Document custom heading IDs

create/text.mdx

@@ -1,7 +1,7 @@
 ---
 title: "Format text"
 description: "Learn how to format text, create headers, and style content."
-keywords: ["Markdown formatting", "text styling", "headers", "anchor links"]
+keywords: ["Markdown formatting", "text styling", "headers", "anchor links", "custom heading IDs"]
 ---
 
 ## Headers
@@ -22,6 +22,23 @@
   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 IDs are generated automatically from header text. You can override the generated ID with a custom one using the `{#custom-id}` syntax:
+
+```mdx
+## My section {#my-custom-anchor}
+### Configuration options {#config}
+```
+
+The custom ID replaces the auto-generated anchor, so you can link to the heading with `#my-custom-anchor` or `#config` instead of the default slugified text.
+
+This is useful when you want stable anchor links that don't change if you update the heading text, or when you need shorter, more memorable anchors.
+
+<Note>
+  Custom heading IDs are supported on heading levels 1 through 4 (`#` to `####`). Levels 5 and 6 are not supported.
+</Note>
+
 ### 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 +81,8 @@
 
 ```mdx
 **_bold and italic_**
 **~~bold and strikethrough~~**
 *~~italic and strikethrough~~*
 ```
 
 **_bold and italic_**<br />

guides/linking.mdx

@@ -1,14 +1,14 @@
 ---
 title: "Linking"
 description: "Learn how to create internal links, reference API endpoints, and maintain link integrity across your documentation."
-keywords: ["internal links", "cross-references", "anchor links", "broken links", "deep linking"]
+keywords: ["internal links", "cross-references", "anchor links", "broken links", "deep linking", "custom heading IDs"]
 ---
 
 Effective linking creates a connected documentation experience that helps users discover related content and navigate efficiently. Too many links or broken links can confuse users and make your documentation less effective. This guide covers how to create and maintain links throughout your documentation.
 
 ## 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.
 
@@ -65,6 +65,16 @@
   Headers with the `noAnchor` prop do not generate anchor links. See [Format text](/create/text#disabling-anchor-links) for details.
 </Note>
 
+### Custom anchor IDs
+
+You can override the auto-generated anchor for any heading by appending `{#custom-id}` to the header text:
+
+```mdx
+## Configuration options {#config}
+```
+
+This heading is reachable at `#config` instead of `#configuration-options`. Custom IDs are useful for keeping anchor links stable when you update heading text. See [Format text](/create/text#custom-heading-ids) for more details.
+
 ## Deep linking
 
 Deep links point to specific states or locations within a page, not just the page itself. Use deep links to send users directly to an open accordion or an API playground view.
@@ -73,7 +83,7 @@
 
 When a user opens an accordion, the URL hash updates to reflect the open state. Visiting a URL with that hash automatically opens and scrolls to the accordion.
 
 By default, the hash is derived from the accordion's `title`. Use the `id` property to set a custom hash:
 
 ```mdx
 <Accordion title="Installation steps" id="install">
@@ -99,7 +109,7 @@
 
 ## Link to API endpoints
 
 When documenting APIs, you can link to specific endpoints from anywhere in your documentation.
 
 Link to API endpoint pages using their path in the navigation.