Adding named anchors in docs

[Saviq]

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 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:

Content.

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; }
</code></pre>

var foo = "bar";
function baz() { return null; }

And a link to it

Unfortunately syntax highlighting currently broken:

Code block syntax highlighting no longer works

#include <stdio.h> #include <stdlib.h> int main(int argc, char* argv[]){ printf("Hello syntax hightlight?\n"); return EXIT_SUCCESS; } The commonly used YAML highlighting also failed recently /cc @admins

[degville]

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:

https://github.com/canonical-webteam-archive/docs.snapcraft.io/issues/33

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.

[galgalesh]

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:

Using external metadata

To help avoid unnecessary duplication, and for convenience, Snapcraft can process and incorporate external metadata from within snapcraft.yaml by using parse-info within a part and a corresponding adopt-info key. For example, the following snapcraft.yaml will parse a file called metadata-file. Snapcraft will attempt to extract version, summary and description metadata for the snap, all of which are mandatory: name: my-snap-name adopt-info: part-with-metadata parts: part-with-metadata: p…

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…

[Saviq]

@galgalesh

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