From a5dc31a791ccffcb2deb5fee020996297043b176 Mon Sep 17 00:00:00 2001
From: Zeno Kapitein <zeno@gitbook.io>
Date: Wed, 17 Jun 2026 10:35:08 +0200
Subject: [PATCH] Stick the page actions bar to the top of the viewport

Make the page header actions (the "On this page" toggle and the
assistant / page actions) stick to the top of the viewport on non-mobile
viewports, so they stay reachable while scrolling long pages such as API
references (RND-11139).

- PageHeader: render the actions as a sibling of `<header>` (a direct
  child of the scrolling `<main>`) so its sticky containing block is the
  full page rather than the short header, which is why it scrolled away
  before. It pins padded just below the site header using the same
  server-default + client CSS-var pattern as the table of contents, and
  drops below the "On this page" panel when that is expanded as an
  overlay so it doesn't show on top of it.
- OpenAPI: shift the sticky code-sample preview down so it clears the
  newly-sticky bar, and leave a small gap at the bottom of the viewport.
- Button: keep secondary buttons' background in the flat depth style
  instead of making them transparent, so the sticky actions stay visible
  over the content they scroll past.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../components/DocumentView/OpenAPI/style.css |   4 +-
 .../src/components/PageBody/PageHeader.tsx    | 178 +++++++++++-------
 .../src/components/primitives/Button.tsx      |   2 -
 3 files changed, 108 insertions(+), 76 deletions(-)

