Compare Gatsby and GitHub heading ID generation

[ty2k]

In many of our document files, we are using a table of contents pattern with links manually added to an "On this page" section that point to anchor tags we manually create and add inline to heading lines. Right now, this works as expected both on GitHub and in our Gatsby implementation. Users come to a table of contents, click a link, and the browser viewport moves to the target.

As an example, look at the chunk of the "Reusable services list" page to see how we are using this pattern for the "Messaging Common service" heading:

## On this page
- [Messaging Common service](#messaging-common-service)
- [Backup Container](#backup-container)
- [BC Address Geocoder](#bc-address-geocoder)
- [Common Document Generation service](#dgen)
- [Common Hosted Email service](#common-hosted-email-service)
- [Common Services Get Token](#common-services-get-token)
- [Fathom](#fathom)
- [go-crond](#go-crond)
- [Matomo OpenShift](#matomo-openshift)
- [OWASP ZAP Security Vulnerability Scanning](#owasp-zap)
- [SonarQube in Private Cloud PaaS](#sq-private-cloud)
- [SonarQube on OpenShift](#sq-openshift)
- [WeasyPrint HTML to PDF/PNG](#weasyprint)

## Messaging Common service<a name="messaging-common-service"></a>
The Common Messaging service (CMSG) is an API for sending messages to internal and external users through SMTP and SMS. You can access the CMSG programmatically through the CMSG-MESSAGING-API. For more information, see the following resources:
* [GitHub repository](https://github.com/bcgov/nr-messaging-service-showcase)
* [About the Messaging Common Service](https://developer.gov.bc.ca/Community-Contributed-Content/About-the-Messaging-Common-Service)
* [Messaging Service Developer Guide](https://developer.gov.bc.ca/Community-Contributed-Content/Messaging-Service-Developer-Guide)

In the snippet above, you can see we are linking to #messaging-common-service and that we have created an anchor tag that the link is hypothetically pointing to: <a name="messaging-common-service"></a>

However, both GitHub and our Gatsby implementation auto-generate IDs for headings. You can see this functionality by hovering over the headings in GitHub, causing a link icon to appear. You can use this to copy the link target, or click it to move the browser to that location and then copy the URL from the browser bar.

On GitHub, the extra <a> tags don't cause any extra cruft in the heading IDs, but Gatsby's remark processor parses these <a> tags into the generated IDs, causing weird output like below: #messaging-common-servicea-namemessaging-common-servicea

Since we are not gaining any functionality by adding these anchor tags manually, I am inclined to move away from using this pattern.

First, do some research and report back in this thread on any edge cases we might need to be aware of if we are going to be linking to auto-generated heading IDs from manually generated table of contents lists. For instance, do headings with special characters have rules that differ in GitHub and Gatsby? With a weird heading with special characters like "What is Keycloak @ BCGov !?", is the expected target the same in both GitHub and Gatsby?

[ty2k]

Our Gatsby implementation is using the official Gatsby plugin gatsby-remark-autolink-headers to generate heading IDs in Markdown source documents. Under the hood, that plugin is using github-slugger, which aims to match the GitHub heading ID generation functionality 1:1.

I've tested a handful of cases to see how special characters are treated, and I can confirm Gatsby and GitHub are generating identical IDs in these cases:

• !? How do we deal with speci@l c#aracters??? becomes #-how-do-we-deal-with-specil-caracters
• Some under_scores and da-shes for no good reason? becomes #some-under_scores-and-da-shes-for-no-good-reason
• Very special characters like á,é,í,ó,ú,Á,É,Í,Ó,Ú,Ñ,ñ becomes #very-special-characters-like-áéíóúáéíóúññ

As such, we have no reason to be adding anchor tags manually to headings in our documentation.

I'm going to do the following to resolve this issue:

• Remove all existing manual <a name=""> anchor tags in our Markdown documents, except in cases where they are being used for something other than a heading (I don't believe there are any edge cases like this, but I will take care to keep them in place if they are genuinely useful).
• Updated the Tech Docs Writing Guide document to include guidance on this topic or change existing guidance.