Ability to customize slug generation

[Porges]

Initial checklist

• I read the support docs
• I read the contributing guide
• I agree to follow the code of conduct
• I searched issues and couldn’t find anything (or linked relevant results below)

Problem

My slug generation for headers happens in the Rehype phase and not in Remark, so I can't get the identifiers added before remark-toc runs, and thus the identifiers are different and the links don't work. Would it be possible to add an option to customize how slugs are generated for remark-toc?

Solution

I would like to be able to override how slugs are generated.

Alternatives

I could use remark-slug instead of rehype-slug, but it is deprecated.

[ChristianMurphy]

Welcome @Porges!
Thanks for reaching out.

My slug generation for headers happens in the Rehype phase and not in Remark

If the slug generation happens in rehype which happens after remark, how would a customization in remark-toc help? Wouldn't it be too early?

If you need access to the slugger in rehype you may be looking for rehype-toc (https://github.com/JS-DevTools/rehype-toc)?

[wooorm]

I don’t quite understand your setup.

• Your input is HTML?
• And then you want to generate markdown from that, with a table of contents?
• But the table of contents is not in the HTML file
• In the HTML file, you have custom links to headings, that do not follow the format that GitHub uses?
• Assuming this feature exists, while the table of contents is also not in HTML, how would the links from the table of contents in your markdown file, point to the headings in the HTML file?

[Porges]

If the slug generation happens in rehype which happens after remark, how would a customization in remark-toc help? Wouldn't it be too early?

I'm using a (slightly) customized slug generation anyway, so I have access to the slug function which is lying around (it's slug after converting to NFKD). It would be very easy to provide this to remark-toc.

If you need access to the slugger in rehype you may be looking for rehype-toc (https://github.com/JS-DevTools/rehype-toc)?

Unfortunately rehype-toc seems to unconditionally insert the TOC, unlike remark-toc which only inserts if a matching header is present. I would like the latter behaviour.

[ChristianMurphy]

I'm using a (slightly) customized slug generation anyway, so I have access to the slug function which is lying around (it's slug after converting to NFKD). It would be very easy to provide this to remark-toc.

This feels a lot like putting the carriage in front of the horse.
I have no doubt you have the will power to make it work, but you're making the problem much harder than you need to.

Yes, you could compute the slugs twice, and hope nothing has modified the content in a way that would change the slug between the two.
Or by using everything in rehype, you could slug once, and use the generated ids directly in the table of contents.

Unfortunately rehype-toc seems to unconditionally insert the TOC

That sounds like a relatively quick fix on the rehype-toc side, and significantly less brittle than the alternatives.

---

What (I think) @wooorm's questions are largely getting at, is this project, remark-toc, is focused more on generating a TOC in markdown itself, mostly for GitHub README.md files.

Your use case sounds much more focused on generating HTML output, in which case, rehype plugins are the way to go.
They will give you more fine grained control over when and how you generate the final document.

[ChristianMurphy]

It also looks like rehype-toc already has interest in allowing customization of where the table of contents is added JS-DevTools/rehype-toc#2

[Porges]

Thanks, I'll focus my efforts over there then 🙂