Code Reading (Docusaurus)
Tags: osd600
Published: 2023-10-30 23:08:21

For my study week I was tasked with reaviwing on of the For my study week, I was tasked with reviewing one of the Docusaurus features in order to implement it in my own project.

The feature I found to be very cool is [Syntax Highlighting for code blocks](https://docusaurus.io/docs/markdown-features/code-blocks) if we go to Docusaurus official page linked above we can see that it uses Prism React Renderer with custome themes.

Here is a small example of how this would work with Markdown:

```jsx
function HelloCodeTitle(props) {
  return <h1>Hello, {props.name}</h1>;
}
```

We can do this by encapsulating the code block in triple backticks (```) followed by a language identifier at the beginning, like so (```jsx).

The implementation is done by the library, so there is not much to explore, but we can still see how Docusaurus uses/configures Prism.

If we go to lines [24 - 25](https://github.com/facebook/docusaurus/blob/10897416dc7d44d4b47579491844ba1894757c2d/website/docusaurus.config.ts#L24), we can see custom themes for Prism that can be found in the [utilities folder](https://github.com/facebook/docusaurus/tree/10897416dc7d44d4b47579491844ba1894757c2d/website/src/utils). For example, we can see in both light and dark themes that they always extend the base theme that goes with Prism. You can see it [here](https://github.com/facebook/docusaurus/blob/10897416dc7d44d4b47579491844ba1894757c2d/website/src/utils/prismDark.ts#L17)

Also, as explained, as can be seen in the example website, Docusaurus has whenever Fenced Code Blocks are parsed in Markdown, you can see that as per Prism documentation, Docusaurus first creates a "pre" tag with the language class and then adds a container with code lines inside.

example: 

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/cu8cfse51g1crkt5xeh4.png)

Now, lastly, let's see how Docusaurus parses Markdown Code Blocks, which can be seen  [here](https://github.com/facebook/docusaurus/blob/4e150d2b8247d44e964272e9a1a52a212d47ec01/packages/docusaurus-utils/src/markdownUtils.ts#L66).

```ts
export function unwrapMdxCodeBlocks(content: string): string {
  // We only support 3/4 backticks on purpose, should be good enough
  const regexp3 =
    /(?<begin>^|\n)```mdx-code-block\n(?<children>.*?)\n```(?<end>\n|$)/gs;
  const regexp4 =
    /(?<begin>^|\n)````mdx-code-block\n(?<children>.*?)\n````(?<end>\n|$)/gs;

  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  const replacer = (substring: string, ...args: any[]) => {
    const groups = args.at(-1);
    return `${groups.begin}${groups.children}${groups.end}`;
  };

  return content.replaceAll(regexp3, replacer).replaceAll(regexp4, replacer);
}

```
The approach is, in fact, what you would expect: 2 regexes for 3/4 backticks to cover most of the scenarios.

I believe this covers all the information I needed to create an implementation of this feature for my project.

Finally, let's talk about the strategies I used to read the code. It was a typical process that I think everyone has used, which is isolating the area that you want to review. In my example, it was Code Block highlighting, so I went using GitHub Code Search to find all related files. Since it was pretty much what I needed, I started going through the files and found that Docusaurus passes parsed Markdown to Prism, and that was it. I also found searching for issues related to your topic helpful because more knowledgeable people leave a lot of explanations and discussions of the feature.

To the question "Did you need to use AI to help?" I say no, as in order to use it on such a big project, I would have to spend a lot of time providing it with the context. I could better invest myself to get a better understanding of the feature rather than an overview. Yes, it can be helpful when you want a quick answer to a general question, but it fails to provide a detailed overview. So using AI is better left for helping in understanding smaller questions, such as code blocks.