From 12be7b7d6c38d57a69a7818b85c2a3781675b4b6 Mon Sep 17 00:00:00 2001
From: barckcode <cristian@helmcode.com>
Date: Mon, 12 Oct 2026 19:02:03 +0200
Subject: [PATCH 1/2] feat(docs): nest a guide under another in the sidebar; PR
 gatekeeper under Automations

Adds an optional `parent` frontmatter field (the parent's entry id). A page
with a parent is rendered as an indented sub-item right under it, in the
parent's group, never twice. The parent shows an active trail while the child
is open, the breadcrumb includes the parent, and prev/next follow the
sidebar's visual order.

- docsNav: groupDocsNav nests children (cycle/orphan safe), flattenDocsNav,
  isActiveDocTrail, docsNavAncestors, shared docsNavItemFromEntry
- DocsSidebarNav + recursive DocsNavList components, nested list markup
- pr-gatekeeper: parent automations, order 21 (webhooks 22), EN and ES
- fix: /es/docs no longer highlights as active on every Spanish page
- tests: unit nesting specs, Container API render test (EN/ES), frontmatter
  guards for `parent`; vitest split into unit and render projects

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 ARCHITECTURE.md                               |   2 +
 src/components/docs/DocsNavList.astro         |  45 +++++
 src/components/docs/DocsSidebarNav.astro      |  27 +++
 src/content.config.ts                         |  11 ++
 src/content/docs-es/pr-gatekeeper.mdx         |   3 +-
 src/content/docs-es/webhooks.mdx              |   2 +-
 src/content/docs/pr-gatekeeper.mdx            |   3 +-
 src/content/docs/webhooks.mdx                 |   2 +-
 src/layouts/Docs.astro                        |  60 +++----
 src/lib/docsNav.test.ts                       | 157 ++++++++++++++++++
 src/lib/docsNav.ts                            | 123 ++++++++++++--
 src/styles/docs-shell.css                     |  27 +++
 src/tests/layouts/DocsShell.test.ts           |  33 ++++
 src/tests/layouts/automationsDocs.test.ts     |   4 +-
 src/tests/layouts/docsI18n.test.ts            |   4 +-
 .../layouts/docsNavNesting.render.test.ts     | 112 +++++++++++++
 src/tests/layouts/prGatekeeperDocs.test.ts    |  16 +-
 vitest.config.ts                              |  24 ++-
 vitest.render.config.ts                       |  20 +++
 19 files changed, 615 insertions(+), 60 deletions(-)
 create mode 100644 src/components/docs/DocsNavList.astro
 create mode 100644 src/components/docs/DocsSidebarNav.astro
 create mode 100644 src/tests/layouts/docsNavNesting.render.test.ts
 create mode 100644 vitest.render.config.ts

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index f77b43d3..46ca43fc 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -128,6 +128,8 @@ The community-tier signup page (`/community`) reuses `LanguageSwitcher.astro` an
 | `/docs/examples` | Code snippets (Python, Node.js, curl) |
 | `/docs/api` | OpenAI-compatible API reference (endpoints, auth, rate limits) |
 
+Sidebar navigation comes from each guide's frontmatter (`src/content.config.ts`): `group` picks the section, `order` the position, and an optional `parent` (the entry id of another guide, identical in EN and ES) lists the page as an indented sub-item right under that guide, in the parent's group. URLs stay flat (`/docs/<id>`); the breadcrumb and prev/next follow the sidebar's visual order. Logic and tests: `src/lib/docsNav.ts`; markup: `src/components/docs/DocsSidebarNav.astro` + `DocsNavList.astro` (rendered in tests with the Astro Container API, `*.render.test.ts`, see `vitest.render.config.ts`).
+
 ### API Endpoints
 
 #### `POST /api/waitlist`
diff --git a/src/components/docs/DocsNavList.astro b/src/components/docs/DocsNavList.astro
new file mode 100644
index 00000000..27e2854c
--- /dev/null
+++ b/src/components/docs/DocsNavList.astro
@@ -0,0 +1,45 @@
+---
+/**
+ * One level of the docs sidebar: a list of pages, each with the pages nested
+ * under it (frontmatter `parent`) rendered as an indented sub-list right below.
+ *
+ * It recurses through Astro.self, so nesting depth is whatever the data says.
+ * Sub-items are always shown, not behind a toggle: with a handful of children
+ * a disclosure button would add a click and a focus stop for no gain, and a
+ * plain nested <ul> is what screen readers announce as "list, level 2".
+ *
+ * `here` is the current path. The current page gets `aria-current="page"`; the
+ * pages above it (its parent chain) get `is-trail`, so the reader sees where
+ * the open page sits in the tree.
+ */
+import { isActiveDocPath, isActiveDocTrail, type DocsNavNode } from '../../lib/docsNav';
+
+interface Props {
+  items: DocsNavNode[];
+  here: string;
+  depth?: number;
+}
+
+const { items, here, depth = 0 } = Astro.props;
+---
+
+<ul class:list={[{ 'docs-nav-sub': depth > 0 }]} data-depth={depth}>
+  {
+    items.map((item) => {
+      const active = isActiveDocPath(here, item.slug);
+      const trail = !active && isActiveDocTrail(here, item);
+      return (
+        <li class:list={[{ 'has-children': item.children.length > 0 }]}>
+          <a
+            href={item.slug}
+            class:list={['docs-nav-link', { 'is-active': active, 'is-trail': trail }]}
+            aria-current={active ? 'page' : undefined}
+          >
+            {item.label}
+          </a>
+          {item.children.length > 0 && <Astro.self items={item.children} here={here} depth={depth + 1} />}
+        </li>
+      );
+    })
+  }
+</ul>
diff --git a/src/components/docs/DocsSidebarNav.astro b/src/components/docs/DocsSidebarNav.astro
new file mode 100644
index 00000000..a44c0a62
--- /dev/null
+++ b/src/components/docs/DocsSidebarNav.astro
@@ -0,0 +1,27 @@
+---
+/**
+ * The docs sidebar's page list: one block per group, each a (possibly nested)
+ * list of pages. Split out of Docs.astro so it can be rendered on its own in
+ * tests; the layout itself drags in the content collections and Cloudflare.
+ */
+import DocsNavList from './DocsNavList.astro';
+import type { DocsNavGroup } from '../../lib/docsNav';
+
+interface Props {
+  groups: DocsNavGroup[];
+  here: string;
+}
+
+const { groups, here } = Astro.props;
+---
+
+<nav class="docs-nav" aria-label="Docs sections">
+  {
+    groups.map((g) => (
+      <div class="docs-nav-group">
+        <p class="docs-nav-label">{g.group}</p>
+        <DocsNavList items={g.items} here={here} />
+      </div>
+    ))
+  }
+</nav>
diff --git a/src/content.config.ts b/src/content.config.ts
index 2b09dd64..430f16d8 100644
--- a/src/content.config.ts
+++ b/src/content.config.ts
@@ -16,6 +16,17 @@ const docsSchema = z.object({
    * second list to maintain either.
    */
   group: z.string().default('Guides'),
+  /*
+   * The entry id of the page this one is listed under in the sidebar (e.g.
+   * `automations`). The page then shows as an indented sub-item right below
+   * its parent, inside the parent's group, and prev/next follow that order.
+   * Its URL stays flat (/docs/<id>): nesting is a nav concern only, so links
+   * and the /api/docs manifest are unaffected. Same value in both languages.
+   */
+  parent: z
+    .string()
+    .regex(/^[a-z0-9-]+$/)
+    .optional(),
   locale: z.string().default('es'),
 });
 
diff --git a/src/content/docs-es/pr-gatekeeper.mdx b/src/content/docs-es/pr-gatekeeper.mdx
index 5bf5fc1d..3b9f3e1e 100644
--- a/src/content/docs-es/pr-gatekeeper.mdx
+++ b/src/content/docs-es/pr-gatekeeper.mdx
@@ -1,8 +1,9 @@
 ---
 title: PR gatekeeper
 description: Monta, paso a paso, una automatización que comprueba cada pull request contra el mínimo de tu equipo y deja el veredicto en un solo comentario.
-order: 22
+order: 21
 group: Guías
+parent: automations
 ---
 
 import Details from '../../components/docs/Details.astro';
diff --git a/src/content/docs-es/webhooks.mdx b/src/content/docs-es/webhooks.mdx
index 08d80611..e7b0fecf 100644
--- a/src/content/docs-es/webhooks.mdx
+++ b/src/content/docs-es/webhooks.mdx
@@ -1,7 +1,7 @@
 ---
 title: Webhooks y programaciones
 description: Lanza tus automatizaciones desde GitHub, Stripe o tus propios sistemas con webhooks firmados, o con una programación.
-order: 21
+order: 22
 group: Guías
 ---
 
diff --git a/src/content/docs/pr-gatekeeper.mdx b/src/content/docs/pr-gatekeeper.mdx
index 48a72481..da4de260 100644
--- a/src/content/docs/pr-gatekeeper.mdx
+++ b/src/content/docs/pr-gatekeeper.mdx
@@ -1,8 +1,9 @@
 ---
 title: PR gatekeeper
 description: Build, step by step, an automation that checks every pull request against your team's minimum bar and keeps the verdict in one comment.
-order: 22
+order: 21
 group: Guides
+parent: automations
 ---
 
 import Details from '../../components/docs/Details.astro';
diff --git a/src/content/docs/webhooks.mdx b/src/content/docs/webhooks.mdx
index 6637fd27..eeae6db6 100644
--- a/src/content/docs/webhooks.mdx
+++ b/src/content/docs/webhooks.mdx
@@ -1,7 +1,7 @@
 ---
 title: Webhooks and schedules
 description: Start your automations from GitHub, Stripe or your own systems with signed webhooks, or on a schedule.
-order: 21
+order: 22
 group: Guides
 ---
 
diff --git a/src/layouts/Docs.astro b/src/layouts/Docs.astro
index 73576dfe..dc7c09e1 100644
--- a/src/layouts/Docs.astro
+++ b/src/layouts/Docs.astro
@@ -11,10 +11,15 @@ import '@fontsource/jetbrains-mono/700.css';
 
 import { getCollection, render } from 'astro:content';
 import DocsTopBar from '../components/docs/DocsTopBar.astro';
+import DocsSidebarNav from '../components/docs/DocsSidebarNav.astro';
 import { API_DOC_META, API_DOC_SLUG } from '../lib/apiDoc';
 import spec from '../data/openapi.json';
 import {
   apiSearchHeadings,
+  docSlug,
+  docsNavAncestors,
+  docsNavItemFromEntry,
+  flattenDocsNav,
   groupDocsNav,
   isActiveDocPath,
   type DocsNavItem,
@@ -75,13 +80,7 @@ const entries = await getCollection(lang === 'es' ? 'docsEs' : 'docs');
  * so the page and the manifest cannot disagree.
  */
 const navItems: DocsNavItem[] = [
-  ...entries.map((entry) => ({
-    slug: entry.id === 'intro' ? `${pfx}/docs` : `${pfx}/docs/${entry.id}`,
-    label: entry.data.title,
-    order: entry.data.order,
-    group: entry.data.group,
-    description: entry.data.description,
-  })),
+  ...entries.map((entry) => docsNavItemFromEntry(entry, pfx)),
   {
     slug: `${pfx}/docs/${API_DOC_SLUG}`,
     label: API_DOC_META.title,
@@ -92,6 +91,9 @@ const navItems: DocsNavItem[] = [
 ].sort((a, b) => a.order - b.order);
 
 const navGroups = groupDocsNav(navItems);
+// The sidebar's visual order (children right after their parent), which is
+// what prev/next must follow; the raw `order` alone would not.
+const navOrder = flattenDocsNav(navGroups);
 
 const enPath = Astro.url.pathname.replace(/^\/es(?=\/|$)/, '') || '/docs';
 const esPath = `/es${enPath}`;
@@ -104,7 +106,7 @@ const isActive = (slug: string) => isActiveDocPath(here, slug);
  * its structure dropped them; they are restored because under /docs they are
  * the only clue to where you are when you arrive from a search engine.
  */
-const breadcrumb = enPath
+const pathCrumbs = enPath
   .split('/')
   .filter(Boolean)
   .map((part, i, parts) => {
@@ -118,11 +120,20 @@ const breadcrumb = enPath
       isCurrent: path === here,
     };
   });
-
-const currentIndex = navItems.findIndex((item) => isActive(item.slug));
-const prevPage = currentIndex > 0 ? navItems[currentIndex - 1] : null;
+// A page nested in the nav (frontmatter `parent`) has a flat URL, so its
+// parents are not in the path: they are slotted in before the current crumb so
+// the breadcrumb tells the same story as the sidebar.
+const parentCrumbs = docsNavAncestors(navItems, here).map((p) => ({
+  label: p.label,
+  path: p.slug,
+  isCurrent: false,
+}));
+const breadcrumb = [...pathCrumbs.slice(0, -1), ...parentCrumbs, ...pathCrumbs.slice(-1)];
+
+const currentIndex = navOrder.findIndex((item) => isActive(item.slug));
+const prevPage = currentIndex > 0 ? navOrder[currentIndex - 1] : null;
 const nextPage =
-  currentIndex >= 0 && currentIndex < navItems.length - 1 ? navItems[currentIndex + 1] : null;
+  currentIndex >= 0 && currentIndex < navOrder.length - 1 ? navOrder[currentIndex + 1] : null;
 
 /*
  * Search index.
@@ -137,7 +148,7 @@ const collectionIndex = await Promise.all(
     const { headings } = await render(entry);
     return {
       title: entry.data.title,
-      href: entry.id === 'intro' ? `${pfx}/docs` : `${pfx}/docs/${entry.id}`,
+      href: docSlug(entry.id, pfx),
       description: entry.data.description,
       headings: headings
         .filter((h) => h.depth >= 2 && h.depth <= 3)
@@ -235,28 +246,7 @@ const searchData = [
           <div id="docs-search-results" class="ds-results" hidden></div>
         </div>
 
-        <nav class="docs-nav" aria-label="Docs sections">
-          {
-            navGroups.map((g) => (
-              <div class="docs-nav-group">
-                <p class="docs-nav-label">{g.group}</p>
-                <ul>
-                  {g.items.map((item) => (
-                    <li>
-                      <a
-                        href={item.slug}
-                        class:list={['docs-nav-link', { 'is-active': isActive(item.slug) }]}
-                        aria-current={isActive(item.slug) ? 'page' : undefined}
-                      >
-                        {item.label}
-                      </a>
-                    </li>
-                  ))}
-                </ul>
-              </div>
-            ))
-          }
-        </nav>
+        <DocsSidebarNav groups={navGroups} here={here} />
       </aside>
 
       <div class="docs-pane">
diff --git a/src/lib/docsNav.test.ts b/src/lib/docsNav.test.ts
index a3b4b6f6..7ecbcfa5 100644
--- a/src/lib/docsNav.test.ts
+++ b/src/lib/docsNav.test.ts
@@ -3,8 +3,11 @@ import spec from '../data/openapi.json';
 import { API_DOC_META, API_DOC_SLUG } from './apiDoc';
 import {
   apiSearchHeadings,
+  docsNavAncestors,
+  flattenDocsNav,
   groupDocsNav,
   isActiveDocPath,
+  isActiveDocTrail,
   slugifyAnchor,
   type DocsNavItem,
 } from './docsNav';
@@ -52,6 +55,12 @@ describe('isActiveDocPath', () => {
     expect(isActiveDocPath('/docs', '/docs')).toBe(true);
   });
 
+  it('does not let /es/docs highlight on every Spanish page either', () => {
+    expect(isActiveDocPath('/es/docs/models', '/es/docs')).toBe(false);
+    expect(isActiveDocPath('/es/docs', '/es/docs')).toBe(true);
+    expect(isActiveDocPath('/es/docs/guides/deploy', '/es/docs/guides')).toBe(true);
+  });
+
   it('does not match a sibling that merely shares a prefix', () => {
     expect(isActiveDocPath('/docs/models-old', '/docs/models')).toBe(false);
   });
@@ -76,6 +85,154 @@ describe('groupDocsNav', () => {
   });
 });
 
+/**
+ * Nesting: a page can declare `parent` (the slug of another page) and it is
+ * then listed as a sub-item right under that page instead of at the top level
+ * of its group. Owner's ask: the PR gatekeeper guide belongs UNDER Automations.
+ */
+describe('groupDocsNav: nesting under a parent', () => {
+  const guides = () => [
+    item({ slug: '/docs/runs', label: 'Runs', order: 19 }),
+    item({ slug: '/docs/automations', label: 'Automations', order: 20 }),
+    item({ slug: '/docs/pr-gatekeeper', label: 'PR gatekeeper', order: 21, parent: '/docs/automations' }),
+    item({ slug: '/docs/webhooks', label: 'Webhooks', order: 22 }),
+  ];
+
+  it('lists the child under its parent, not at the top level', () => {
+    const [g] = groupDocsNav(guides());
+    expect(g.items.map((i) => i.label)).toEqual(['Runs', 'Automations', 'Webhooks']);
+    const automations = g.items.find((i) => i.label === 'Automations')!;
+    expect(automations.children.map((c) => c.label)).toEqual(['PR gatekeeper']);
+  });
+
+  it('never lists a child twice', () => {
+    const flat = flattenDocsNav(groupDocsNav(guides()));
+    expect(flat.filter((i) => i.label === 'PR gatekeeper')).toHaveLength(1);
+    expect(flat).toHaveLength(4);
+  });
+
+  it('gives top-level items an empty children list', () => {
+    const [g] = groupDocsNav(guides());
+    expect(g.items.find((i) => i.label === 'Runs')!.children).toEqual([]);
+  });
+
+  it('orders siblings under one parent by their own order, whatever the input order', () => {
+    const [g] = groupDocsNav([
+      item({ slug: '/docs/b', label: 'B', order: 5, parent: '/docs/p' }),
+      item({ slug: '/docs/p', label: 'P', order: 1 }),
+      item({ slug: '/docs/a', label: 'A', order: 3, parent: '/docs/p' }),
+    ]);
+    expect(g.items[0].children.map((c) => c.label)).toEqual(['A', 'B']);
+  });
+
+  it('follows the parent into its group, even if the child says otherwise', () => {
+    const groups = groupDocsNav([
+      item({ slug: '/docs/p', label: 'P', order: 0, group: 'Guides' }),
+      item({ slug: '/docs/c', label: 'C', order: 1, parent: '/docs/p', group: 'Reference' }),
+    ]);
+    expect(groups.map((g) => g.group)).toEqual(['Guides']);
+    expect(groups[0].items[0].children.map((c) => c.label)).toEqual(['C']);
+  });
+
+  it('does not open a group for a child alone', () => {
+    const groups = groupDocsNav([
+      item({ slug: '/docs/p', label: 'P', order: 5, group: 'Guides' }),
+      item({ slug: '/docs/c', label: 'C', order: 0, parent: '/docs/p', group: 'Get started' }),
+    ]);
+    expect(groups.map((g) => g.group)).toEqual(['Guides']);
+  });
+
+  /** A typo in `parent` must not make the page vanish from the nav. */
+  it('keeps a page whose parent does not exist at the top level', () => {
+    const [g] = groupDocsNav([item({ slug: '/docs/orphan', label: 'Orphan', parent: '/docs/nope' })]);
+    expect(g.items.map((i) => i.label)).toEqual(['Orphan']);
+  });
+
+  it('keeps a page that names itself as parent at the top level', () => {
+    const [g] = groupDocsNav([item({ slug: '/docs/self', label: 'Self', parent: '/docs/self' })]);
+    expect(g.items.map((i) => i.label)).toEqual(['Self']);
+  });
+
+  it('survives a parent cycle without dropping or duplicating pages', () => {
+    const flat = flattenDocsNav(
+      groupDocsNav([
+        item({ slug: '/docs/a', label: 'A', order: 0, parent: '/docs/b' }),
+        item({ slug: '/docs/b', label: 'B', order: 1, parent: '/docs/a' }),
+      ]),
+    );
+    expect(flat.map((i) => i.label).sort()).toEqual(['A', 'B']);
+  });
+
+  it('nests more than one level deep', () => {
+    const groups = groupDocsNav([
+      item({ slug: '/docs/a', label: 'A', order: 0 }),
+      item({ slug: '/docs/b', label: 'B', order: 1, parent: '/docs/a' }),
+      item({ slug: '/docs/c', label: 'C', order: 2, parent: '/docs/b' }),
+    ]);
+    expect(groups[0].items[0].children[0].children.map((c) => c.label)).toEqual(['C']);
+  });
+});
+
+describe('flattenDocsNav: the visual order, for prev/next', () => {
+  it('puts each child right after its parent, before the parent\'s next sibling', () => {
+    const flat = flattenDocsNav(
+      groupDocsNav([
+        item({ slug: '/docs/intro', label: 'Intro', order: 0, group: 'Get started' }),
+        item({ slug: '/docs/automations', label: 'Automations', order: 20 }),
+        item({ slug: '/docs/webhooks', label: 'Webhooks', order: 21 }),
+        // Out of order on purpose: the visual order wins over the raw number.
+        item({ slug: '/docs/pr-gatekeeper', label: 'PR gatekeeper', order: 22, parent: '/docs/automations' }),
+      ]),
+    );
+    expect(flat.map((i) => i.label)).toEqual(['Intro', 'Automations', 'PR gatekeeper', 'Webhooks']);
+  });
+});
+
+describe('isActiveDocTrail', () => {
+  const [g] = groupDocsNav([
+    item({ slug: '/docs/automations', label: 'Automations', order: 0 }),
+    item({ slug: '/docs/pr-gatekeeper', label: 'PR gatekeeper', order: 1, parent: '/docs/automations' }),
+    item({ slug: '/docs/webhooks', label: 'Webhooks', order: 2 }),
+  ]);
+  const automations = g.items[0];
+
+  it('marks the parent as on the trail while a child is open', () => {
+    expect(isActiveDocTrail('/docs/pr-gatekeeper', automations)).toBe(true);
+  });
+
+  it('also when the parent itself is open', () => {
+    expect(isActiveDocTrail('/docs/automations', automations)).toBe(true);
+  });
+
+  it('not on an unrelated page', () => {
+    expect(isActiveDocTrail('/docs/webhooks', automations)).toBe(false);
+  });
+});
+
+describe('docsNavAncestors: for the breadcrumb', () => {
+  const items = [
+    item({ slug: '/docs/automations', label: 'Automations', order: 0 }),
+    item({ slug: '/docs/pr-gatekeeper', label: 'PR gatekeeper', order: 1, parent: '/docs/automations' }),
+  ];
+
+  it('returns the parents of a nested page, outermost first', () => {
+    expect(docsNavAncestors(items, '/docs/pr-gatekeeper').map((i) => i.label)).toEqual(['Automations']);
+  });
+
+  it('returns nothing for a top-level page or an unknown one', () => {
+    expect(docsNavAncestors(items, '/docs/automations')).toEqual([]);
+    expect(docsNavAncestors(items, '/docs/nope')).toEqual([]);
+  });
+
+  it('stops on a cycle instead of looping forever', () => {
+    const cyclic = [
+      item({ slug: '/docs/a', label: 'A', parent: '/docs/b' }),
+      item({ slug: '/docs/b', label: 'B', parent: '/docs/a' }),
+    ];
+    expect(docsNavAncestors(cyclic, '/docs/a').length).toBeLessThanOrEqual(1);
+  });
+});
+
 describe('slugifyAnchor', () => {
   // Comprobados uno a uno contra los ids que Scalar pinta en la página.
   it.each([
diff --git a/src/lib/docsNav.ts b/src/lib/docsNav.ts
index 0998e88c..60b0b0bd 100644
--- a/src/lib/docsNav.ts
+++ b/src/lib/docsNav.ts
@@ -13,11 +13,22 @@ export interface DocsNavItem {
   order: number;
   group: string;
   description: string;
+  /**
+   * Slug of the page this one is listed under, if any (same shape as `slug`).
+   * A page with a parent appears as a sub-item right below it, in the
+   * parent's group, and never at the top level as well.
+   */
+  parent?: string;
+}
+
+/** A nav entry with the pages nested under it, already in visual order. */
+export interface DocsNavNode extends DocsNavItem {
+  children: DocsNavNode[];
 }
 
 export interface DocsNavGroup {
   group: string;
-  items: DocsNavItem[];
+  items: DocsNavNode[];
 }
 
 /** A search hit target: a heading inside a docs page. */
@@ -79,29 +90,117 @@ export function apiSearchHeadings(spec: {
  * Whether a nav entry should read as the current page.
  *
  * Prefix matching, not just equality, so a nested route highlights its parent.
- * `/docs` is excluded from the prefix branch or it would highlight on every
- * page of the section.
+ * The docs index (`/docs`, and `/es/docs` for Spanish) is excluded from the
+ * prefix branch or it would highlight on every page of the section. Only
+ * `/docs` used to be excluded, so the Spanish index lit up on every ES page.
  */
+const DOCS_INDEX = /^(\/[a-z]{2})?\/docs$/;
 export function isActiveDocPath(here: string, slug: string): boolean {
   const target = slug.replace(/\/+$/, '');
   const current = here.replace(/\/+$/, '') || '/docs';
-  return current === target || (target !== '/docs' && current.startsWith(`${target}/`));
+  return current === target || (!DOCS_INDEX.test(target) && current.startsWith(`${target}/`));
+}
+
+/** The slug of a guide, from its collection id: `intro` is the docs index. */
+export function docSlug(id: string, pfx = ''): string {
+  return id === 'intro' ? `${pfx}/docs` : `${pfx}/docs/${id}`;
 }
 
 /**
- * Groups the nav, preserving the order the items already carry.
+ * A collection entry as a nav item. Shared by the layout and the tests so the
+ * page and its render test cannot build the nav two different ways.
  *
- * The group order follows the lowest `order` in each group rather than a list
- * written by hand in the layout, so adding a guide stays a matter of creating
- * one file.
+ * `parent` is written in frontmatter as the parent's entry id; the nav speaks
+ * slugs, so it is resolved here with the same locale prefix.
+ */
+export function docsNavItemFromEntry(
+  entry: {
+    id: string;
+    data: { title: string; order: number; group: string; description: string; parent?: string };
+  },
+  pfx = '',
+): DocsNavItem {
+  return {
+    slug: docSlug(entry.id, pfx),
+    label: entry.data.title,
+    order: entry.data.order,
+    group: entry.data.group,
+    description: entry.data.description,
+    parent: entry.data.parent ? docSlug(entry.data.parent, pfx) : undefined,
+  };
+}
+
+/**
+ * The chain of parents of a page, outermost first.
+ *
+ * A `parent` that points nowhere, at the page itself, or into a cycle ends the
+ * chain there: a typo in frontmatter must cost the nesting, never the page.
+ */
+export function docsNavAncestors(items: DocsNavItem[], slug: string): DocsNavItem[] {
+  const bySlug = new Map(items.map((i) => [i.slug, i]));
+  const chain: DocsNavItem[] = [];
+  const seen = new Set<string>([slug]);
+  let parent = bySlug.get(slug)?.parent;
+  while (parent && !seen.has(parent)) {
+    const node = bySlug.get(parent);
+    if (!node) break;
+    seen.add(parent);
+    chain.unshift(node);
+    parent = node.parent;
+  }
+  // Inside a cycle the walk comes back to a page already seen: the chain is
+  // meaningless, so the page is treated as top level.
+  return parent && seen.has(parent) ? [] : chain;
+}
+
+/**
+ * Groups the nav, preserving the order the items already carry, and nests the
+ * pages that declare a `parent` under it.
+ *
+ * The group order follows the lowest `order` among the top-level items of each
+ * group rather than a list written by hand in the layout, so adding a guide
+ * stays a matter of creating one file. A child always sits in its parent's
+ * group, whatever its own `group` says, so a child alone cannot open a section.
  */
 export function groupDocsNav(items: DocsNavItem[]): DocsNavGroup[] {
   const sorted = [...items].sort((a, b) => a.order - b.order);
+  // Nodes are matched to items by position, not by slug: the slug is only
+  // used to resolve `parent`, so two entries sharing one cannot swallow each
+  // other.
+  const nodes: DocsNavNode[] = sorted.map((i) => ({ ...i, children: [] }));
+  const bySlug = new Map<string, DocsNavNode>();
+  for (const n of nodes) if (!bySlug.has(n.slug)) bySlug.set(n.slug, n);
   const groups: DocsNavGroup[] = [];
-  for (const item of sorted) {
-    const existing = groups.find((g) => g.group === item.group);
-    if (existing) existing.items.push(item);
-    else groups.push({ group: item.group, items: [item] });
+  for (const node of nodes) {
+    const ancestors = node.parent ? docsNavAncestors(sorted, node.slug) : [];
+    if (ancestors.length > 0) {
+      bySlug.get(ancestors[ancestors.length - 1].slug)!.children.push(node);
+      continue;
+    }
+    const existing = groups.find((g) => g.group === node.group);
+    if (existing) existing.items.push(node);
+    else groups.push({ group: node.group, items: [node] });
   }
   return groups;
 }
+
+/**
+ * Every page in the order the sidebar shows it: depth first, each child right
+ * after its parent. Prev/next walk this list so they never jump around.
+ */
+export function flattenDocsNav(groups: DocsNavGroup[]): DocsNavItem[] {
+  const out: DocsNavItem[] = [];
+  const walk = (nodes: DocsNavNode[]) => {
+    for (const { children, ...item } of nodes) {
+      out.push(item);
+      walk(children);
+    }
+  };
+  for (const g of groups) walk(g.items);
+  return out;
+}
+
+/** Whether the page or one of the pages nested under it is the current one. */
+export function isActiveDocTrail(here: string, node: DocsNavNode): boolean {
+  return isActiveDocPath(here, node.slug) || node.children.some((c) => isActiveDocTrail(here, c));
+}
diff --git a/src/styles/docs-shell.css b/src/styles/docs-shell.css
index 21accce1..a4ecfec3 100644
--- a/src/styles/docs-shell.css
+++ b/src/styles/docs-shell.css
@@ -334,6 +334,33 @@ body.docs {
   color: var(--doc-accent);
   background: var(--doc-accent-dim);
 }
+/* Keyboard focus: the browser ring is clipped by the drawer's overflow on
+   some engines, so it is drawn inside the link instead. */
+.docs-nav-link:focus-visible {
+  outline: 1px solid var(--doc-accent);
+  outline-offset: -1px;
+}
+
+/* Nested pages (frontmatter `parent`): an indented sub-list hanging from a
+   thin guide line under the parent. The parent of the open page keeps the
+   accent colour without the fill, so the trail reads at a glance while the
+   page itself stays the one highlighted. */
+.docs-nav-link.is-trail {
+  color: var(--doc-accent);
+}
+.docs-nav .docs-nav-sub {
+  margin: 2px 0 2px 10px;
+  padding-left: 8px;
+  border-left: 1px solid var(--doc-bd);
+}
+.docs-nav-sub .docs-nav-link {
+  padding-top: 5px;
+  padding-bottom: 5px;
+  font-size: 11px;
+}
+li.has-children:has(.docs-nav-sub .is-active) > .docs-nav-sub {
+  border-left-color: var(--doc-accent);
+}
 
 /* ── Content pane ────────────────────────────────────────────────────────── */
 .docs-pane {
diff --git a/src/tests/layouts/DocsShell.test.ts b/src/tests/layouts/DocsShell.test.ts
index f594e0bd..35360807 100644
--- a/src/tests/layouts/DocsShell.test.ts
+++ b/src/tests/layouts/DocsShell.test.ts
@@ -161,6 +161,7 @@ describe('frontmatter of the docs collection', () => {
       order?: number;
       group?: string;
       title?: string;
+      parent?: string;
     },
   }));
 
@@ -190,6 +191,38 @@ describe('frontmatter of the docs collection', () => {
     expect(new Set(orders).size, `orders: ${orders.join(', ')}`).toBe(orders.length);
   });
 
+  /**
+   * `parent` nests a page under another in the sidebar. A typo does not fail
+   * the build (the nav falls back to the top level), so it is caught here: the
+   * parent must exist, must not be the page itself, and must share its group,
+   * or the child would silently move to another section.
+   */
+  it('points every `parent` at an existing guide of the same group', () => {
+    const byId = new Map(metas.map((m) => [m.file.replace(/\.(md|mdx)$/, ''), m]));
+    for (const m of metas) {
+      const parent = m.data.parent;
+      if (parent === undefined) continue;
+      const id = m.file.replace(/\.(md|mdx)$/, '');
+      expect(parent, `${m.file}: parent of itself`).not.toBe(id);
+      expect(byId.has(parent), `${m.file}: parent=${parent} does not exist`).toBe(true);
+      expect(byId.get(parent)!.data.group, `${m.file}: parent in another group`).toBe(m.data.group);
+      expect(byId.get(parent)!.data.parent, `${m.file}: nested two levels`).toBeUndefined();
+    }
+  });
+
+  it('places a child right after its parent (or its previous sibling) in the flat order', () => {
+    const byId = new Map(metas.map((m) => [m.file.replace(/\.(md|mdx)$/, ''), m]));
+    for (const m of metas) {
+      if (!m.data.parent) continue;
+      const parentOrder = byId.get(m.data.parent)!.data.order as number;
+      const siblings = metas
+        .filter((s) => s.data.parent === m.data.parent)
+        .map((s) => s.data.order as number)
+        .sort((a, b) => a - b);
+      expect(siblings, `${m.file}: children of ${m.data.parent}`).toEqual(siblings.map((_, i) => parentOrder + 1 + i));
+    }
+  });
+
   it('numbers from zero with no gaps', () => {
     const orders = [...metas.map((m) => m.data.order as number), API_DOC_META.order].sort(
       (a, b) => a - b,
diff --git a/src/tests/layouts/automationsDocs.test.ts b/src/tests/layouts/automationsDocs.test.ts
index 7e98b748..6b053f15 100644
--- a/src/tests/layouts/automationsDocs.test.ts
+++ b/src/tests/layouts/automationsDocs.test.ts
@@ -96,7 +96,9 @@ describe.each(Object.entries(pages))('automations guides (%s)', (_locale, page)
     expect(a.group).toBe(page.group);
     expect(h.group).toBe(page.group);
     expect(a.order).toBe(runs.order + 1);
-    expect(h.order).toBe(runs.order + 2);
+    // The PR gatekeeper guide is nested under Automations (frontmatter
+    // `parent`), so it takes the slot right after it and Webhooks follows.
+    expect(h.order).toBe(a.order + 2);
     for (const later of ['examples.md', 'apps.md']) {
       const o = (parseFrontmatter(read(page.dir + later)).frontmatter as { order: number }).order;
       expect(o, later).toBeGreaterThan(h.order);
diff --git a/src/tests/layouts/docsI18n.test.ts b/src/tests/layouts/docsI18n.test.ts
index 3c35b10d..aba762bb 100644
--- a/src/tests/layouts/docsI18n.test.ts
+++ b/src/tests/layouts/docsI18n.test.ts
@@ -43,6 +43,8 @@ describe('the two guide collections', () => {
       const en = parseFrontmatter(read(resolve(enDir, file))).frontmatter as Record<string, unknown>;
       const es = parseFrontmatter(read(resolve(esDir, esFile))).frontmatter as Record<string, unknown>;
       expect(es.order, `${id}: order`).toBe(en.order);
+      // `parent` is an entry id, not a label, so it is identical in both.
+      expect(es.parent, `${id}: parent`).toBe(en.parent);
     }
   });
 
@@ -112,7 +114,7 @@ describe('the docs layout', () => {
    * segment made every Spanish page show an extra crumb for the docs index.
    */
   it('builds the breadcrumb from the path without the locale prefix', () => {
-    expect(layout).toContain('const breadcrumb = enPath');
+    expect(layout).toContain('const pathCrumbs = enPath');
   });
 
   it('declares both languages to search engines', () => {
diff --git a/src/tests/layouts/docsNavNesting.render.test.ts b/src/tests/layouts/docsNavNesting.render.test.ts
new file mode 100644
index 00000000..17968be1
--- /dev/null
+++ b/src/tests/layouts/docsNavNesting.render.test.ts
@@ -0,0 +1,112 @@
+import { beforeAll, describe, expect, it } from 'vitest';
+import { experimental_AstroContainer as AstroContainer } from 'astro/container';
+import { readFileSync, readdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { parseFrontmatter } from '@astrojs/markdown-remark';
+import DocsSidebarNav from '../../components/docs/DocsSidebarNav.astro';
+import { API_DOC_META, API_DOC_SLUG } from '../../lib/apiDoc';
+import { docsNavItemFromEntry, groupDocsNav, type DocsNavItem } from '../../lib/docsNav';
+
+/**
+ * The docs sidebar, rendered for real from the real guides (EN and ES).
+ *
+ * Owner's ask (2026-10-12): the PR gatekeeper guide must show BELOW
+ * Automations as its sub-item, not as a sibling at the same level. This mounts
+ * the same component the layout uses, fed by the same mapper, and reads the
+ * HTML a browser would get.
+ */
+const here = dirname(fileURLToPath(import.meta.url));
+
+const LOCALES = {
+  en: { dir: '../../content/docs', pfx: '', automations: 'Automations' },
+  es: { dir: '../../content/docs-es', pfx: '/es', automations: 'Automatizaciones' },
+} as const;
+
+/** The nav items the layout builds, from frontmatter instead of the collection. */
+function navItems(lang: keyof typeof LOCALES): DocsNavItem[] {
+  const { dir, pfx } = LOCALES[lang];
+  const abs = resolve(here, dir);
+  const entries = readdirSync(abs)
+    .filter((f) => /\.(md|mdx)$/.test(f))
+    .map((f) => {
+      const fm = parseFrontmatter(readFileSync(resolve(abs, f), 'utf-8')).frontmatter as Record<string, unknown>;
+      return {
+        id: f.replace(/\.(md|mdx)$/, ''),
+        data: {
+          title: String(fm.title),
+          order: Number(fm.order),
+          group: String(fm.group ?? 'Guides'),
+          description: String(fm.description ?? ''),
+          parent: fm.parent as string | undefined,
+        },
+      };
+    });
+  return [
+    ...entries.map((e) => docsNavItemFromEntry(e, pfx)),
+    {
+      slug: `${pfx}/docs/${API_DOC_SLUG}`,
+      label: API_DOC_META.title,
+      order: API_DOC_META.order,
+      group: API_DOC_META.group[lang],
+      description: API_DOC_META.description,
+    },
+  ];
+}
+
+let container: AstroContainer;
+beforeAll(async () => {
+  container = await AstroContainer.create();
+});
+
+/** The sidebar's HTML with whitespace collapsed, for structural matching. */
+async function sidebar(lang: keyof typeof LOCALES, path: string): Promise<string> {
+  const html = await container.renderToString(DocsSidebarNav, {
+    props: { groups: groupDocsNav(navItems(lang)), here: path },
+  });
+  return html.replace(/\s+/g, ' ');
+}
+
+for (const lang of ['en', 'es'] as const) {
+  const { pfx, automations } = LOCALES[lang];
+  const gatekeeper = `${pfx}/docs/pr-gatekeeper`;
+
+  describe(`docs sidebar (${lang})`, () => {
+    it('renders PR gatekeeper inside a nested list right under Automations', async () => {
+      const html = await sidebar(lang, `${pfx}/docs`);
+      const re = new RegExp(
+        `<li class="has-children"[^>]*>\\s*<a href="${pfx}/docs/automations"[^>]*>\\s*${automations}\\s*</a>\\s*` +
+          `<ul class="docs-nav-sub" data-depth="1"[^>]*>\\s*<li[^>]*>\\s*<a href="${gatekeeper}"`,
+      );
+      expect(html).toMatch(re);
+    });
+
+    it('lists PR gatekeeper exactly once', async () => {
+      const html = await sidebar(lang, `${pfx}/docs`);
+      expect(html.match(new RegExp(`href="${gatekeeper}"`, 'g'))).toHaveLength(1);
+    });
+
+    it('keeps Webhooks at the top level, after the Automations block', async () => {
+      const html = await sidebar(lang, `${pfx}/docs`);
+      // Closing the sub-list and the Automations item, then the next sibling.
+      expect(html).toMatch(
+        new RegExp(`href="${gatekeeper}"[\\s\\S]*?</ul>\\s*</li>\\s*<li[^>]*>\\s*<a href="${pfx}/docs/webhooks"`),
+      );
+      expect(html).toMatch(new RegExp(`<ul data-depth="0"[^>]*>[\\s\\S]*href="${pfx}/docs/webhooks"`));
+    });
+
+    it('marks the child as the current page and Automations as the trail when the guide is open', async () => {
+      const html = await sidebar(lang, gatekeeper);
+      expect(html).toMatch(
+        new RegExp(`<a href="${gatekeeper}" class="docs-nav-link is-active" aria-current="page"`),
+      );
+      expect(html).toMatch(new RegExp(`<a href="${pfx}/docs/automations" class="docs-nav-link is-trail"(?! aria-current)`));
+      expect(html.match(/aria-current="page"/g)).toHaveLength(1);
+    });
+
+    it('does not mark the trail on unrelated pages', async () => {
+      const html = await sidebar(lang, `${pfx}/docs/webhooks`);
+      expect(html).not.toContain('is-trail');
+    });
+  });
+}
diff --git a/src/tests/layouts/prGatekeeperDocs.test.ts b/src/tests/layouts/prGatekeeperDocs.test.ts
index 805f66ab..c67007be 100644
--- a/src/tests/layouts/prGatekeeperDocs.test.ts
+++ b/src/tests/layouts/prGatekeeperDocs.test.ts
@@ -142,13 +142,21 @@ describe.each(Object.entries(pages))('PR gatekeeper guide (%s)', (_locale, page)
   const blocks = codeBlocks(body);
   const instructions = blocks.find((b) => b.startsWith('```text')) ?? '';
 
-  test('sits in the guides group, right after Webhooks and before Examples and Apps', () => {
+  /**
+   * Owner's call (2026-10-12): the guide lives UNDER Automations in the
+   * sidebar, as its sub-item, not as a sibling. Its order is the slot right
+   * after Automations so the flat order (the /api/docs manifest) and the
+   * sidebar's visual order agree; Webhooks comes next.
+   */
+  test('is nested under Automations, right after it and before Webhooks', () => {
     expect(fm.title).toBe('PR gatekeeper');
     expect(fm.group).toBe(page.group);
+    expect((fm as { parent?: string }).parent).toBe('automations');
     const order = (f: string) => (parseFrontmatter(read(page.dir + f)).frontmatter as { order: number }).order;
-    expect(fm.order).toBe(order('webhooks.mdx') + 1);
-    expect(order('examples.md')).toBe(fm.order + 1);
-    expect(order('apps.md')).toBe(fm.order + 2);
+    expect(fm.order).toBe(order('automations.mdx') + 1);
+    expect(order('webhooks.mdx')).toBe(fm.order + 1);
+    expect(order('examples.md')).toBe(order('webhooks.mdx') + 1);
+    expect(order('apps.md')).toBe(order('examples.md') + 1);
   });
 
   test('is served by /api/docs without errors', async () => {
diff --git a/vitest.config.ts b/vitest.config.ts
index 44520736..6ae9aece 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -1,10 +1,28 @@
 import { defineConfig } from 'vitest/config';
 
+/*
+ * Two projects. `unit` is the suite as it always was (plain Vite, Node env).
+ * `render` compiles `.astro` components so they can be rendered with Astro's
+ * Container API; it needs Astro's Vite plugins, which live in its own config
+ * (vitest.render.config.ts) because loading them for every file changes how
+ * the other suites resolve modules and breaks several of them.
+ */
+const RENDER_TESTS = 'src/**/*.render.test.ts';
+
 export default defineConfig({
   test: {
-    globals: true,
-    environment: 'node',
-    include: ['src/**/*.test.ts'],
     fileParallelism: false,
+    projects: [
+      {
+        test: {
+          name: 'unit',
+          globals: true,
+          environment: 'node',
+          include: ['src/**/*.test.ts'],
+          exclude: [RENDER_TESTS, '**/node_modules/**'],
+        },
+      },
+      './vitest.render.config.ts',
+    ],
   },
 });
diff --git a/vitest.render.config.ts b/vitest.render.config.ts
new file mode 100644
index 00000000..ef04ecdd
--- /dev/null
+++ b/vitest.render.config.ts
@@ -0,0 +1,20 @@
+import { getViteConfig } from 'astro/config';
+
+/*
+ * Renders `.astro` components under vitest (Astro Container API).
+ *
+ * `configFile: false` on purpose: astro.config.mjs brings the Cloudflare
+ * adapter, whose Vite plugin refuses the SSR environment vitest sets up. The
+ * components rendered here need nothing from that config.
+ */
+export default getViteConfig(
+  {
+    test: {
+      name: 'render',
+      globals: true,
+      environment: 'node',
+      include: ['src/**/*.render.test.ts'],
+    },
+  },
+  { configFile: false },
+);

From 12f448c086ce0f5f5b3c4a2d95ed68c828017678 Mon Sep 17 00:00:00 2001
From: barckcode <cristian@helmcode.com>
Date: Mon, 12 Oct 2026 19:10:54 +0200
Subject: [PATCH 2/2] test(docs): page-level breadcrumb and prev/next for
 nested guides; review notes

- docsNavPage.test.ts: full EN/ES pages from the dev server (breadcrumb
  Docs / Automations / PR gatekeeper, prev/next around the child, sidebar
  trail on the real page)
- DocsShell: pin prev/next to flattenDocsNav; drawer scrolls the current
  page into view when it opens (short phones)
- docsNavAncestors: first entry wins on a repeated slug, as in groupDocsNav;
  stronger cycle assertion and a duplicate-slug test
- ARCHITECTURE: one-level nesting policy and child order rule

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 ARCHITECTURE.md                       |   2 +-
 src/layouts/Docs.astro                |   3 +
 src/lib/docsNav.test.ts               |  18 ++++-
 src/lib/docsNav.ts                    |   4 +-
 src/tests/layouts/DocsShell.test.ts   |  18 +++++
 src/tests/layouts/docsNavPage.test.ts | 100 ++++++++++++++++++++++++++
 6 files changed, 142 insertions(+), 3 deletions(-)
 create mode 100644 src/tests/layouts/docsNavPage.test.ts

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 46ca43fc..214a1671 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -128,7 +128,7 @@ The community-tier signup page (`/community`) reuses `LanguageSwitcher.astro` an
 | `/docs/examples` | Code snippets (Python, Node.js, curl) |
 | `/docs/api` | OpenAI-compatible API reference (endpoints, auth, rate limits) |
 
-Sidebar navigation comes from each guide's frontmatter (`src/content.config.ts`): `group` picks the section, `order` the position, and an optional `parent` (the entry id of another guide, identical in EN and ES) lists the page as an indented sub-item right under that guide, in the parent's group. URLs stay flat (`/docs/<id>`); the breadcrumb and prev/next follow the sidebar's visual order. Logic and tests: `src/lib/docsNav.ts`; markup: `src/components/docs/DocsSidebarNav.astro` + `DocsNavList.astro` (rendered in tests with the Astro Container API, `*.render.test.ts`, see `vitest.render.config.ts`).
+Sidebar navigation comes from each guide's frontmatter (`src/content.config.ts`): `group` picks the section, `order` the position, and an optional `parent` (the entry id of another guide, identical in EN and ES) lists the page as an indented sub-item right under that guide, in the parent's group. The library supports any depth, but content is kept to one level (enforced in `DocsShell.test.ts`), and a child's `order` must be the slot right after its parent so the flat order (`/api/docs` manifest) matches the sidebar. URLs stay flat (`/docs/<id>`); the breadcrumb and prev/next follow the sidebar's visual order. Logic and tests: `src/lib/docsNav.ts`; markup: `src/components/docs/DocsSidebarNav.astro` + `DocsNavList.astro` (rendered in tests with the Astro Container API, `*.render.test.ts`, see `vitest.render.config.ts`).
 
 ### API Endpoints
 
diff --git a/src/layouts/Docs.astro b/src/layouts/Docs.astro
index dc7c09e1..ca1e711e 100644
--- a/src/layouts/Docs.astro
+++ b/src/layouts/Docs.astro
@@ -388,6 +388,9 @@ const searchData = [
           backdrop.hidden = !open;
           menuBtn.setAttribute('aria-expanded', String(open));
           document.body.style.overflow = open ? 'hidden' : '';
+          // A nested or late page can sit below the fold of a short phone:
+          // bring the current link into view so the reader sees where they are.
+          if (open) side.querySelector('[aria-current="page"]')?.scrollIntoView({ block: 'center' });
         };
         menuBtn.addEventListener('click', () => setOpen(!side.classList.contains('open')));
         backdrop.addEventListener('click', () => setOpen(false));
diff --git a/src/lib/docsNav.test.ts b/src/lib/docsNav.test.ts
index 7ecbcfa5..70834315 100644
--- a/src/lib/docsNav.test.ts
+++ b/src/lib/docsNav.test.ts
@@ -173,6 +173,22 @@ describe('groupDocsNav: nesting under a parent', () => {
   });
 });
 
+describe('groupDocsNav: entries sharing a slug', () => {
+  it('keeps both and nests a child under the first of them', () => {
+    const groups = groupDocsNav([
+      item({ slug: '/docs/p', label: 'P1', order: 0 }),
+      item({ slug: '/docs/p', label: 'P2', order: 1 }),
+      item({ slug: '/docs/c', label: 'C', order: 2, parent: '/docs/p' }),
+    ]);
+    expect(groups[0].items.map((i) => i.label)).toEqual(['P1', 'P2']);
+    expect(groups[0].items[0].children.map((c) => c.label)).toEqual(['C']);
+    expect(docsNavAncestors(
+      [item({ slug: '/docs/p', label: 'P1' }), item({ slug: '/docs/p', label: 'P2' }), item({ slug: '/docs/c', parent: '/docs/p' })],
+      '/docs/c',
+    ).map((i) => i.label)).toEqual(['P1']);
+  });
+});
+
 describe('flattenDocsNav: the visual order, for prev/next', () => {
   it('puts each child right after its parent, before the parent\'s next sibling', () => {
     const flat = flattenDocsNav(
@@ -229,7 +245,7 @@ describe('docsNavAncestors: for the breadcrumb', () => {
       item({ slug: '/docs/a', label: 'A', parent: '/docs/b' }),
       item({ slug: '/docs/b', label: 'B', parent: '/docs/a' }),
     ];
-    expect(docsNavAncestors(cyclic, '/docs/a').length).toBeLessThanOrEqual(1);
+    expect(docsNavAncestors(cyclic, '/docs/a')).toEqual([]);
   });
 });
 
diff --git a/src/lib/docsNav.ts b/src/lib/docsNav.ts
index 60b0b0bd..3e898188 100644
--- a/src/lib/docsNav.ts
+++ b/src/lib/docsNav.ts
@@ -137,7 +137,9 @@ export function docsNavItemFromEntry(
  * chain there: a typo in frontmatter must cost the nesting, never the page.
  */
 export function docsNavAncestors(items: DocsNavItem[], slug: string): DocsNavItem[] {
-  const bySlug = new Map(items.map((i) => [i.slug, i]));
+  // First entry wins on a repeated slug, as in groupDocsNav.
+  const bySlug = new Map<string, DocsNavItem>();
+  for (const i of items) if (!bySlug.has(i.slug)) bySlug.set(i.slug, i);
   const chain: DocsNavItem[] = [];
   const seen = new Set<string>([slug]);
   let parent = bySlug.get(slug)?.parent;
diff --git a/src/tests/layouts/DocsShell.test.ts b/src/tests/layouts/DocsShell.test.ts
index 35360807..74175aaa 100644
--- a/src/tests/layouts/DocsShell.test.ts
+++ b/src/tests/layouts/DocsShell.test.ts
@@ -69,6 +69,24 @@ describe('Docs.astro: pieces that must not disappear', () => {
     expect(layout).toContain('aria-label="Pagination"');
   });
 
+  /**
+   * With today's content the raw `order` and the sidebar's visual order agree
+   * (a guard below keeps children right after their parent), so a page-level
+   * test cannot tell them apart. What makes prev/next follow the sidebar when
+   * they diverge is walking flattenDocsNav (unit-tested in docsNav.test.ts),
+   * so that wiring is pinned here.
+   */
+  it('scrolls the current page into view when the mobile drawer opens', () => {
+    expect(layout).toMatch(/if \(open\) side\.querySelector\('\[aria-current="page"\]'\)\?\.scrollIntoView/);
+  });
+
+  it('walks the sidebar\'s visual order for prev/next', () => {
+    expect(layout).toContain('const navOrder = flattenDocsNav(navGroups)');
+    expect(layout).toMatch(/const currentIndex = navOrder\.findIndex/);
+    expect(layout).toMatch(/prevPage = currentIndex > 0 \? navOrder\[currentIndex - 1\]/);
+    expect(layout).toMatch(/navOrder\[currentIndex \+ 1\]/);
+  });
+
   it('keeps the search box with its keyboard shortcut', () => {
     expect(layout).toContain('id="docs-search"');
     expect(layout).toMatch(/metaKey \|\| e\.ctrlKey/);
diff --git a/src/tests/layouts/docsNavPage.test.ts b/src/tests/layouts/docsNavPage.test.ts
new file mode 100644
index 00000000..f344eeba
--- /dev/null
+++ b/src/tests/layouts/docsNavPage.test.ts
@@ -0,0 +1,100 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { startDocsApiServer, type DocsApiServer } from '../helpers/docsApiServer';
+
+/**
+ * The full docs pages, served by the dev server, for what the sidebar render
+ * test cannot see: the breadcrumb and prev/next wired in Docs.astro.
+ *
+ * A nested page (frontmatter `parent`) keeps a flat URL, so its parent is not
+ * in the path: the breadcrumb must slot it in. Prev/next must walk the
+ * sidebar's visual order (child right after its parent), not the raw `order`.
+ */
+let server: DocsApiServer;
+
+const PATHS = ['/docs/pr-gatekeeper', '/docs/automations', '/docs/webhooks'];
+const html = new Map<string, string>();
+
+/*
+ * Every page is fetched once, up front, with a generous budget: the first SSR
+ * of a docs page on a cold dev server compiles the whole collection and can
+ * take longer than vitest's 5s per-test default.
+ */
+beforeAll(async () => {
+  server = await startDocsApiServer();
+  for (const p of PATHS.flatMap((p) => [p, `/es${p}`])) {
+    const res = await server.fetch(p);
+    expect(res.status, p).toBe(200);
+    html.set(p, (await res.text()).replace(/\s+data-astro-source-[a-z]+="[^"]*"/g, '').replace(/\s+/g, ' '));
+  }
+}, 120_000);
+
+afterAll(async () => {
+  await server?.stop();
+});
+
+/** The page HTML without Astro's dev-only source attributes, whitespace collapsed. */
+async function page(path: string): Promise<string> {
+  const body = html.get(path);
+  if (body === undefined) throw new Error(`not prefetched: ${path}`);
+  return body;
+}
+
+const between = (html: string, start: RegExp, end: string) => {
+  const from = html.search(start);
+  expect(from, String(start)).toBeGreaterThanOrEqual(0);
+  return html.slice(from, html.indexOf(end, from));
+};
+
+const LOCALES = [
+  { lang: 'en', pfx: '', automations: 'Automations', webhooks: 'Webhooks and schedules' },
+  { lang: 'es', pfx: '/es', automations: 'Automatizaciones', webhooks: 'Webhooks y programaciones' },
+] as const;
+
+for (const { lang, pfx, automations, webhooks } of LOCALES) {
+  describe(`nested docs page (${lang})`, () => {
+    it('breadcrumb: Docs / parent / current page', async () => {
+      const body = await page(`${pfx}/docs/pr-gatekeeper`);
+      const crumbs = between(body, /<nav class="breadcrumb"/, '</nav>');
+      expect(crumbs).toMatch(
+        new RegExp(
+          `<a href="${pfx}/docs">Docs</a> <span class="separator">/</span> ` +
+            `<a href="${pfx}/docs/automations">${automations}</a> <span class="separator">/</span> ` +
+            `<span class="current">PR gatekeeper</span>`,
+        ),
+      );
+    });
+
+    it('prev/next of the child: its parent, then the parent\'s next sibling', async () => {
+      const body = await page(`${pfx}/docs/pr-gatekeeper`);
+      const pn = between(body, /<nav class="docs-prevnext"/, '</nav>');
+      expect(pn).toMatch(new RegExp(`<a href="${pfx}/docs/automations" class="dpn dpn-prev">.*?${automations}`));
+      expect(pn).toMatch(new RegExp(`<a href="${pfx}/docs/webhooks" class="dpn dpn-next">.*?${webhooks}`));
+    });
+
+    it('next of the parent is its child', async () => {
+      const pn = between(await page(`${pfx}/docs/automations`), /<nav class="docs-prevnext"/, '</nav>');
+      expect(pn).toContain(`<a href="${pfx}/docs/pr-gatekeeper" class="dpn dpn-next">`);
+    });
+
+    it('prev of the parent\'s next sibling is the child', async () => {
+      const pn = between(await page(`${pfx}/docs/webhooks`), /<nav class="docs-prevnext"/, '</nav>');
+      expect(pn).toContain(`<a href="${pfx}/docs/pr-gatekeeper" class="dpn dpn-prev">`);
+    });
+
+    it('a top-level page keeps its plain breadcrumb', async () => {
+      const crumbs = between(await page(`${pfx}/docs/webhooks`), /<nav class="breadcrumb"/, '</nav>');
+      expect(crumbs).not.toContain(`${pfx}/docs/automations`);
+      expect(crumbs).toContain(`<span class="current">${webhooks}</span>`);
+    });
+
+    it('the sidebar of the full page nests the child under its parent', async () => {
+      const side = between(await page(`${pfx}/docs/pr-gatekeeper`), /<nav class="docs-nav"/, '</nav>');
+      expect(side).toMatch(
+        new RegExp(
+          `<a href="${pfx}/docs/automations" class="docs-nav-link is-trail">[^<]*</a> ` +
+            `<ul class="docs-nav-sub" data-depth="1"> <li> <a href="${pfx}/docs/pr-gatekeeper" class="docs-nav-link is-active" aria-current="page">`,
+        ),
+      );
+    });
+  });
+}