How to give a custom ID to a heading?

Application
1

On GitHub, I want to manually provide the value of the HTML ID attribute to a heading (instead of it being generated from the name of the heading), so that if I change the heading in the future, the links that people bookmarked will still link to the same place.

Some sources mention doing it as # Hello {#custom-id}, but I think this does not work on GitHub.

GitHub converts # Hello to the following HTML:

<h1>
  <a id="user-content-hello" class="anchor" aria-hidden="true" href="#hello">
    <svg class="octicon octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true">
      <path
        fill-rule="evenodd"
        d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z">
      </path>
    </svg>
  </a>
  Hello
</h1>

I can use the HTML <h1> and give it a custom ID, but the anchor inside will not point to the custom ID:

In:

<h1 id="custom-id">Hello</h1>

Out:

<h1 id="user-content-custom-id">
  <a id="user-content-hello" class="anchor" aria-hidden="true" href="#hello">
    <svg class="octicon octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true">
      <path 
        fill-rule="evenodd"
        d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z">
      </path>
    </svg>
  </a>
  Hello
</h1>

This defeats the purpose because when people click on the anchor and bookmark it, the bookmark will have the current name of the heading, instead of the custom ID that I provided.

Putting an anchor in heading manually does not work either:

In:

<h1 id="custom-id">
  <a href="#custom-id"></a>
  Hello
</h1>

Out:

<h1 id="user-content-custom-id">
  <a id="user-content-----hello" class="anchor" aria-hidden="true" href="#----hello">
    <svg class="octicon octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true">
      <path 
        fill-rule="evenodd"
        d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z">
      </path>
    </svg>
  </a>
  <a href="#custom-id"></a>
  Hello
</h1>
2

For what it’s worth, Pandoc, Markdig and MMD create a link to the anchored heading here:

## Föo

[text][Föo]

Cebe, Kramdown, Markdig, Maruku, Pandoc and PHP MD Extra support a manual override:

## Foo ## {#bar}

[text](#bar)
3

Two observations here. The first is that this sounds like a great idea for an extension, and to get the “what is a feature and what is an extension” discussion kicked off.

The second is that I would actually like an extension that specifies:

  1. the “formula” for folding down the text and/or how to refer to it from within the same document
  2. how to override default behavior.