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/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.
+
+:::