Add option to maintain case for generated heading ids

[elylucas]

Have you read the Contributing Guidelines on issues?

• [X] I have read the Contributing Guidelines on issues.

Description

We are migrating from a custom docs implementation to Docusaurus and need to maintain the case consistency of our current headings in our docs for external links currently pointed at our docs.

We thought about using the custom header ids, but we have a lot and it adds a lot of cruft to the md files and will have to added to each new header moving forward to maintain consistency.

It would be nice to have an option specified in docusaurus.config.js that will pass in maintainCase to the github slugger to preserve the casing of the heading anchors.

Has this been requested on Canny?

https://docusaurus.io/feature-requests/p/add-option-to-keep-capitalization-in-generated-heading-ids (older one but pretty much same request)

Motivation

Its been requested before (link in the canny inpuyt), and the answer was the custom header ids. That feature is great for a handful of custom links, but it would be great to turn this option on and it would eliminate the need to have to specify a custom id on each of our headings.

API design

Have a config option named maintainHeaderCasing that will be specified in the config file. This option will need to be passed down and passed as an option to the slugger here:

https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-mdx-loader/src/remark/headings/index.ts#L39

Have you tried building it?

Yes, we've patched it locally for our current needs by hard coding maintainCasing in the options to true here:

https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-mdx-loader/src/remark/headings/index.ts#L39

I'd be willing to contribute a fully working solution passing in the config option as well. I'll just need to figure out how to access the config from here.

Self-service

• [X] I'd be willing to contribute this feature to Docusaurus myself.

[Josh-Cena]

I think we can do it, as part of our Markdown infrastructure upgrade in v3. ref https://github.com/facebook/docusaurus/issues/5999

[iAdramelk]

What is the status of this issue? Need this feature too and ready to make a PR if you give me some guidance about where this options should be placed.

[slorber]

It's already implemented for the docusaurus write-heading-ids CLI

https://docusaurus.io/docs/cli#docusaurus-write-heading-ids-sitedir

Now that we have siteConfig.markdown, we could also add an option to let you customize the generated anchors (when an explicit id is not provided)

---

I'm not sure what the public API should look like. Do we only want to allow maintaining case, or even give more freedom to the users to provide their own anchorText -> anchorId logic?

If we only want to maintain the case, I propose:

const siteConfig = {
  markdown: {
    anchors: {maintainCase: true}
  },
}

We could start by providing that option, and then see if there's a need for something more powerful (not requested yet). Doing site config breaking changes are not too painful.

The place to make the change is likely here:

https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-mdx-loader/src/remark/headings/index.ts#L41

id = parsedHeading.id ?? slugs.slug(heading,{maintainCase: markdownConfig.anchors.maintainCase});

[iAdramelk]

@slorber write-heading-ids is updating existing mdx files which is something. It can be run before build, but it is not very convenient. It's not the information I want to commit to the repo.

For my use case just adding maintainCase to the config is enough. I am actually just patching the exact line above right now to make it work as I want.

Do you want me to make PR with this option?