Links in Code Examples (via magic comments)

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]

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.