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