Links in Code Examples (via magic comments)

[nathan-contino-mongo]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Description

Clickable links in code samples. The Firebase documentation uses a similar system for linking code snippets to configuration information: https://firebase.google.com/docs/web/setup#add-sdks-initialize

Example:

The bottom of this section of the doc mentions that the magic comment system could extend in the future for additional markup use cases. I believe this is one potential use case for an extension of that system.

Has this been requested on Canny?

No response

Motivation

In many cases, it makes more sense to surface links through prose or an admonition before or after a code block. But sometimes this:

• takes up valuable vertical space on an already long page
• clutters up a page that already contains lots of admonitions
• creates confusion for users when examples are long and/or need multiple outward links

API design

I'm not super familiar with the implementation for the magic comment system. But right now, that system uses the following syntax for highlights:

// highlight-start
highlighted text
// highlight-end
not highlighted text
// highlight-next-line
highlighted text

I imagine we could extend these magic comments to use an uncommon keyword for linking to a docusaurus ID, with a link name and reference as arguments provided in the markdown format:

// docs-link [Link to something](/absolute/path/to/{id})

Have you tried building it?

no

Self-service

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

[Josh-Cena]

Sounds cool to me!

To be clear, we won't make this the default behavior, because I don't feel like this will be used by a lot of users; this requires having some ad-hoc Markdown parser on client-side, so the effort is non-trivial and probably means bundle size bloat. However, we will make the magic comment system extensible (which it currently isn't) so you can more easily build this in userland through swizzling CodeBlock.

[slorber]

I plan to refactor CodeBlock already so this will become even simpler: swizzle CodeBlock/Line and transform the line to whatever you want (ie transform comment string to JSX)

Was wondering: do we have an need for this in our own doc? We could add it to dogfood and improve our doc DX, just need to figure a few good places to use this.

[Josh-Cena]

Oh... I just realized this will not be a normal magic comment either! Because the definition of a "magic comment" is something that adds metadata about the next line (e.g. highlight, collapsible), and it will be removed. So we can't even use the magic comment system here. @slorber We can close this as soon as you make that refactor 👍

[Josh-Cena]

Now that #7175 is merged, this should be able to be implemented in userland.

[nathan-contino-mongo]

Thank you @Josh-Cena