Official support for custom HTML Markdown anchors

[Marcono1234]

Select Topic Area

Question

Body

Is it documented somewhere whether GitHub officially supports custom HTML anchors in Markdown? For example, in some cases it might be desirable to create anchors without creating a Markdown header, or with a custom anchor ID which can be used for permalinks, regardless of whether the corresponding header is renamed later.
For example:

# <a id="my-anchor"></a> Some header text which could change in the future

Apparently GitHub does support <a> with custom id and name (though name is deprecated).

The important question is however if this is officially supported (similar to the <details> tag), or whether the libraries GitHub is using for Markdown rendering just happen to support this, but the behavior might change in the future.

In the past it looks like the behavior for this also changed; previously it was possible to use uppercase letters in the anchor (e.g. <a name="TOC-Overview"></a>), but that is not possible anymore since a few months (?)¹. However, all lowercase anchors (including -) still seem to work.

Footnotes

1. Actually, anchors with uppercase letters still kind of work; GitHub still emits them in the HTML, but it does not scroll there anymore. Because GitHub prefixes these anchors with user-content- you could still use ...#user-content-TOC-Overview but that seems to directly scroll to that HTML element, not accounting for the floating headers at the top and therefore being cut off. ↩

[MichaelChirico]

This should be higher priority -- relying on the exact wording of anchors to generate links is extremely brittle. Any minor copy-edit has the capacity to silently break any number of downstream references.

[Marcono1234]

The GitHub documentation now describes custom anchor support, but it is not clear if this is actually a supported feature or just a description of the observed behavior from a non-GitHub employee, see github/docs#36577.