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?