From 3175702a9eaa85e4a9791f1190025479219db084 Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Sat, 21 Mar 2026 05:44:02 +0000
Subject: [PATCH] Document custom heading IDs syntax

Generated-By: mintlify-agent
---
 create/text.mdx    | 19 ++++++++++++++++++-
 guides/linking.mdx | 12 +++++++++++-
 2 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/create/text.mdx b/create/text.mdx
index 6168762bc..2e6ed180c 100644
--- a/create/text.mdx
+++ b/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 `#` symbols to create headers of different levels:
   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.
diff --git a/guides/linking.mdx b/guides/linking.mdx
index 1917b1494..808235559 100644
--- a/guides/linking.mdx
+++ b/guides/linking.mdx
@@ -1,7 +1,7 @@
 ---
 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.
@@ -65,6 +65,16 @@ Anchor links are automatically created from header text.
   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.