feat(core): add new site config option siteConfig.markdown.anchors.maintainCase

[iAdramelk]

Added an option to preserve case then using github slugger as discussed in this comment. This option is disabled by default.

Pre-flight checklist

• I have read the Contributing Guidelines on pull requests.
• If this is a code change: I have written unit tests and/or added dogfooding pages to fully verify the new behavior.
• If this is a new API or substantial change: the PR has an accompanying issue (closes #0000) and the maintainers have approved on my working plan.

Motivation

This PR closes #7946. I encountered this issue while migrating large docs site to the Docusaurus. We also used mdx and Github slugger but with default options. After migrating we had hundreds of broken anchor links in our docs. Using https://docusaurus.io/docs/cli#docusaurus-write-heading-ids-sitedir helped, but it was updating the original mdx files which was not optimal.

Test Plan

I added a test case for this plugin option. See https://github.com/iAdramelk/docusaurus/blob/10ad71855edc3977c2c0eb75951c0a42952155f3/packages/docusaurus-mdx-loader/src/remark/headings/__tests__/index.test.ts#L323-L337

Test links

Changes:

• Added option to markdown config types. Not sure which link to use here, used issue link for now, will appreciate some guidance here.
• Added option to heading plugin.
• Added tests to the heading plugin.
• Added example to the docs.
• Updated mdx loader config to pass the option. Not sure that my way of adding options here is the correct one. Would be grateful for advice.

Deploy preview: https://deploy-preview-_____--docusaurus-2.netlify.app/

Related issues/PRs

#7946

[netlify]

✅ [V2]

Name	Link
🔨 Latest commit	7297594
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/662a5c4efb572f0008960c3e
😎 Deploy Preview	https://deploy-preview-10064--docusaurus-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[github-actions]

⚡️ Lighthouse report for the deploy preview of this PR

URL	Performance	Accessibility	Best Practices	SEO	PWA	Report
/	🟠 70	🟢 98	🟢 96	🟢 100	🟠 88	Report
/docs/installation	🟠 64	🟢 96	🟢 100	🟢 100	🟠 88	Report
/docs/category/getting-started	🟠 75	🟢 100	🟢 100	🟢 90	🟠 88	Report
/blog	🟠 67	🟢 100	🟢 100	🟢 90	🟠 88	Report
/blog/preparing-your-site-for-docusaurus-v3	🟠 62	🟢 96	🟢 100	🟢 100	🟠 88	Report
/blog/tags/release	🟠 67	🟢 100	🟢 100	🟠 80	🟠 88	Report
/blog/tags	🟠 77	🟢 100	🟢 100	🟢 90	🟠 88	Report

[Josh-Cena]

I believe you need to add config validation schema in packages/docusaurus/src/server/configValidation.ts. Also, do we really want to make maintainCase required? I think it should be anchor?: { maintainCase?: boolean } so anchor: {} is still valid, especially if we have other options in the future.

[iAdramelk]

Hey, I added validation to the config and made all fields optional. Please check.

[slorber]

LGTM thanks 👍