Document explicit ids feature

packages/docusaurus/bin/docusaurus.js

@@ -288,8 +288,8 @@ cli
 cli
   .command('write-heading-ids [contentDir]')
   .description('Generate heading ids in Markdown content')
-  .action((contentDir = '.') => {
-    wrapCommand(writeHeadingIds)(contentDir);
+  .action((siteDir = '.') => {
+    wrapCommand(writeHeadingIds)(siteDir);
   });
 
 cli.arguments('<command>').action((cmd) => {

website/docs/cli.md

@@ -184,6 +184,4 @@ By default, the files are written in `website/i18n/<defaultLocale>/...`.
 
 ### `docusaurus write-heading-ids [siteDir]`
 
-Add explicit heading ids to the Markdown documents of your site instead of generating the ids from the heading text, ensuring anchor links don't break when modifying or translating heading text.
-
-A heading like `## my heading` is transformed into `## my heading {#my-heading}`
+Add [explicit heading ids](./guides/markdown-features/markdown-features-headings.mdx#explicit-ids) to the Markdown documents of your site.

website/docs/guides/markdown-features/markdown-features-headings.mdx

@@ -0,0 +1,59 @@
+---
+id: headings
+title: Headings
+description: Using Markdown headings
+slug: /markdown-features/headings
+---
+
+## Markdown headings
+
+You can use regular Markdown headings.
+
+```
+## Level 2 title
+
+### Level 3 title
+
+### Level 4 title
+```
+
+Markdown headings appear as a table-of-contents entry.
+
+## Heading ids
+
+Each heading has an id that can be generated, or explicitly specified.
+
+Heading ids allow you to link to a specific document heading in Markdown or JSX:
+
+```md
+[link](#heading-id)
+```
+
+```jsx
+<Link to="#heading-id">link</Link>
+```
+
+### Generated ids
+
+By default, Docusaurus will generate heading ids for you, based on the heading text.
+
+`### Hello World` will have id `hello-world`.
+
+Generated ids have **some limits**:
+
+- The id might not look good
+- You might want to **change or translate** the text without updating the existing id
+
+### Explicit ids
+
+A special Markdown syntax lets you set an **explicit heading id**:
+
+```md
+### Hello World {#my-explicit-id}
+```
+
+:::tip
+
+Use the **[write-heading-ids](../../cli.md#docusaurus-write-heading-ids-sitedir)** CLI command to add explicit ids to all your Markdown documents.
+
+:::

website/docs/i18n/i18n-tutorial.md

@@ -254,6 +254,27 @@ We only copy `.md` and `.mdx` files, as pages React components are translated th
 
 :::
 
+### Use explicit heading ids
+
+By default, a Markdown heading `### Hello World` will have a generated id `hello-world`.
+
+Other documents can target it with `[link](#hello-world)`.
+
+The translated heading becomes `### Bonjour le Monde`, with id `bonjour-le-monde`.
+
+Generated ids are not always a good fit for localized sites, as it requires you to localize all the anchor links:
+
+```diff
+- [link](#hello-world).
++ [link](#bonjour-le-monde)
+```
+
+:::tip
+
+For localized sites, it is recommended to use **[explicit heading ids](../guides/markdown-features/markdown-features-headings.mdx#explicit-ids)**.
+
+:::
+
 ## Deploy your site
 
 You can choose to deploy your site under a **single domain**, or use **multiple (sub)domains**.

website/sidebars.js

@@ -43,6 +43,7 @@ module.exports = {
             'guides/markdown-features/tabs',
             'guides/markdown-features/code-blocks',
             'guides/markdown-features/admonitions',
+            'guides/markdown-features/headings',
             'guides/markdown-features/inline-toc',
             'guides/markdown-features/assets',
             'guides/markdown-features/plugins',