update (right-hand side) TOC template to use custom anchors

[thaJeztah]

• relates to engine: update reference docs to use new anchor tags #16460 (comment)

We use a custom liquid template to generate the right-hand (in page) TOC. This code currently generates anchor-links based on the headings themselves. For the reference documentation, we started using custom anchors based on the flags that they relate to. For example;

docs/_data/engine-cli/docker_build.yaml

Line 573 in 4ef5b48

### <a name="tag"></a> Tag an image (-t, --tag)

With those custom anchors, both the "generated" anchor (#-tag-an-image--t---tag) and the custom (#tag) anchors can be used. The custom anchors allow us to have a predictable anchor, even if the heading is rephrased.

We should update the liquid code to understand the custom anchors, so that the TOC uses them, and so that users can bookmark those links without risking them to change if the headings are changed.

❓ Why not us liquid annotations ({: id=custom-anchor } for these?

We need to use the (hacky) <a name=...></a> because those pages are generated from Markdown pages in upstream repositories. We want those pages to be browsable / readable on GitHub, which doesn't support the liquid annotations. The <a id=...> HTML tags work both on GitHub and in HTML generated by Jekyll (although Jekyll itself doesn't know about them).

[thaJeztah]

/cc @crazy-max 😄

[docker-robot]

There hasn't been any activity on this issue for a long time.
If the problem is still relevant, mark the issue as fresh with a /remove-lifecycle stale comment.
If not, this issue will be closed in 14 days. This helps our maintainers focus on the active issues.

Prevent issues from auto-closing with a /lifecycle frozen comment.

/lifecycle stale