Hyperlinks to other doc content

[Sidnioulz]

Examples

Datadog Druids

This one not only links to other DS content but has preview cards tailored to the content.

Back Market

Links are made between different pages of the token documentation, so controllable from within the docgen project.

Rationale

Links make documentation so much richer. In particular, linking between tokens that reference each other is useful for discovery. It helps users understand the meaning of a core / semantic token, and helps them understand where a specific core token is used. It can help users to learn a token system and maintainers to decide how to define new tokens and what to connect them to.

Many links between tokens that reference each other could be produced within the documentation project, and external links are easy to support.

Challenges

Supporting link previews or specially-formatted links would require an extra configuration layer and/or a link format to be used by our consumers (and thus, support for that format to at least be written in the source of truth). It would likely need to be debated and, if desired, specified separately from a simpler linking feature.