Add note about escaping header ids

[thadguidry]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Description

The current docs didn't mention about the new syntax conventions (or options) for header ids as @slorber mentioned at #3321 (comment)

A bit more detail about that should ideally be added to the page https://docusaurus.io/docs/markdown-features/toc#heading-ids ?

Self-service

• I'd be willing to address this documentation request myself.

[slorber]

Hi @thadguidry

Docusaurus v3 is retrocompatible regarding heading ids with v2, and this doc remains relevant and accurate.

https://docusaurus.io/docs/api/docusaurus-config#markdown

https://docusaurus.io/docs/migration/v3#headingids-option

TLDR: until we provide a new syntax and deprecate the old one, I think it's fine to keep the docs as is.

I've added this issue for the Docusaurus v4 milestone, but it's not just documentation, it's also proposing and implementing the new syntax + a smooth migration plan.

[damageboy]

When the mdxv1 compat option is turned on, are users expected to escape the heading id's or now.

The wording around "This syntax is now invalid" doesn't help would be users in understanding if thet are expected
to re-write the explicit ids with mdxv1compat turned on or not.

[slorber]

When the mdxv1 compat option is turned on, are users expected to escape the heading id's or now.

I recommend to not do anything and keep the heading as is until we provide a better replacement.

But there are cases where you might want need escape: if you use additional tools (like VSCode extensions, syntax highlighters or whatever else exists) that require a valid MDX document. Without escaping \{, your document is invalid, and it's possible that those tools report you errors (and they are right, because they don't know about our compatibility option).

That's the only reason I can think of to rewrite your headers with escaping right now. Unless you have a good reason to rewrite headings, you'd rather keep them as is.

[slorber]

FYI Docusaurus v3.10 will support a new MDX comment syntax that does not need escaping and should be compatible with other tools

See related PRs for details:

• feat(cli): write-heading-ids CLI now supports the --syntax and --migrate options #11777
• feat(mdx-loader): add support for explicit headingId based on MD/MDX comments #11755