Feature request: automatically generated ids for headers

17

I suggest adopting Wikipedia’s section anchor scheme, which takes the text of the header and converts it to a valid id:

  1. spaces => _
  2. certain punctuation is converted to character entity references
  3. second and following duplicate headers are appended with _2 to _n suffixes (N.B.: the first instance is unchanged.)
  4. header depth is ignored

This would allow authors to refer to headers without imposing any extra syntax:

# A good place to start

...

Please begin at [the beginning](#A_good_place_to_start).

Downsides:

  • The requirement for unique ids (point #3) means that the converter will need to keep track of duplicate header names. Further, if there are multiple Markdown documents on a single page, the page will need to be validated to be sure that no documents duplicate the same ids. These are concerns with any system that allows URL fragments in Markdown, however. (This leads me to believe that link anchors should be an extension and not part of the core standard.)

  • Edits to the header text will break links (both internal and external). This could be solved by adding manual anchors and creating redirects (which is what Wikipedia does). If authors are able to specific anchors manually, they could future-proof their own documents at the cost of giving up the convenience of automation. (Again, this seems more appropriate for an extension that also adds manual anchors.)

On the plus side:

  • Authors can predict what ids will be generated. And perhaps more importantly, so can their authoring tools. (Though, again, #3 complicates matters.)

  • Editors can reorganize a document without breaking it as long as they don’t change the text of the header. (Oh, they also need to be careful not to rearrange the order of duplicate headers. Sigh.)

  • People familiar with Wikipedia section links will feel at home.

  • There is a pleasing parallelism between the syntax of ATX headers and the links to them.

2 Likes