Best way to create annotations/comments for code blocks?

[C-Loftus]

I am working on documenting a config file where I want to add comments to each line without actually adding them in the file or putting it all in a paragraph / table after the code block. It would be awesome if there was a way to show the comments next to or above the line by hovering the line or clicking a button would be great.

This is doable in quarto and a brief example can be found here: https://quarto.org/docs/authoring/code-annotation.html

What is the recommended way of doing this in Docusaurus? It appears the feature request had some discussion but I am unclear if anything came of it.
https://docusaurus.canny.io/feature-requests/p/annotationscomments-for-code-blocks

I know you can swizzle components but I am not sure if there is an easier way or if anyone has accomplished this previously.

Thank you!

[slorber]

We don't provide that feature out of the box.

The possible ways to implement that are through a remark/rehype plugin (only works in Markdown code blocks), or by swizzling the CodeBlock component, or by creating your own custom code block component to replace the code block component we use for Markdown code blocks (@theme/CodeBlock).

I agree this feature would be useful, but it can be implemented in userland. If someone implements it first in userland, and the implementation is successful, we might as well merge it back in Docusaurus.

[C-Loftus]

Sounds good. I am going to try out https://codehike.org/docs/installation/docusaurus for the time being as a replacement to the code block component since it seems to do most of what I need.

[slorber]

👍

See with @pomber for how to integrate it properly. I'm not sure this docs page is super up to date considering we are now using MDX v3.

Also Docusaurus v3.5 (upcoming release) will contain recmaPlugin config, which @pomber requested (see #10237)

[pomber]

I recommend you try codehike v1 (beta) with Docusaurus, here's an example project: https://github.com/code-hike/examples/tree/with-docusaurus/with-docusaurus.

Full codehike v1 support will come with Docusaurus v3.5, but your use case should work as it is now. See the new codeblocks docs and the code annotations docs.

If you have any questions you can open an issue/discussion in the codehike repo.