feat(v2): add ability to set custom heading id (#4222)

* feat(v2): add ability to set custom heading id

* Add cli command

* Fix slugger

* write-heading-ids doc + add in commands/templates

* refactor + add tests for writeHeadingIds

* polish writeHeadingIds

* polish writeHeadingIds

* remove i18n goals todo section as the  remaining items are quite abstract/useless

* fix edge case with 2 md links in heading

* extract parseMarkdownHeadingId helper function

* refactor using the shared parseMarkdownHeadingId utility fn

* change logic of edge case

* Handle edge case

* Document explicit ids feature

Co-authored-by: slorber <lorber.sebastien@gmail.com>

website/docs/cli.md

@@ -11,11 +11,15 @@ Once your website is bootstrapped, the website source will contain the Docusauru
 {
   // ...
   "scripts": {
+    "docusaurus": "docusaurus",
     "start": "docusaurus start",
     "build": "docusaurus build",
     "swizzle": "docusaurus swizzle",
     "deploy": "docusaurus deploy",
-    "clear": "docusaurus clear"
+    "clear": "docusaurus clear",
+    "serve": "docusaurus serve",
+    "write-translations": "docusaurus write-translations",
+    "write-heading-ids": "docusaurus write-heading-ids"
   }
 }
 ```
@@ -177,3 +181,7 @@ By default, the files are written in `website/i18n/<defaultLocale>/...`.
 | `--override` | `false` | Override existing translation messages |
 | `--config` | `undefined` | Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js` |
 | `--messagePrefix` | `''` | Allows to add a prefix to each translation message, to help you highlight untranslated strings |
+
+### `docusaurus write-heading-ids [siteDir]`
+
+Add [explicit heading ids](./guides/markdown-features/markdown-features-headings.mdx#explicit-ids) to the Markdown documents of your site.

website/docs/guides/docs/docs-create-doc.mdx

@@ -44,6 +44,10 @@ The headers are well-spaced so that the hierarchy is clear.
 - that you want your users to remember
   - and you may nest them
     - multiple times
+
+### Custom id headers {#custom-id}
+
+With `{#custom-id}` syntax you can set your own header id.
 ```
 
 This will render in the browser as follows:

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-introduction.md

@@ -36,14 +36,6 @@ The goals of the Docusaurus i18n system are:
 - **RTL support**: locales reading right-to-left (Arabic, Hebrew...) should be easy to use.
 - **Default translations**: theme labels are translated for you in [many languages](https://github.com/facebook/docusaurus/tree/master/packages/docusaurus-theme-classic/codeTranslations).
 
-### i18n goals (TODO)
-
-Features that are **not yet implemented**:
-
-- **Contextual translations**: reduce friction to contribute to the translation effort.
-- **Anchor links**: linking should not break when you localize headings.
-- **Advanced configuration options**: customize route paths, file-system paths.
-
 ### i18n non-goals
 
 We don't provide support for:

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**.