Open jaune162 opened 2 months ago
That would be a really cool feature, and I'd definitely use something like that if it were so simple. Meanwhile, you could potentially do it with the Custom Magic Comments functionality (https://docusaurus.io/docs/3.0.1/markdown-features/code-blocks#custom-magic-comments), converting it to numbers with CSS.
This approach seems difficult to implement. I think there has two way to implement this feature.
CodeBlock/Line
swizzle I think the latter is better,but I don't know how to register a Prism plugin in docusaurus config.
There is the simple implement. but just code-block
import React from 'react';
import clsx from 'clsx';
import type { Props } from '@theme/CodeBlock/Line';
import styles from './styles.module.css';
import type { TokenInputProps, TokenOutputProps } from 'prism-react-renderer';
export default function CodeBlockLine(
{
line,
classNames,
showLineNumbers,
getLineProps,
getTokenProps
}: Props): JSX.Element {
if (line.length === 1 && line[0]!.content === '\n') {
line[0]!.content = '';
}
const lineProps = getLineProps({
line,
className: clsx(classNames, showLineNumbers && styles.codeLine)
});
const lineTokens = line.map((token, key) => {
console.log(token, key);
return (<span key={key} {...getCommentCalloutTokenProps({token, key}, getTokenProps)} />)
});
return (
<span {...lineProps}>
{showLineNumbers ? (
<>
<span className={styles.codeLineNumber}/>
<span className={styles.codeLineContent}>{lineTokens}</span>
</>
) : (
lineTokens
)}
<br/>
</span>
);
}
const commentCalloutRegex = /^(\/\/\s+)(<)(\d{1,2})(>)$/;
function getCommentCalloutTokenProps(input: TokenInputProps, original: Function): TokenOutputProps {
if (input.token.types[0] === 'comment' && input.token.content.match(commentCalloutRegex)) {
const matches = input.token.content.match(commentCalloutRegex)
return {
className: styles.commentCallout,
children: matches[3]
}
} else {
return original(input);
}
}
.commentCallout {
border-radius: 100%;
display: inline-block;
font-family: Roboto, sans-serif;
font-size: 1rem;
font-style: normal;
color: white;
background-color: black;
border: 1px solid black;
height: 1.25em;
letter-spacing: -.25ex;
line-height: 1.2;
text-align: center;
text-indent: -.25ex;
width: 1.25em;
}
The follow code
public class A { // <1>
public static void main(String[] args) { // <14>
System.out.println("");
}
}
Redner as:
But not elegant enough.
- a prism plugin
I think the latter is better,but I don't know how to register a Prism plugin in docusaurus config.
Hey @jaune162! I'm not really into frontend stuff, but I used Docusaurus for project documentation and made some tweaks, like adding magic comments. They're registered in the section where you can add the Prism plugin you mentioned.
I don't have any plugins set up, but I added an example line in my config to show how it would look.
There are repositories doing that, please see examples.
So, if option 2 is the way to go, it looks like it might be possible. What do you think?
@baldram Thanks. I will try it.
But there is no plugins
option in the source code.
export type PrismConfig = {
theme: PrismTheme;
darkTheme?: PrismTheme;
defaultLanguage?: string;
additionalLanguages: string[];
magicComments: MagicCommentConfig[];
};
I'm not sure is works.
@jaune162 Maybe in the repositories I found (some using Docusaurus 3.x), someone tried this, but it doesn't seem to work. 🤔 From the discussion here, it looks like it's nontrivial indeed, and people are hacking it in different ways. There's also a note for developers there.
Afaik the lib we use (prism-react-renderer) does not support Prism plugin.
I implemented this using @jaune162 's approach overall with swizzle eject, but went a different direction. I wanted auto-counting and I wanted the callout indicators to always be on the left side.
I also needed to have callouts on lines where comments weren't possible (XML). asciidoc also has this issue. To work around this, I used magicComments
and overrode the highlighting default:
magicComments: [
{
className: 'theme-code-block-callout-line',
line: 'callout-this-line'
}
]
The code-block starts off with:
```xml {1-5,8,11-13} showLineNumbers
And the result is:
Callouts outside of code blocks were created with a separate component and put into the doc like so:
<Callout id="1" /> `Window` is the root element consisting of the title bar, frame, and caption buttons drawn by the OS (by default).
I'm going to detail some different designs / use cases that I stumbled into during the above implementation and might be considered by a feature implementer:
I also needed to have callouts on lines where comments weren't possible (XML). asciidoc also has this issue
These are valid concerns.
To work around this, I used magicComments and overrode the highlighting default
In my case, the solution (inline comments) presented in the first comment will still be more convenient because the documents are not written manually. Code snippets are automatically extracted from the code based on appropriate markers. But it's not a big challenge. In this case, the parser generating the documentation will have to interpret the markers, remove them from the code, and replace them with the call as you showed.
I would probably feel better without auto-counting. It would be preferable if they could be specified explicitly (because, in practice, we will be marking individual lines anyway). However, this relies on different functionality that works the way it does, and we can't change that I guess. Besides, it's a very interesting approach.
Have you read the Contributing Guidelines on issues?
Description
Example: https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#literals-and-source-code
Has this been requested on Canny?
No response
Motivation
This feature is very useful for explaining the complex parts of the source code in the document
API design
No response
Have you tried building it?
No response
Self-service