diff --git a/packages/gitbook/src/components/DocumentView/OpenAPI/style.css b/packages/gitbook/src/components/DocumentView/OpenAPI/style.css
index ee840de73..81b4e3247 100644
--- a/packages/gitbook/src/components/DocumentView/OpenAPI/style.css
+++ b/packages/gitbook/src/components/DocumentView/OpenAPI/style.css
@@ -149,7 +149,9 @@
 }
 
 .openapi-column-preview {
-    @apply flex flex-col flex-1 xl:max-2xl:pt-20 lg:pt-6 sticky self-start max-h-[calc(100vh-var(--toc-top-offset))] top-(--toc-top-offset);
+    /* Shift down by ~2rem so the pinned preview clears the sticky "On this page" /
+    page-actions bar below the header, and leave a 1rem gap at the bottom of the viewport. */
+    @apply flex flex-col flex-1 xl:max-2xl:pt-8 lg:pt-6 sticky self-start max-h-[calc(100vh-var(--toc-top-offset)-3rem)] top-[calc(var(--toc-top-offset)+2rem)];
 }
 
 .openapi-column-preview-body {
diff --git a/packages/gitbook/src/components/PageBody/PageHeader.tsx b/packages/gitbook/src/components/PageBody/PageHeader.tsx
index d118de9ae..a71085849 100644
--- a/packages/gitbook/src/components/PageBody/PageHeader.tsx
+++ b/packages/gitbook/src/components/PageBody/PageHeader.tsx
@@ -47,11 +47,34 @@ export async function PageHeader(props: {
     }
 
     return (
-        <header className={tcls(CONTENT_STYLE, 'mb-6 space-y-3 after:clear-both after:block')}>
+        <>
+            {/* Page actions (assistant, "On this page", ...). Rendered as a sibling of the
+            <header> — i.e. a direct child of the scrolling <main> — so that on larger screens
+            it can stick to the top of the viewport while the page is scrolled. If it lived
+            inside the <header>, its sticky containing block would be the short header and it
+            would scroll away with it. */}
             <div
                 className={tcls(
                     'float-right ml-4 flex gap-2',
-                    hasAncestors ? '-my-0.5' : '-mt-3 xs:mt-2'
+                    hasAncestors ? '-my-0.5' : '-mt-3 xs:mt-2',
+
+                    // Stick to the top of the viewport on non-mobile viewports so the actions
+                    // remain reachable while reading long pages (e.g. API references).
+                    'lg:sticky lg:z-20',
+
+                    // When the "On this page" panel is expanded as an overlay, drop below it
+                    // so the sticky actions don't show on top of the open panel.
+                    'lg:[body.outline-open_&]:z-0',
+
+                    // Server-side static positioning, padded slightly below the site header
+                    // (unlike the TOC/outline, which sit flush against it).
+                    'lg:top-3',
+                    'lg:site-header:top-[4.75rem]',
+                    'lg:site-header-sections:top-[7.5rem]',
+
+                    // Client-side dynamic positioning (CSS var applied by TableOfContentsScript),
+                    // kept consistent with the outline so both account for headers/banners/covers.
+                    'lg:[html[style*="--outline-top-offset"]_&]:top-[calc(var(--outline-top-offset)+0.75rem)]!'
                 )}
             >
                 {hasPageActions ? (
@@ -70,78 +93,87 @@ export async function PageHeader(props: {
                 <PageAsideToggleButton />
             </div>
 
-            {hasAncestors && (
-                <nav aria-label="Breadcrumb" className="text-tint leading-snug">
-                    <ol className="inline">
-                        {ancestors.map((breadcrumb, index) => {
-                            const href = linker.toPathForPage({
-                                pages: revision.pages,
-                                page: breadcrumb,
-                            });
-                            return (
-                                <li key={breadcrumb.id} className="inline">
-                                    <StyledLink
-                                        href={href}
-                                        className={tcls(
-                                            'inline',
-                                            'no-underline',
-                                            'hover:underline',
-                                            'text-xs',
-                                            'tracking-wide',
-                                            'font-semibold',
-                                            'uppercase',
-                                            'items-center',
-                                            'contrast-more:underline',
-                                            'contrast-more:decoration-current'
+            <header className={tcls(CONTENT_STYLE, 'mb-6 space-y-3 after:clear-both after:block')}>
+                {hasAncestors && (
+                    <nav aria-label="Breadcrumb" className="text-tint leading-snug">
+                        <ol className="inline">
+                            {ancestors.map((breadcrumb, index) => {
+                                const href = linker.toPathForPage({
+                                    pages: revision.pages,
+                                    page: breadcrumb,
+                                });
+                                return (
+                                    <li key={breadcrumb.id} className="inline">
+                                        <StyledLink
+                                            href={href}
+                                            className={tcls(
+                                                'inline',
+                                                'no-underline',
+                                                'hover:underline',
+                                                'text-xs',
+                                                'tracking-wide',
+                                                'font-semibold',
+                                                'uppercase',
+                                                'items-center',
+                                                'contrast-more:underline',
+                                                'contrast-more:decoration-current'
+                                            )}
+                                        >
+                                            <PageIcon
+                                                page={breadcrumb}
+                                                style="mr-1 inline size-3.5 shrink-0"
+                                            />
+                                            {breadcrumb.title}
+                                        </StyledLink>
+                                        {index !== ancestors.length - 1 && (
+                                            <Icon
+                                                aria-hidden
+                                                icon="chevron-right"
+                                                className="mx-2 inline-flex size-2 text-tint-subtle"
+                                            />
                                         )}
-                                    >
-                                        <PageIcon
-                                            page={breadcrumb}
-                                            style="mr-1 inline size-3.5 shrink-0"
-                                        />
-                                        {breadcrumb.title}
-                                    </StyledLink>
-                                    {index !== ancestors.length - 1 && (
-                                        <Icon
-                                            aria-hidden
-                                            icon="chevron-right"
-                                            className="mx-2 inline-flex size-2 text-tint-subtle"
-                                        />
-                                    )}
-                                </li>
-                            );
-                        })}
-                    </ol>
-                </nav>
-            )}
-            <PageTags page={page} revision={revision} />
-            {page.layout.title ? (
-                <h1
-                    className={tcls(
-                        'text-2xl',
-                        '@xs:text-3xl',
-                        '@lg:text-4xl',
-                        'leading-tight',
-                        'font-bold',
-                        'flex',
-                        'items-center',
-                        'gap-[.5em]',
-                        'grow',
-                        'text-pretty',
-                        'clear-right',
-                        'xs:clear-none'
-                    )}
-                >
-                    <PageIcon page={page} style={['text-tint-subtle ', 'shrink-0']} />
-                    {page.title}
-                </h1>
-            ) : null}
-            {page.description && page.layout.description ? (
-                <p className={tcls(CONTENT_STYLE_REDUCED, 'text-lg', 'text-tint', 'clear-both')}>
-                    {page.description}
-                </p>
-            ) : null}
-        </header>
+                                    </li>
+                                );
+                            })}
+                        </ol>
+                    </nav>
+                )}
+                <PageTags page={page} revision={revision} />
+                {page.layout.title ? (
+                    <h1
+                        className={tcls(
+                            'text-2xl',
+                            '@xs:text-3xl',
+                            '@lg:text-4xl',
+                            'leading-tight',
+                            'font-bold',
+                            'flex',
+                            'items-center',
+                            'gap-[.5em]',
+                            'grow',
+                            'text-pretty',
+                            'clear-right',
+                            'xs:clear-none'
+                        )}
+                    >
+                        <PageIcon page={page} style={['text-tint-subtle ', 'shrink-0']} />
+                        {page.title}
+                    </h1>
+                ) : null}
+                {page.description && page.layout.description ? (
+                    <p
+                        className={tcls(
+                            CONTENT_STYLE_REDUCED,
+                            'text-lg',
+                            'text-tint',
+                            'clear-both'
+                        )}
+                    >
+                        {page.description}
+                    </p>
+                ) : null}
+            </header>
+        </>
     );
 }
 
diff --git a/packages/gitbook/src/components/primitives/Button.tsx b/packages/gitbook/src/components/primitives/Button.tsx
index ebe422e30..14a31dbbc 100644
--- a/packages/gitbook/src/components/primitives/Button.tsx
+++ b/packages/gitbook/src/components/primitives/Button.tsx
@@ -58,10 +58,8 @@ export const variantClasses = {
     ],
     secondary: [
         'bg-tint',
-        'depth-flat:bg-transparent',
         'text-tint',
         'hover:bg-tint-hover',
-        'hover:not-disabled:depth-flat:bg-tint-hover',
         'hover:not-disabled:text-tint',
         'contrast-more:bg-tint-subtle',
         'disabled:bg-transparent',