Support asciidoc source code callouts in CodeBlock

[jaune162]

Have you read the Contributing Guidelines on issues?

• I have 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

• I'd be willing to contribute this feature to Docusaurus myself.

[baldram]

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.

[jaune162]

This approach seems difficult to implement. I think there has two way to implement this feature.

1. Eject a CodeBlock/Line swizzle
2. a prism plugin

I think the latter is better，but I don't know how to register a Prism plugin in docusaurus config.

[jaune162]

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.

[baldram]

2. 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?

[jaune162]

@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.

[baldram]

@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.

[slorber]

Afaik the lib we use (prism-react-renderer) does not support Prism plugin.

• Document how to use Prism Plugins / add Prism diff-highlight plugin #3318
• Add support for diff-highlight FormidableLabs/prism-react-renderer#90