From 3e537867bc2d6141e1f80cfa491d320c10fe8551 Mon Sep 17 00:00:00 2001
From: Peter White <peter@gitbook.io>
Date: Mon, 14 Sep 2026 10:22:11 +0200
Subject: [PATCH] Hide anchor links on pages with anchors disabled in the
 layout

---
 .../DocumentView/Expandable/Expandable.tsx    | 56 ++++++++++---------
 .../DocumentView/HashLinkButton.tsx           | 13 +++++
 .../src/components/DocumentView/Heading.tsx   | 37 ++++++------
 3 files changed, 65 insertions(+), 41 deletions(-)

diff --git a/packages/gitbook/src/components/DocumentView/Expandable/Expandable.tsx b/packages/gitbook/src/components/DocumentView/Expandable/Expandable.tsx
index 2c8e4d05c..2c3832930 100644
--- a/packages/gitbook/src/components/DocumentView/Expandable/Expandable.tsx
+++ b/packages/gitbook/src/components/DocumentView/Expandable/Expandable.tsx
@@ -3,6 +3,7 @@ import { Icon } from '@gitbook/icons';
 
 import type { BlockProps } from '../Block';
 import { Blocks } from '../Blocks';
+import { shouldShowHashLinks } from '../HashLinkButton';
 import { Inlines } from '../Inlines';
 import { Details } from './Details';
 import { ToggleChevron } from '@/components/primitives';
