Document custom heading IDs in MDX

create/text.mdx

@@ -22,6 +22,22 @@
   Use descriptive, keyword-rich headers that clearly indicate the content that follows. This improves both user navigation and search engine optimization.
 </Tip>
 
+### Custom heading IDs
+
+By default, anchor links are [auto-generated](/guides/linking#how-anchor-links-are-generated) from the heading text. You can override this with a custom ID using the `{#custom-id}` syntax:
+
+```mdx
+## My heading {#my-custom-id}
+```
+
+This sets the anchor link to `#my-custom-id` instead of the auto-generated `#my-heading`. Custom IDs work with heading levels 1 through 4.
+
+Custom IDs are automatically slugified — spaces become hyphens, special characters are removed or converted, and underscores are preserved. For example, `{#my custom id}` produces `#my-custom-id`.
+
+If multiple headings share the same custom ID, a numeric suffix is appended to keep them unique (e.g. `#same-id`, `#same-id-2`, `#same-id-3`).
+
+Custom heading IDs are useful when you want stable anchor links that don't change if you edit the heading text, or when auto-generated slugs don't produce the ID you want.
+
 ### Disabling anchor links
 
 By default, headers include clickable anchor links that allow users to link directly to specific sections. You can disable these anchor links using the `noAnchor` prop in HTML or React headers.
@@ -64,8 +80,8 @@
 
 ```mdx
 **_bold and italic_**
 **~~bold and strikethrough~~**
 *~~italic and strikethrough~~*
 ```
 
 **_bold and italic_**<br />

guides/linking.mdx

@@ -8,7 +8,7 @@
 
 ## Internal links
 
 Link to other pages in your documentation using root-relative paths. Root-relative paths start from the root of your documentation directory and work consistently regardless of where the linking page is located.
 
 ```mdx
 * [Quickstart guide](/quickstart)
@@ -46,7 +46,7 @@
 * [Customize your playground](/api-playground/overview#customize-your-playground)
 * [Cards properties](/components/cards#properties)
 
 ### How anchor links are generated
 
 Anchor links are automatically created from header text.
 
@@ -61,6 +61,14 @@
 | `### API Authentication` | `#api-authentication` |
 | `#### Step 1: Install` | `#step-1-install` |
 
+You can override the auto-generated anchor link by specifying a custom ID with the `{#custom-id}` syntax:
+
+```mdx
+## Step 2: Configure credentials {#configure-credentials}
+```
+
+This heading produces the anchor link `#configure-credentials` instead of the auto-generated `#step-2-configure-credentials`. See [Custom heading IDs](/create/text#custom-heading-ids) for more details.
+
 <Note>
   Headers with the `noAnchor` prop do not generate anchor links. See [Format text](/create/text#disabling-anchor-links) for details.
 </Note>