New documentation feature request: copy-able link for each section/paragraph in the Specification

[dcj]

I vaguely recall mentioning/discussing this previously, IIRC at that time someone said "Some of the sections are link-able" e.g https://homieiot.github.io/specification/#device-attributes will navigate to section "7.1.1 Device Attributes".
Yes that is true/correct, but:

• That link is not obvious to a casual viewer of the specification, and AFAICT it can't be "copied" in a browser for easily pasting elsewhere.
• IMO the Specification would benefit from more granular links, for example I would like to link directly to the section that documents the description document

I am initiating proposal this as a "discussion", if approved "in concept" then I would move it to an issue, and presumably I will need to do the work and create a PR, but I'm not going to do that unless the powers-that-be are receptive...

[Tieske]

clicking a link in the ToC at the top-right of the page will give you the full section link in the browser addressbar.

[dcj]

clicking a link in the ToC at the top-right of the page will give you the full section link in the browser addressbar.

I stand corrected....

But AFAICT "IMO the Specification would benefit from more granular links, for example I would like to link directly to the section that documents the description document" is not currently supported.

In a Markdown document I am currently writing, I make heavy uses of "headings", and each heading is a link to itself, so it is very easy to copy/grab that link, and use/refer to it elsewhere, e.g. #### [MQTT Broker Authentication](#mqtt-broker-authentication). IMO the table of contents is itself a nice and useful feature, but scrolling up to find it is not as easy as a directly accessible links.

[jacoscaz]

If I understand correctly, GitHub already does this automatically when it parses README.md files into rendered HTLM (see chain symbol that appears whenever hovering on a header). Doing the same on our end shouldn't be (too) hard. I, too, find it very nice for documentation purposes as I often need to link to specific sections of reference documents, particularly when working with specifications.

[jacoscaz]

In fact, we already generate the id, otherwise linking from the ToC wouldn't work:

And here's Hugo's documentation on adding links (second example): https://gohugo.io/render-hooks/headings/#examples .

[jacoscaz]

@dcj probably worth opening an issue / PR in this repo: https://github.com/homieiot/homieiot.github.io .