Markdown footnotes in HTML: keep the reference and its return link together

Keep each instruction connected to its supporting note and its return links.

The note number looks correct, but clicking it goes nowhere. Render footnote references and definitions with the same parser extension, then retain both sets of generated IDs. A superscript number alone is not a working reference.

Start with a fictional workshop instruction whose supporting note explains a supplied packing rule. Keep that note in the Markdown original:

Packing note: repeated references and both return links
Packing note: repeated references and both return links
Open the full example ↗

Open the complete example · Download the full HTML source

Each tray holds six items.[^packing]

[^packing]: Fictional exercise rule, not a warehouse specification.

The reader needs two movements: from the instruction to its explanation, then back to the instruction. Check both before treating the HTML as a finished reading copy.

Enable the footnote extension explicitly

The markdown-it-footnote README documents definition-style notes, inline notes, the generated reference links, and backlinks. In a browser with matching distributions loaded:

const parser = window.markdownit({html: false})
  .use(window.markdownitFootnote);
const rendered = parser.render(source);

source is your complete Markdown string. Supply the extension before rendering. A parser without this extension should not be assumed to understand the same notation merely because another Markdown preview did.

The plugin's documented output links a reference such as fnref1 to its note entry, then links the note back to the reference. Treat those IDs as generated relationships, not permanent identifiers for an external citation system.

Check destinations instead of counting superscripts

For every reference link, read its fragment destination and confirm that an element with that ID exists in the delivered document. Follow its backlink and confirm that the corresponding reference still exists.

Repeated references deserve a separate check. One note definition can be referenced more than once; keep the resulting return destinations associated with the actual generated references. Do not hand-edit every backlink to the first number because the printed note text is shared.

If several independently rendered fragments will share one document, inspect the combined IDs for collisions. A fragment that worked alone can conflict with another fragment's IDs. Choose a documented ID customization or a deliberate namespace policy before combining the outputs.

Preserve the relationship during delivery

Keep the footnote section, reference IDs, fragment links, and reading styles in the exported HTML. Copying only the visible paragraph omits its destination. Copying only the note section omits the instruction the reader needs to return to.

The existing Markdown conversion guide explains wrapping a fragment into a page. The TinyMCE footnote guide concerns an editor's insertion and maintenance controls. This recipe converts Markdown source with a named parser extension; it does not run that editor or claim its subscription features.

For review in NOS, keep the source note alongside the reading copy. Ask the reviewer which sentence the explanation supports. A working backlink makes navigation possible; the author still needs a real source before replacing the fictional exercise note with an operational assertion.

Keep reading