Adding named anchors in docs

Hey all,

I often find myself trying to refer to a particular section in the Snapcraft docs and find that there’s no named anchors there (i.e. those allowing a #some-heading in the URL to scroll the browser down there).

As an example, GitHub does this automatically by creating a named anchor from the heading text itself. That would be a huge gain in itself. It also displays a :link: icon on hover on the left of the heading to let the viewer know there’s an anchor and let them get the link for it.

Where applicable, explicit named anchors may also be used in Markdown:

<a name="content"></a>Content.

[And a link to it](#content)

Which translates to:


And a link to it

It’s trickier to add in code blocks, but also possible:

<pre><code class="lang-javascript">var foo = "bar";
<a name="baz"></a>function baz() { return null; }
var foo = "bar";
function baz() { return null; }

And a link to it

Unfortunately syntax highlighting currently broken:

Thanks for bringing this up, and I totally agree - ideally, I think it would be great to have named anchors automatically generated from headings and subheadings.

It’s an issue that has come up before:

With the above issue, there didn’t seem to be a simple solution, but I think it’s worth revisiting to see if we can either find a new solution (possibly a Discourse addon?), work something into the publishing backend, or maybe standardise on marking up headings to generate the deep links.


Just a note that I’ve been explicitly adding these to every heading that I want to link to, the appstream heading as an example:

This is what it looks like in code:

<h3 id='heading--appstream'>AppStream<sup><a href=#heading--appstream>⚓</a></sup></h3>

(For some reason, browsers seem to find the position of the link better if it’s the id of a header instead of the name of a link.)

The advantage of doing these explicitly is that they don’t break when you change the heading name. However I understand that readers/users also want to link to content and won’t think of creating an anchor themselves…

I think this may very well be a policy - you’re totally right that changing headings would break the anchors, so maybe being explicit is indeed better.

I would, however, recommend the # <a name="heading-title"></a>Heading Title approach (as per the answer to the above stackoverflow question).

It also allows for maintaining backwards compatibility:

# <a name="heading-title"></a><a name="old-heading-title"></a>Heading Title

Heading Title

New Link, Old Link