Stable names for headings and internal <doc:> links

[ktoso]

Feature Name

Stable names for headings and internal doc: links

Description

Other documentation tools like sphinx or asciidoctor frequently offer a way to refer "intra" a documentation page.

For example, I might be discussing a complex topic and another new word might pop up. I don't want to start explaining the new term right away, but want to cross link to the section that explains it:

## Blooping
This is why bloopy is very interesting, we can bloop and blop it (blopping will be explained in more depth in <doc:#bloping>)

@ID { bloping } // some name for this, not sure what's the best `SectionID` or something
## Bloping the Blops 

Bloping is an advanced technique ...

Motivation

Currently one has to manually copy paste and guess around to get the ID of a heading from the TEXT of the heading, like so: #Bloping-the-Blops for Bloping the Blops.

I'm also forced to use <a> rather than rely on <doc:... style syntax.

If the section name ever changes, my link will be broken.

Importance

This is important for advanced features whose documentation has multiple advanced topics and needs to point the user at where they can learn about it if they haven't already.

It also is a popular feature in all kinds of other documentation engines, making porting docs to docc more painful than it has to be.

Alternatives Considered

Hardcoding headings as today -- this is not good, because the links are not stable nor are they validated, leading to big potential for broken internal docs links.

[d-ronnqvist]

I agree that this is a feature that we should add to DocC to make it easier to evolve content over time.

Until then, you can write links to headings using <doc:page-name#heading-name> and get a little but more support from DocC (compared to writing inline html anchor tags):

• DocC can turn #Bloping the Blops into #Bloping-the-Blops for you.
• DocC can warn about documentation links that didn't resolve if the heading text changed. The current warnings only point out that the link failed to resolve but I'm working on some improvements to enable more actionable warnings for unresolved links.

[ktoso]

Thanks! Good to hear that format works, I'll give it a shot, improvements would be welcome -- the improved resolver looks like a good step as well 👍

[QuietMisdreavus]

Some Markdown implementations (e.g. PHP Markdown Extra) have a special syntax for adding a custom id to a heading:

## This is my heading {#my-heading}

swift-cmark (the fork of GitHub-Flavored Markdown that Swift-DocC uses) doesn't support this, but something like this could be added.

Also related is apple/swift-markdown#83, which is more about adding id attributes anywhere, rather than customizing existing header anchors.