Using link reference definitions as invisible structural markers — sound, or a bad idea?

Extensions
1

I’m designing the file format for a tool that round-trips rich documents to and from Markdown. Some blocks have no Markdown form (tabbed content, a few attribute-bearing containers), and I need to carry their structure in the file losslessly while keeping the file readable as plain CommonMark in any viewer — GitHub, GitLab, VS Code, Obsidian, anything.

I’d like a sanity check on the carrier I’ve settled on before I commit to it.

The idea

Use a link reference definition with a fixed label and the payload in the title:

[meta]: # (tabs default="0")

**First tab**

[meta]: # (tab-body)

Body of the first tab, ordinary Markdown.

[meta]: # (/tab-body)

**Second tab**

[meta]: # (tab-body)

Body of the second tab.

[meta]: # (/tab-body)

[meta]: # (/tabs)

Per the spec, a link reference definition “does not correspond to a structural element of a document”, so a compliant parser registers the label and emits nothing. The titles become bold lines, the bodies stay ordinary Markdown, and the structure is recoverable by anything that knows to read [meta] definitions. Everything renders as sensible prose everywhere else.

I chose this over raw HTML tags (<x-tabs>) because tag stripping is a sanitiser policy — GitHub unwraps unknown elements, Azure DevOps escapes them — whereas a definition disappears at the grammar level, before any sanitiser runs.

What I’ve verified so far

  • Rendered through GitHub’s own /markdown API: invisible, and the Markdown between markers (lists, fences, tables, emphasis) is unaffected.
  • Parsed with remark, markdown-it and marked: each marker is a definition node; scaling from 1,000 to 10,000 definitions is linear in all three (no quadratic behaviour), and cmark’s pathological suite already covers 25,000 colliding reference labels.
  • The rules I have to honour: blank line before a marker after prose (a definition cannot interrupt a paragraph), never indent it 4+ spaces (becomes a code block), and escape ) in the payload since it terminates a parenthesised title.

Where I’m unsure, and would value opinions

  1. Are there compliant parsers that still emit or display unused definitions? I found one home-grown parser whose regex only accepted definitions without a title, so [//]: # 'x' rendered as text. Is the title the part of this construct most often half-implemented in the wild, and should I avoid relying on it?

  2. Same label repeated hundreds of times. The spec says the first definition wins for resolution; I never reference it, so I don’t care which wins. Does any implementation warn, dedupe, or otherwise object to hundreds of duplicate labels? Linters aside.

  3. Collision with the author’s own definitions. If someone writes [text][meta], it resolves to my marker and renders as a link to #. I’m using a namespaced label to make that unlikely. Is there a better convention than picking an unlikely label?

  4. Is this considered an abuse of the construct? [//]: # (comment) is a known idiom for comments; I’m extending it to carry structured payloads at volume. I’d rather hear “don’t” from people who maintain parsers than discover it later.

  5. Formatters and linters. I’ve checked two: Prettier keeps all definitions in place but normalises the title delimiter ((x) → "x", or 'x' when the payload contains a double quote) — so I plan to emit Prettier’s preferred form to stay byte-stable. markdownlint fires MD053 (unused definition) on every marker, which I’d document as a one-line config. Do mdformat, remark-stringify, or any editor’s “organise definitions” feature hoist definitions to the end of the file? That would destroy the positional pairing, and I’d rather know now.

Happy to share the small benchmark script if useful. Thanks.