Skip to content

backlink-anchor-format.md

Latest commit

 

History

History
35 lines (23 loc) · 2.8 KB

backlink-anchor-format.md

File metadata and controls

35 lines (23 loc) · 2.8 KB

Link anchors

The numeric markers in the text can be clicked to jump down to the corresponding item in the reference list, and back. This is done with <a href="#…"> links targetting matching id="…" anchors.

Warning: You know that e.g. < and " need to be "HTML escaped" in both href="…" and id="…". In addition, the browser will apply URL decoding to href="…". You need to URL encode href="…" but not id="…" to make them work together seamlessly. AnchorFormatter implements this.

Down to the footnote

The anchor to jump down to a list item is prefixed cite_note-, followed by:

  • For unnamed references: The numeric id of the reference, e.g. cite_note-1.
  • For named references: The reference's name, a dash, and the numeric id, e.g. cite_note-Britannica-2.

Warning: A reference's name alone is not necessarily unique because of additional underscore normalization (see AnchorFormatter::normalizeFragmentIdentifier). For example, name="a b" and name="a__b" are different names that both become cite_note-a_b-… as an anchor. Only the additional id makes them unique.

This is implemented in AnchorFormatter::getNoteIdentifier, used by both parsers.

Back up to the article text

The anchor to jump back up to one of possibly multiple footnote markers is prefixed cite_ref-, followed by:

  • For unnamed references: The numeric id of the reference, e.g. cite_ref-1.
  • For named references that are not re-used: The reference's name, an underscore, numeric id, a dash, and a zero, e.g. cite_ref-Britannica_2-0.
  • For named references that are re-used: As above, except with any number in place of the zero.

This is implemented in AnchorFormatter::getBacklinkIdentifier, used by both parsers.

Additional notes:

  • As above, the name alone is not necessarily unique.
  • The underscore normalization happens for historical reasons because the legacy parser creates links by parsing wikitext like [[#cite_note-a b-1]]. The MediaWiki parser enforces some normalizations on such wikitext. Parsoid re-implements this behavior only for compatibility, but doesn't really need to for any technical reason.
  • The numeric identifier is global per document and increments for any <ref> tag in the document, no matter which group. This is not the same as the number visible in the footnote marker.
  • Re-uses are 0-based. This is only for historical reasons and could as well be changed to be 1-based.

History

  • Historically, it was possible to customize the cite_note- and cite_ref- prefixes. This was (almost) unused and removed in 2024.
  • Incomplete <ref follow=…> (relevant for Wikisource) got anchors in just another format, e.g. cite_note-Britannica. This was unused and removed in 2025.