Giters

rehypejs / rehype-slug

plugin to add `id` attributes to headings

Home Page:https://unifiedjs.com

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Support manual custom IDs

crutchcorn opened this issue · comments

commented

Initial checklist

Problem

Currently, there's no way to manually specify a header's ID. This means that, while drafting an article in MD (to then be passed into rehype), if I want to update a header's text, I must then go and update many of the links into that section.

Solution

Ideally, we can support the same Title {#id} syntax as gatsby-remark-autolink-headers and others. This will allow us to fix the problems from above.

Luckily, said plugin uses Remark under-the-hood and porting the code is fairly trivial (I've already done so w/ tests, just awaiting a PR in case this idea is received well).

If we port that code, we should also get support for these OOTB:

  • maintainCase: Boolean. Maintains the case for markdown header (optional)
  • removeAccents: Boolean. Remove accents from generated headings IDs (optional)
  • enableCustomId: Boolean. Enable custom header IDs with {#id} (optional)

Alternatives

This idea may be out-of-scope for this project. We may want to defer to the ecosystem to solve this problem, which I understand entirely

commented

there's no way to manually specify a header's ID.

This plugin allows existing IDs:

rehype-slug/index.js

Line 23 in 22582b7

if (headingRank(node) && node.properties && !hasProperty(node, 'id')) {
. It generates IDs for any heading that doesn’t have one. You can run any plugin before (or after) to use different IDs.

if I want to update a header's text, I must then go and update many of the links into that section.

This sounds like a different problem than your solution? With {#id}s, when you change them, you must also update all links?

we can support the same Title {#id} syntax as gatsby-remark-autolink-headers and others

I’m not a giant fan of this syntax, as it interferes with MDX 2 expressions, and isn’t supported by CommonMark or GitHub (in fact, it breaks linking on GH). Why do you want manual IDs? How often do you use them?
You could implement them as a syntax extension as well: https://github.com/micromark/micromark#case-variables.

commented

Hmm that's true. I may just take that logic and export elsewhere in a different rehype plugin

This sounds like a different problem than your solution? With {#id}s, when you change them, you must also update all links?

This is true, but with an important caveat: I tend to have an alright grasp of the section when I update the headers' text, but not a perfect grasp on what the headed section should be called in terms of a heading tag. Because of this, the manual IDs tend to help rather frequently with understanding the sections, being able to change the headings without having to change the section links. (because for each heading I add a link to the blog that I tend to link out for specific purposes)

You could implement them as a syntax extension as well: https://github.com/micromark/micromark#case-variables.

I admittedly missed this. Seems like the better implementation route to go towards. The Unified ecosystem is so big - it's awesome!

commented

This problem is something several people touch on, so I’d like to be involved in finding a proper solution.
I don’t think that’s here. But do ping me wherever you’re having the discussion!