@@ -31,6 +32,8 @@ export async function Expandable(props: BlockProps<DocumentBlockExpandable>) {
         ? await getSpaceLanguage(context.contentContext)
         : defaultLanguage;
 
+    const showHashLink = shouldShowHashLinks(context);
+
     return (
         <Details
             id={id}
@@ -41,7 +44,8 @@ export async function Expandable(props: BlockProps<DocumentBlockExpandable>) {
                 className={tcls(
                     'cursor-pointer',
                     'px-4',
-                    'pr-10',
+                    // Reserve room for the anchor icon pinned to the right edge
+                    showHashLink && 'pr-10',
                     'py-4',
                     'relative',
                     'list-none',
@@ -71,32 +75,34 @@ export async function Expandable(props: BlockProps<DocumentBlockExpandable>) {
                     context={context}
                     ancestorInlines={[]}
                 />
-                <a
-                    href={`#${id}`}
-                    aria-label={tString(language, 'direct_link_to_heading')}
-                    className={tcls(
-                        'absolute',
-                        'top-2',
-                        'bottom-2',
-                        'right-4',
-                        'flex',
-                        'items-center',
-                        'dark:shadow-none',
-                        'dark:ring-0'
-                    )}
-                >
-                    <Icon
-                        icon="hashtag"
+                {showHashLink ? (
+                    <a
+                        href={`#${id}`}
+                        aria-label={tString(language, 'direct_link_to_heading')}
                         className={tcls(
-                            'inline-block',
-                            'size-3',
-                            'transition-colors',
-                            'text-transparent',
-                            'group-hover/expandable:text-tint-subtle',
-                            'contrast-more:group-hover/expandable:text-tint-strong'
+                            'absolute',
+                            'top-2',
+                            'bottom-2',
+                            'right-4',
+                            'flex',
+                            'items-center',
+                            'dark:shadow-none',
+                            'dark:ring-0'
                         )}
-                    />
-                </a>
+                    >
+                        <Icon
+                            icon="hashtag"
+                            className={tcls(
+                                'inline-block',
+                                'size-3',
+                                'transition-colors',
+                                'text-transparent',
+                                'group-hover/expandable:text-tint-subtle',
+                                'contrast-more:group-hover/expandable:text-tint-strong'
+                            )}
+                        />
+                    </a>
+                ) : null}
             </summary>
             <Blocks
                 nodes={body.nodes}
diff --git a/packages/gitbook/src/components/DocumentView/HashLinkButton.tsx b/packages/gitbook/src/components/DocumentView/HashLinkButton.tsx
index 2cb43cbdf..093570111 100644
--- a/packages/gitbook/src/components/DocumentView/HashLinkButton.tsx
+++ b/packages/gitbook/src/components/DocumentView/HashLinkButton.tsx
@@ -2,9 +2,22 @@ import type { DocumentBlockHeading, DocumentBlockTabs } from '@gitbook/api';
 import { Icon } from '@gitbook/icons';
 
 import { Link } from '../primitives';
+import type { DocumentContext } from './DocumentView';
 import { getBlockTextStyle } from './spacing';
 import { type ClassValue, tcls } from '@/lib/tailwind';
 
+/**
+ * Whether blocks should render a visible anchor link icon.
+ * Only the page body carries a page; search answers, AI chat and PDF export keep anchors.
+ */
+export function shouldShowHashLinks(context: DocumentContext): boolean {
+    const contentContext = context.contentContext;
+    if (!contentContext || !('page' in contentContext)) {
+        return true;
+    }
+    return contentContext.page.layout.anchors !== false;
+}
+
 /**
  * A hash icon which adds the block or active block item's ID in the URL hash.
  * The button needs to be wrapped in a container with `hashLinkButtonWrapperStyles`.
diff --git a/packages/gitbook/src/components/DocumentView/Heading.tsx b/packages/gitbook/src/components/DocumentView/Heading.tsx
index dc1a8271d..82644a978 100644
--- a/packages/gitbook/src/components/DocumentView/Heading.tsx
+++ b/packages/gitbook/src/components/DocumentView/Heading.tsx
@@ -1,7 +1,7 @@
 import type { DocumentBlockHeading } from '@gitbook/api';
 
 import type { BlockProps } from './Block';
-import { HashLinkButton, hashLinkButtonWrapperStyles } from './HashLinkButton';
+import { HashLinkButton, hashLinkButtonWrapperStyles, shouldShowHashLinks } from './HashLinkButton';
 import { HeadingRevealWrapper } from './HeadingRevealWrapper';
 import { Inlines } from './Inlines';
 import { getBlockTextStyle } from './spacing';
@@ -24,6 +24,8 @@ export async function Heading(props: BlockProps<DocumentBlockHeading>) {
         ? await getSpaceLanguage(context.contentContext)
         : defaultLanguage;
 
+    const showHashLink = shouldShowHashLinks(context);
+
     return (
         <HeadingRevealWrapper
             as={Tag}
@@ -34,7 +36,8 @@ export async function Heading(props: BlockProps<DocumentBlockHeading>) {
                 'font-heading',
                 'pdf-heading',
                 'block',
-                'pr-6',
+                // Reserve room for the absolutely positioned anchor icon on coarse pointers
+                showHashLink && 'pr-6',
                 'pointer-fine:flex',
                 'pointer-fine:items-baseline',
                 'pointer-fine:pr-0',
@@ -63,20 +66,22 @@ export async function Heading(props: BlockProps<DocumentBlockHeading>) {
                 <Inlines {...rest} context={context} nodes={block.nodes} ancestorInlines={[]} />
             </span>
 
-            <HashLinkButton
-                id={id}
-                block={block}
-                className={tcls(
-                    'absolute',
-                    block.type === 'heading-1'
-                        ? '[transform:translateY(0.125em)]'
-                        : '[transform:translateY(0.17em)]',
-                    'pointer-fine:-ml-6 pointer-fine:relative pointer-fine:order-first pointer-fine:self-center pointer-fine:pr-2 pointer-fine:[transform:none]',
-                    'pointer-fine:[.flip-heading-hash_&]:order-last pointer-fine:[.flip-heading-hash_&]:ml-1 pointer-fine:[.flip-heading-hash_&]:pl-2'
-                )}
-                iconClassName={tcls('size-4')}
-                label={tString(language, 'direct_link_to_heading')}
-            />
+            {showHashLink ? (
+                <HashLinkButton
+                    id={id}
+                    block={block}
+                    className={tcls(
+                        'absolute',
+                        block.type === 'heading-1'
+                            ? '[transform:translateY(0.125em)]'
+                            : '[transform:translateY(0.17em)]',
+                        'pointer-fine:-ml-6 pointer-fine:relative pointer-fine:order-first pointer-fine:self-center pointer-fine:pr-2 pointer-fine:[transform:none]',
+                        'pointer-fine:[.flip-heading-hash_&]:order-last pointer-fine:[.flip-heading-hash_&]:ml-1 pointer-fine:[.flip-heading-hash_&]:pl-2'
+                    )}
+                    iconClassName={tcls('size-4')}
+                    label={tString(language, 'direct_link_to_heading')}
+                />
+            ) : null}
         </HeadingRevealWrapper>
     );
 }