Compare Gatsby and GitHub heading ID generation about platform-developer-docs HOT 1 CLOSED

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.

from platform-developer-docs.