docs: fix anchors in markdown doc file

[artellador]

---

title: "docs: fix anchors in markdown doc file"

Anchors to headings were failing. After taking a look, I saw there were HTML anchor elements defined, but it seems after rendering the HTML, the "user-content-" prefix was being added.
With the proposed solution the links work but it is far from perfect, because it scrolls below the anchor. Enough as a quick fix, but can be improved. To make it better, probably we would need to replace all the anchors and use the ones generated by GitHub by default (that is, the heading text in lowercase, replacing spaces with "-").
My two cents to an interesting project :)

---

Related issue(s):

---

[github-actions]

Welcome to AsyncAPI. Thanks a lot for creating your first pull request. Please check out our contributors guide useful for opening a pull request.
Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.

[derberg]

thanks for taking time to fix it

tbh, technically I think these a elements can actually be entirely removed as GitHub add these anyway, we just duplicate them. I have a theory we have these a elements as legacy from OpenAPI from old times when GitHub did not support autogeneration of a for headers

look, if you do this

## <a id="test"></a>Definitions

you will get this

<h2 data-sourcepos="87:1-87:31" dir="auto">
  <a id="user-content-definitions" class="anchor" aria-hidden="true" tabindex="-1" href="#definitions"><svg class="octicon octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true"><path d="REDACTED"></path></svg></a>
  <a id="user-content-test"></a>
    Definitions
</h2>

for few years GitHub was generating id without this additional text like user-content but then like...I think 2y ago they started doing it.

so yeah, I basically think the best would be just to entirely remove stuff like <a id="test"></a> from markdown headers cause we do not need them, GH generates them anyway. They follow approach to lower case and add - so Operation Bindings Object becomes user-content-operation-bindings-object but cool think is that internally the translate them and #operation-bindings-object also works like a charm

Also GH adds the chain icon on hover that you can click to get a link to the section

and the link it generates, uses the GH generated href, not the one that we assume we control with custom a

@fmvilas do you remember maybe, is there a reason to keep these a elements other than inside tables, like <a name="messageExampleObjectHeaders"></a>headers? is it legacy from OpenAPI or some other thing?

[artellador]

I though about rewriting all the anchors making use of the GitHub autogenerated anchors, but I didn´t want to remove elements explicitly added there, just fix what was broken.
Once you take a decision, if you opt for the autogenerated ones, if I have a gap, I´d make another PR.

[fmvilas]

@derberg this was done in the times when GitHub didn't support them in the headers (or they generated a different id). I think we can safely remove them. Let's make sure that the website doesn't rely on them. If that's the case, website should generate these itself instead.

[derberg]

@fmvilas thanks, yeah website generates its own ToC afaik.

@artellador you can go ahead and make proper adjustments

[sonarcloud]

Quality Gate passed

Issues
0 New issues

Measures
0 Security Hotspots
No data about Coverage
No data about Duplication

See analysis details on SonarCloud

[derberg]

@artellador fyi, if you do not ping me (with a comment or rerequesting review) that the PR is ready for review - I will not know. Especially that you did few commits. So please specify whenever you are ready for final review