Are custom anchors in GitHub Markdown an officially supported feature?

[Marcono1234]

Code of Conduct

• I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#custom-anchors

What part(s) of the article would you like to see updated?

Section "Custom anchors"

I don't necessarily want the section to be changed, but rather would like to know if custom anchors are really officially supported by GitHub-flavored Markdown.
#33531 which added this section seems to have been written by a non-GitHub employee, and also #33531 (comment) by a GitHub employee rather sounds like this is just describing the current behavior, without actually giving any guarantees.

For reference, GitHub's handling of custom anchors was changed in the past and did break custom anchors in multiple projects, see https://github.com/orgs/community/discussions/50962.

Additional information

No response

[subatoi]

Thanks for raising an issue, @Marcono1234—I'll look into this in case there's something in our docs that needs to be changed.

For reference, GitHub's handling of custom anchors was changed in the past and did break custom anchors in multiple projects, see https://github.com/orgs/community/discussions/50962.

Can you give me an example of where custom anchors were broken? I tested this and I couldn't replicate the behaviour you described in that linked issue.

[subatoi]

@Marcono1234 I can confirm the anchors themselves aren't an officially supported feature. I'll leave this open for now to give you time to have a look at the question above, but otherwise this issue will be closed soon.

[Marcono1234]

Can you give me an example of where custom anchors were broken? I tested this and I couldn't replicate the behaviour you described in that linked issue.

See google/gson#2286, and try for example the TOC links at the top of https://github.com/google/gson/blob/gson-parent-2.10/UserGuide.md; I am rather certain that they did work at some point in the past (but unfortunately the Web Archive does not have such an old version of that GitHub page archived).

Though weirdly enough with a quick GitHub code search I found for example https://github.com/cinar/checker/blob/ea60113fa1f75da6d2aa8a00010bbbcc15448fee/DOC.md where uppercase custom name anchors do work.
So I am not completely sure why it does not work for the Gson UserGuide.md.

---

I can confirm the anchors themselves aren't an officially supported feature.

Should the GitHub documentation then clarify this? Otherwise users might rely on this too much, and are then annoyed when the GitHub Markdown processing changes and their custom anchors don't work anymore.

[subatoi]

See google/gson#2286, and try for example the TOC links at the top of https://github.com/google/gson/blob/gson-parent-2.10/UserGuide.md; I am rather certain that they did work at some point in the past (but unfortunately the Web Archive does not have such an old version of that GitHub page archived).

I'm confused, because those anchors don't match the headers? For example #TOC-Goals-for-Gson isn't equivalent to the slugified version of Goals for Gson because it has TOC- in front of it. Did that previously work?

(Edited) My apologies, I misread and completely mixed this up with another piece of work.

I've taken another look at it now and I can see exactly what you mean.

Should the GitHub documentation then clarify this? Otherwise users might rely on this too much, and are then annoyed when the GitHub Markdown processing changes and their custom anchors don't work anymore.

I'll investigate whether there's anything we can do to avoid this sort of situation in the future and what exactly happened, but I can't commit to that specific resolution.

Since we've resolved the original question, I'm going to close this issue out. Thank you for reporting it.