Duplicated heading texts should have a unique ID to generate expected anchor link

[khiga8]

When a page has duplicated heading text, they end up generating the same anchor link. This is confusing because if I share an anchor link to a section of a page, it end up somewhere unexpected.

There's a markdownlint rule to flag duplicate heading text, but I think a more bullet-proof solution would be to update the doc parser to handle duplicate heading text.

Similar to the approach that github.com takes, could we append -1 to the ID and increment from there when the same heading text is seen?

It looks like ID is being set here in MarkdownHeading.

[khiga8]

A bit more on the nuance of this rule (github/markdownlint-github#30):

[tallys]

@lesliecdubs looks like this does need to have both rails and react labels 👍 let me know how you'd like to prioritize it

[lesliecdubs]

@khiga8 hi! Were you requesting this work to be done within the Doctocat repo and https://primer.style as per the repo this issue is filed in, or within PRC and PVC components?

[khiga8]

@lesliecdubs I'm requesting a bug fix to a Doctocat component, specifically, MarkdownHeading. This affects all Primer sites.

[lesliecdubs]

Thank you for the clarification.

@broccolinisoup I saw that this is needed for the work you've started in primer/design#365. Feel free to pick this up if it would help move that issue or the migration efforts along! If not, please drop a comment here and I'll look into further assignment.

[broccolinisoup]

Thanks @lesliecdubs! There are 2 possible solutions for primer/design#365. I was feeling more close to changing the titles of the sections to support the markdown linting rule and it also sounded to me the most accessible solution as well (one example would be less cognitive effort when the subtitle is a title by itself rather than making an association with its parent title) but I'll see what @emilybrick says on the PR. Even if we decided to go with changing the titles, I would be happy to pick it up. I am just not sure if I can do it soon because I have a couple of things on my plate already. Having said that, I'd be happy to pick this up if there is no one assigned when I am done with my currently in progress things. Thank you!

[lesliecdubs]

Thanks @broccolinisoup, I'll see if I can find someone else to pick this up in the meantime! If this issue is still open and unassigned when you have some time available, feel free to jump in.

[broccolinisoup]

@lesliecdubs all my WIP is in the review process so I am picking this up 😊

[broccolinisoup]

@khiga8 I had a look at how we generate the slugs in doctocat. The github-slugger library that we use is actually doing what you were describing however the issue in doctocat is that because everything is a component, heading components don't know anything about the page context therefore they are not aware of if there are other headings with the same name if that makes sense. And the doctocat doesn't seem to have a state that I can try to access to get the pageContext and providing the pageContext to the headings as a prop doesn't sound the best practise to me. I will re-think about it and chat with one of team mates to see if there is anything I misunderstand here or any other way we can solve this issue. Please let me know if you have any suggestions 🙌🏻

[khiga8]

@broccolinisoup My initial (not-good) thought was that the anchor could have a uniquely generated ID appended to the slug. But I realized that's not a good idea because it would make it impossible to link to reference the anchor heading within the markdown which we tend to do 😅.

I am not familiar with the codebase nor how Gatsby works, but this code seemed like it could be relevant...maybe?

gatsby-node.js:

      const code = await mdx(node.rawBody)
      const {frontmatter} = extractExports(code)

      actions.createPage({

I see we're using:

const mdx = require(`gatsby-plugin-mdx/utils/mdx`)

Gatsby-plugin-mdx options mentions rehype-autolink-headings.

Could it be worth looking into this plugin, or writing our own similar "thing" that can be passed into Gatsby-plugin-mdx to add IDs appropriately? (Just thinking out loud without knowing how this all actually works cries)

chat with one of team mates

That seems like a good idea :)

[broccolinisoup]

@khiga8 I am sorry that I didn't respond to your post - I had other things come to my way and didn't have a chance to look into this issue at all 😞 I'll come back here once I clear other things on my plate - thank you!

[github-actions]

Hi! This issue has been marked as stale because it has been open with no activity for 180 days. You can comment on the issue or remove the stale label to keep it open. If you do nothing, this issue will be closed in 7 days.

[github-actions]

Hi! This issue has been marked as stale because it has been open with no activity for 180 days. You can comment on the issue or remove the stale label to keep it open. If you do nothing, this issue will be closed in 7 days.