From 374532059724ccc5877e7d5605e79dcc01cbb96e Mon Sep 17 00:00:00 2001
From: Richard Iannone <riannone@me.com>
Date: Thu, 22 Oct 2026 18:31:55 -0400
Subject: [PATCH 1/6] Prepare shared sidebars before Quarto rendering

---
 great_docs/core.py | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/great_docs/core.py b/great_docs/core.py
index b867a50d..795015be 100644
--- a/great_docs/core.py
+++ b/great_docs/core.py
@@ -32,6 +32,7 @@
 from ._website.navigation import github as nav_github
 from ._website.navigation import label as nav_label
 from ._website.navigation import release as nav_release
+from ._website.navigation import shared_sidebar
 from ._website.scripts import script_include, script_tag
 from ._website.seo import description as seo_description
 from ._website.seo import noindex
@@ -16421,6 +16422,13 @@ class Result:
             # ── Pre-render termshow recordings ──────────────────────
             self._prerender_term_player(log)
 
+            # Render each long reference sidebar once rather than on every page.
+            # A versioned build does this in each version's own directory.
+            if watch or not self._config.has_versions:
+                shared = shared_sidebar.prepare(self.build_dir)
+                if shared:
+                    log.detail("Sharing rendered sidebar(s): " + ", ".join(shared))
+
             # ── Step 16: Build site with Quarto ────────────────────────
             step += 1
             log.step_start(step, "Build site with Quarto")
@@ -16428,6 +16436,7 @@ class Result:
                 log.step_done("Starting watch mode...")
                 log.footer(watch_mode=True)
                 self._print_layout_notice()
+                quarto_env[shared_sidebar.PREVIEW_ENV] = "1"
                 subprocess.run(["quarto", "preview", "--no-browser"], env=quarto_env)
                 return
             elif self._config.has_versions:

From e5708734c6ffe80938e3f9b6f47f7f618f2aeef8 Mon Sep 17 00:00:00 2001
From: Richard Iannone <riannone@me.com>
Date: Thu, 22 Oct 2026 18:32:22 -0400
Subject: [PATCH 2/6] Add post-render shared sidebar restoration

---
 great_docs/assets/share-sidebars.py | 223 ++++++++++++++++++++++++++++
 1 file changed, 223 insertions(+)
 create mode 100644 great_docs/assets/share-sidebars.py

diff --git a/great_docs/assets/share-sidebars.py b/great_docs/assets/share-sidebars.py
new file mode 100644
index 00000000..bd1950a3
--- /dev/null
+++ b/great_docs/assets/share-sidebars.py
@@ -0,0 +1,223 @@
+"""
+Copy each shared sidebar into the pages that show it (Quarto post-render)
+
+Before rendering, Great Docs trims each long reference sidebar and adds a
+template page that shows it in full (see `shared_sidebar.py`). This script
+takes the full sidebar from the template, then gives every page that shows
+the trimmed sidebar the full one, with the page's own link marked as current
+and the sections around it open, as Quarto would. It also restores the
+search crumbs Quarto takes from the sidebar and, unless the site is being
+previewed, removes the template.
+
+During `quarto preview`, a re-render of one page doesn't render the
+template again, so the full sidebar is cached in the project.
+"""
+
+import json
+import os
+import re
+from pathlib import Path, PurePosixPath
+
+build_dir = Path.cwd()
+manifest_path = build_dir / "_gd_sidebars.json"
+cache_dir = build_dir / "_gd_sidebars"
+
+_NAV_OPEN = re.compile(r'<nav id="quarto-sidebar"[^>]*>')
+_NAV_TAG = re.compile(r"<(/?)nav[\s>]")
+_UL_TAG = re.compile(r"<(/?)ul(?:\s[^>]*)?>")
+_UL_COLLAPSED = re.compile(
+    r'<ul id="(?P<id>[^"]+)" class="collapse list-unstyled sidebar-section depth\d+ ">'
+)
+
+
+def _nav_bounds(html):
+    """Return where the sidebar's contents start and end, or `None`"""
+    opening = _NAV_OPEN.search(html)
+    if opening is None:
+        return None
+    depth = 1
+    for tag in _NAV_TAG.finditer(html, opening.end()):
+        depth += -1 if tag.group(1) else 1
+        if depth == 0:
+            return opening.end(), tag.start()
+    return None
+
+
+def _offset(page):
+    """Return the prefix Quarto gives links on a page to reach the site root"""
+    depth = len(PurePosixPath(page).parts) - 1
+    return "../" * depth if depth else "./"
+
+
+def _rebase(nav, source, target):
+    """Point the links of a sidebar taken from page `source` at page `target`"""
+    old, new = _offset(source), _offset(target)
+    if old == new:
+        return nav
+    return re.sub(r'(\s(?:href|src)=")' + re.escape(old), lambda m: m.group(1) + new, nav)
+
+
+def _expand(nav, section_id):
+    """Open a collapsed sidebar section, as Quarto does around the current page"""
+    sid = re.escape(section_id)
+    nav = re.sub(
+        r'(<ul id="' + sid + r'" class="collapse list-unstyled sidebar-section depth\d+ )">',
+        r'\1show">',
+        nav,
+        count=1,
+    )
+    return re.sub(
+        r'(class="[^"]*?) collapsed(" data-bs-toggle="collapse" data-bs-target="#'
+        + sid
+        + r'"\s+role="navigation" aria-expanded=)"false"',
+        r'\1\2"true"',
+        nav,
+    )
+
+
+def _for_page(nav, template, page):
+    """Return the template's sidebar as Quarto renders it on `page`"""
+    nav = _rebase(nav, template, page)
+    offset = _offset(page)
+    targets = [offset + page]
+    if page.endswith("/index.html"):
+        targets.append(offset + page[: -len("index.html")])
+    link = re.search(
+        r'<a href="(?:'
+        + "|".join(re.escape(t) for t in targets)
+        + r')" class="sidebar-item-text sidebar-link(?=")',
+        nav,
+    )
+    if link is None:
+        return nav
+
+    # The sections that hold the link, and the link's own section if it has one
+    open_sections = []
+    for tag in _UL_TAG.finditer(nav, 0, link.start()):
+        if tag.group(1):
+            open_sections.pop()
+        else:
+            open_sections.append(tag.group(0))
+    next_item = nav.find("<li", link.end())
+    own = _UL_COLLAPSED.search(nav, link.end(), next_item if next_item != -1 else len(nav))
+
+    nav = nav[: link.end()] + " active" + nav[link.end() :]
+    collapsed = [m.group("id") for m in map(_UL_COLLAPSED.match, open_sections) if m]
+    if own:
+        collapsed.append(own.group("id"))
+    for section_id in collapsed:
+        nav = _expand(nav, section_id)
+    return nav
+
+
+def _rendered_pages(output_dir):
+    """Return the pages this render wrote, relative to the output, or `None` for all"""
+    if os.environ.get("QUARTO_PROJECT_RENDER_ALL"):
+        return None
+    listing = os.environ.get("QUARTO_USE_FILE_FOR_PROJECT_OUTPUT_FILES")
+    if listing:
+        text = Path(listing).read_text(encoding="utf-8")
+    else:
+        text = os.environ.get("QUARTO_PROJECT_OUTPUT_FILES", "")
+    root = output_dir.resolve()
+    pages = set()
+    for line in text.splitlines():
+        if not line.strip():
+            continue
+        path = (build_dir / line.strip()).resolve()
+        try:
+            pages.add(path.relative_to(root).as_posix())
+        except ValueError:
+            continue
+    return pages or None
+
+
+def _share(sidebar, output_dir, rendered):
+    template = sidebar["template"]
+    template_html = output_dir / template
+    cached = cache_dir / f"{sidebar['id']}.html"
+    if template_html.is_file():
+        html = template_html.read_text(encoding="utf-8")
+        bounds = _nav_bounds(html)
+        if bounds is None:
+            return 0
+        nav = html[bounds[0] : bounds[1]]
+        cache_dir.mkdir(exist_ok=True)
+        cached.write_text(nav, encoding="utf-8")
+        # `quarto preview` reads every page it rendered once this script is
+        # done, so the template stays while Great Docs previews the site
+        if not os.environ.get("GREAT_DOCS_PREVIEW"):
+            template_html.unlink()
+            template_html.with_suffix(".md").unlink(missing_ok=True)
+    elif cached.is_file():
+        nav = cached.read_text(encoding="utf-8")
+    else:
+        return 0
+
+    count = 0
+    for page in sidebar["pages"]:
+        if rendered is not None and page not in rendered:
+            continue
+        path = output_dir / page
+        if not path.is_file():
+            continue
+        html = path.read_text(encoding="utf-8")
+        bounds = _nav_bounds(html)
+        if bounds is None:
+            continue
+        html = html[: bounds[0]] + _for_page(nav, template, page) + html[bounds[1] :]
+        path.write_text(html, encoding="utf-8")
+        count += 1
+    return count
+
+
+def _restore_crumbs(output_dir, sidebars):
+    """Give search entries the crumbs Quarto takes from the full sidebar"""
+    path = output_dir / "search.json"
+    if not path.is_file():
+        return
+    crumbs = {}
+    for sidebar in sidebars:
+        crumbs.update(sidebar["crumbs"])
+    entries = json.loads(path.read_text(encoding="utf-8"))
+    changed = False
+    for entry in entries:
+        trail = crumbs.get(str(entry.get("href", "")).split("#", 1)[0])
+        if trail is not None and entry.get("crumbs") != trail:
+            entry["crumbs"] = trail
+            changed = True
+    if changed:
+        path.write_text(json.dumps(entries, indent=2, ensure_ascii=False), encoding="utf-8")
+
+
+def _drop_from_sitemap(output_dir, sidebars):
+    path = output_dir / "sitemap.xml"
+    if not path.is_file():
+        return
+    xml = path.read_text(encoding="utf-8")
+    for sidebar in sidebars:
+        xml = re.sub(
+            r"\s*<url>\s*<loc>[^<]*/" + re.escape(sidebar["template"]) + r"</loc>.*?</url>",
+            "",
+            xml,
+            flags=re.S,
+        )
+    path.write_text(xml, encoding="utf-8")
+
+
+def main():
+    if not manifest_path.is_file():
+        return
+    manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    output_dir = build_dir / manifest["output_dir"]
+    rendered = _rendered_pages(output_dir)
+    for sidebar in manifest["sidebars"]:
+        count = _share(sidebar, output_dir, rendered)
+        if count:
+            print(f"[post-render] Shared the {sidebar['id']} sidebar with {count} page(s)")
+    _restore_crumbs(output_dir, manifest["sidebars"])
+    _drop_from_sitemap(output_dir, manifest["sidebars"])
+
+
+if __name__ == "__main__":
+    main()

From 515d4c8b4bcd27f44be8630a5d16fb0132968d0a Mon Sep 17 00:00:00 2001
From: Richard Iannone <riannone@me.com>
Date: Thu, 22 Oct 2026 18:32:35 -0400
Subject: [PATCH 3/6] Prepare reference sidebars for shared rendering

---
 .../_website/navigation/shared_sidebar.py     | 554 ++++++++++++++++++
 1 file changed, 554 insertions(+)
 create mode 100644 great_docs/_website/navigation/shared_sidebar.py

diff --git a/great_docs/_website/navigation/shared_sidebar.py b/great_docs/_website/navigation/shared_sidebar.py
new file mode 100644
index 00000000..43f690e8
--- /dev/null
+++ b/great_docs/_website/navigation/shared_sidebar.py
@@ -0,0 +1,554 @@
+"""
+Reference sidebars rendered once and shared by their pages
+
+Quarto rebuilds a page's whole sidebar on every page that shows it, so a
+reference sidebar with a thousand links costs a thousand links per page.
+Before rendering, each long sidebar is copied to a `gd-full-<id>` sidebar
+that only a one-page template shows, and the original keeps just the links
+the navbar needs. The pages keep naming the original sidebar, so Quarto
+renders a short one. After rendering, `share-sidebars.py` copies the
+template's sidebar into each page, marks the page's link as current, opens
+the sections around it, and restores the search crumbs Quarto takes from
+the sidebar. The result matches what Quarto renders on its own.
+
+A sidebar is left alone when sharing could change a page, for instance when
+its pages show breadcrumbs or previous and next links, which Quarto also
+builds from the sidebar.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+import os
+import shutil
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass, field
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+from yaml12 import format_yaml, parse_yaml, write_yaml
+
+from ..._utils import QUARTO_YML_HEADER
+from ..._yaml import split_front_matter
+from ..page_metadata import rendered_pages
+
+SIDEBAR_IDS = ("reference", "cli-reference", "mcp-reference")
+"""The sidebars Great Docs generates for its reference sections"""
+
+SCRIPT = "share-sidebars.py"
+"""The post-render script, copied from the package assets into `scripts/`"""
+
+MANIFEST = "_gd_sidebars.json"
+"""What the post-render script needs, written to the build directory"""
+
+FULL_PREFIX = "gd-full-"
+"""Prefix of the id of the full copy of a shared sidebar"""
+
+TEMPLATE_PREFIX = "gd-sidebar-"
+"""Prefix of the name of the page that renders the full sidebar"""
+
+PREVIEW_ENV = "GREAT_DOCS_PREVIEW"
+"""Set for `quarto preview`, which needs the template page to stay in place"""
+
+# Quarto's input formats, each of which renders to `<stem>.html`
+_INPUT_SUFFIXES = (".qmd", ".md", ".markdown", ".rmd", ".Rmd", ".rmarkdown", ".ipynb")
+
+
+def prepare(build_dir: Path) -> list[str]:
+    """
+    Arrange for each long reference sidebar to be rendered once
+
+    Run this after every other change to the project, just before Quarto
+    renders it.
+
+    Parameters
+    ----------
+    build_dir
+        The Quarto project directory.
+
+    Returns
+    -------
+    :
+        The ids of the shared sidebars, empty when none is shared.
+    """
+    quarto_yml = build_dir / "_quarto.yml"
+    if not quarto_yml.is_file():
+        return []
+    text = quarto_yml.read_text(encoding="utf-8")
+    config = parse_yaml(text) or {}
+    website = config.get("website")
+    if not isinstance(website, dict) or not isinstance(website.get("sidebar"), list):
+        return []
+
+    project = _Project(build_dir, config)
+    plans = [plan for sidebar in project.sidebars if (plan := project.plan(sidebar))]
+    plans = project.settle(plans)
+    if not plans:
+        return []
+
+    # Work out the crumbs from the full sidebars before trimming them
+    manifest = {
+        "output_dir": str(config.get("project", {}).get("output-dir", "_site")),
+        "sidebars": [project.manifest_entry(plan) for plan in plans],
+    }
+
+    sidebars = website["sidebar"]
+    for plan in plans:
+        full = {**copy.deepcopy(plan.sidebar), "id": FULL_PREFIX + plan.id}
+        plan.sidebar["contents"] = project.navbar_items(plan.sidebar)
+        sidebars.append(full)
+        for directory in plan.tag_dirs:
+            _tag_directory(build_dir / directory, plan.id)
+        _write_template(build_dir / plan.template, plan)
+
+    project_config = config.setdefault("project", {})
+    entry = f"scripts/{SCRIPT}"
+    post_render = project_config.get("post-render")
+    if post_render is None:
+        project_config["post-render"] = entry
+    else:
+        scripts = post_render if isinstance(post_render, list) else [post_render]
+        if entry not in scripts:
+            project_config["post-render"] = [*scripts, entry]
+
+    (build_dir / "scripts").mkdir(exist_ok=True)
+    shutil.copy2(Path(__file__).parents[2] / "assets" / SCRIPT, build_dir / "scripts" / SCRIPT)
+
+    (build_dir / MANIFEST).write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8")
+
+    with open(quarto_yml, "w", encoding="utf-8") as f:
+        if text.startswith(QUARTO_YML_HEADER):
+            f.write(QUARTO_YML_HEADER)
+        write_yaml(config, f)
+    return [plan.id for plan in plans]
+
+
+@dataclass
+class _Plan:
+    """How one sidebar is shared"""
+
+    sidebar: dict[str, Any]
+    """The sidebar's entry in `_quarto.yml`, trimmed in place when shared"""
+
+    pages: list[str]
+    """Inputs that show the sidebar, relative to the project"""
+
+    implicit: set[str] = field(default_factory=set)
+    """Pages that show the sidebar only because they are listed in it"""
+
+    tag_dirs: list[str] = field(default_factory=list)
+    """Directories whose metadata names the sidebar for its implicit pages"""
+
+    @property
+    def id(self) -> str:
+        return str(self.sidebar["id"])
+
+    @property
+    def template(self) -> str:
+        """The input of the page that renders the full sidebar"""
+        parent = _common_dir(self.pages)
+        return str(PurePosixPath(parent, f"{TEMPLATE_PREFIX}{self.id}.qmd"))
+
+
+class _Project:
+    """The parts of a Quarto project that decide which sidebar a page shows"""
+
+    def __init__(self, build_dir: Path, config: dict[str, Any]):
+        self.build_dir = build_dir
+        self.config = config
+        website = config.get("website", {})
+        self.sidebars: list[dict[str, Any]] = [
+            s for s in website.get("sidebar", []) if isinstance(s, dict)
+        ]
+        navbar = website.get("navbar") if isinstance(website.get("navbar"), dict) else {}
+        self.navbar = [*(navbar.get("left") or []), *(navbar.get("right") or [])]
+        self.page_navigation = bool(website.get("page-navigation"))
+        self.bread_crumbs = website.get("bread-crumbs", True) is not False
+        search = website.get("search")
+        self.merge_navbar_crumbs = not (
+            isinstance(search, dict) and search.get("merge-navbar-crumbs") is False
+        )
+        self._pages = sorted(
+            path.relative_to(build_dir).as_posix() for path in rendered_pages(build_dir, config)
+        )
+        # The first sidebar listing each page, read before any is trimmed
+        self._listed_in: dict[str, str] = {}
+        for sidebar in reversed(self.sidebars):
+            for href in _hrefs(sidebar.get("contents")):
+                self._listed_in[href] = str(sidebar.get("id"))
+        self._unnamed = any(s.get("id") is None for s in self.sidebars)
+        self._meta: dict[str, dict[str, Any]] = {}
+        self._dir_meta: dict[str, dict[str, Any]] = {}
+
+    # ── Reading the project ──────────────────────────────────────────────────
+
+    def page_meta(self, page: str) -> dict[str, Any]:
+        """Return a page's front matter, or `{}` when it has none"""
+        if page not in self._meta:
+            try:
+                content = (self.build_dir / page).read_text(encoding="utf-8")
+            except (OSError, UnicodeDecodeError):
+                content = ""
+            self._meta[page] = dict(split_front_matter(content)[0].data)
+        return self._meta[page]
+
+    def dir_meta(self, directory: str) -> dict[str, Any]:
+        """Return a directory's `_metadata.yml`, or `{}` when it has none"""
+        if directory not in self._dir_meta:
+            meta: Any = None
+            for name in ("_metadata.yml", "_metadata.yaml"):
+                path = self.build_dir / directory / name
+                if path.is_file():
+                    try:
+                        meta = parse_yaml(path.read_text(encoding="utf-8"))
+                    except Exception:
+                        meta = None
+                    break
+            self._dir_meta[directory] = meta if isinstance(meta, dict) else {}
+        return self._dir_meta[directory]
+
+    def option(self, page: str, key: str) -> Any:
+        """Return a page option from its front matter or directory metadata"""
+        meta = self.page_meta(page)
+        if key in meta:
+            return meta[key]
+        for directory in _ancestors(page):
+            if key in self.dir_meta(directory):
+                return self.dir_meta(directory)[key]
+        return None
+
+    def shown_sidebar(self, page: str, tags: dict[str, str] | None = None) -> str | None:
+        """
+        Return the id of the sidebar Quarto shows on a page
+
+        Parameters
+        ----------
+        page
+            The page's input, relative to the project.
+        tags
+            Directory metadata added for sharing, mapping a directory to the
+            sidebar it names.
+
+        Returns
+        -------
+        :
+            The sidebar's id, `""` for a sidebar without one, or `None` when
+            the page shows no sidebar.
+        """
+        explicit = self.page_meta(page).get("sidebar")
+        if explicit is None:
+            for directory in _ancestors(page):
+                if tags and directory in tags:
+                    explicit = tags[directory]
+                    break
+                if "sidebar" in self.dir_meta(directory):
+                    explicit = self.dir_meta(directory)["sidebar"]
+                    break
+        if explicit is False:
+            return None
+        if explicit is not None:
+            if any(s.get("id") == explicit for s in self.sidebars):
+                return str(explicit)
+        return self.containing_sidebar(_output(page))
+
+    def containing_sidebar(self, href: str) -> str | None:
+        """Return the sidebar Quarto picks for a page that names none"""
+        # Quarto matches a missing page option against a sidebar without an
+        # id, so such a sidebar shows on every page that names none
+        if self._unnamed:
+            return ""
+        return self._listed_in.get(href)
+
+    # ── Planning ─────────────────────────────────────────────────────────────
+
+    def plan(self, sidebar: dict[str, Any]) -> _Plan | None:
+        """Plan the sharing of a sidebar, or return `None` when it can't be shared"""
+        sidebar_id = sidebar.get("id")
+        if sidebar_id not in SIDEBAR_IDS or not _shareable(sidebar.get("contents")):
+            return None
+        if len(_hrefs(sidebar["contents"])) <= len(self.navbar_items(sidebar)):
+            return None
+        if any(str(s.get("id", "")).startswith(FULL_PREFIX) for s in self.sidebars):
+            return None
+
+        pages: list[str] = []
+        implicit: set[str] = set()
+        for page in self._pages:
+            if self.shown_sidebar(page) != sidebar_id:
+                continue
+            if self.option(page, "sidebar") is None:
+                implicit.add(page)
+            pages.append(page)
+        # Listed pages Quarto can't read the options of
+        for href in _input_hrefs(sidebar["contents"]):
+            if href.endswith(".ipynb") and (self.build_dir / href).is_file():
+                return None
+        if not pages:
+            return None
+        for page in pages:
+            # Quarto builds breadcrumbs and previous/next links from the sidebar
+            navigation = self.option(page, "page-navigation")
+            if navigation is True or (self.page_navigation and navigation is not False):
+                return None
+            if self.bread_crumbs and self.option(page, "bread-crumbs") is not False:
+                return None
+
+        plan = _Plan(sidebar=sidebar, pages=pages, implicit=implicit)
+        if implicit:
+            root = _common_dir(implicit)
+            if root in ("", "."):
+                return None
+            plan.tag_dirs = [root]
+        if (self.build_dir / plan.template).exists():
+            return None
+        return plan
+
+    def settle(self, plans: list[_Plan]) -> list[_Plan]:
+        """
+        Drop plans whose directory metadata would move another page
+
+        A directory's metadata names the sidebar for every page below it
+        that names none, so it may only cover pages that already show it.
+        """
+        plans = list(plans)
+        while plans:
+            tags = {d: plan.id for plan in plans for d in plan.tag_dirs}
+            bad = None
+            for plan in plans:
+                for directory in plan.tag_dirs:
+                    for page in self._below(directory):
+                        if self.shown_sidebar(page, tags) != self.shown_sidebar(page):
+                            bad = plan
+                            break
+                    # The options of notebooks aren't read here
+                    if bad is None and any(self._notebooks(directory)):
+                        bad = plan
+                    if bad:
+                        break
+                if bad:
+                    break
+            if bad is None:
+                return plans
+            plans.remove(bad)
+        return plans
+
+    def _below(self, directory: str) -> Iterator[str]:
+        prefix = directory.rstrip("/") + "/"
+        return (page for page in self._pages if page.startswith(prefix))
+
+    def _notebooks(self, directory: str) -> Iterator[Path]:
+        for path in (self.build_dir / directory).rglob("*.ipynb"):
+            rel = path.relative_to(self.build_dir)
+            if not any(part.startswith(("_", ".")) for part in rel.parts):
+                yield path
+
+    def navbar_items(self, sidebar: dict[str, Any]) -> list[Any]:
+        """
+        Return the sidebar links that a short sidebar keeps
+
+        Quarto marks the navbar link whose target the sidebar links to as
+        current, so the short sidebar keeps those links (or its first link
+        when the navbar links to none of them).
+        """
+        targets = {_output(_href(item)) for item in self.navbar if _href(item)}
+        kept = [
+            item for item in _leaves(sidebar.get("contents")) if _output(_href(item)) in targets
+        ]
+        if not kept:
+            kept = list(_leaves(sidebar.get("contents")))[:1]
+        short = []
+        for item in kept:
+            if isinstance(item, dict):
+                text = _text(item)
+                item = {"text": text, "href": _href(item)} if text else {"href": _href(item)}
+            short.append(item)
+        return short
+
+    # ── Manifest ─────────────────────────────────────────────────────────────
+
+    def manifest_entry(self, plan: _Plan) -> dict[str, Any]:
+        """Describe a shared sidebar for the post-render script"""
+        crumbs = {}
+        for page in plan.pages:
+            trail = self.crumbs(plan, page)
+            if trail is not None:
+                crumbs[_output(page)] = trail
+        return {
+            "id": plan.id,
+            "template": _output(plan.template),
+            "pages": [_output(page) for page in plan.pages],
+            "crumbs": crumbs,
+        }
+
+    def crumbs(self, plan: _Plan, page: str) -> list[str] | None:
+        """
+        Return the search crumbs Quarto gives a page from the full sidebar
+
+        These are the sections around the page's link and the link itself,
+        after the navbar item that opens the sidebar.
+
+        Returns
+        -------
+        :
+            The crumbs, or `None` when the page has none or they can't be
+            worked out (such as a link without text to a page without a title).
+        """
+        href = _output(page)
+        trail = _trail(plan.sidebar.get("contents"), href)
+        if not trail:
+            return None
+        texts = []
+        for item in trail:
+            text = _text(item)
+            if text is None and _href(item):
+                target = _href(item)
+                if target in self._pages:
+                    title = self.page_meta(target).get("title")
+                    text = title if isinstance(title, str) else None
+                if text is None:
+                    return None
+            texts.append(text)
+        if self.merge_navbar_crumbs:
+            nav_item = self._navbar_item(plan, page)
+            if isinstance(nav_item, dict):
+                text = nav_item.get("text")
+                if isinstance(text, str) and text and texts[0] != text:
+                    texts.insert(0, text)
+        return texts
+
+    def _navbar_item(self, plan: _Plan, page: str) -> Any:
+        """Return the navbar item Quarto pairs with a page's sidebar"""
+        named = page not in plan.implicit
+        for item in self.navbar:
+            href = _href(item)
+            if not href:
+                continue
+            # A page that names its sidebar pairs it with any navbar link
+            if named or self.containing_sidebar(_output(href)) == plan.id:
+                return item
+        return None
+
+
+# ── Sidebar contents ─────────────────────────────────────────────────────────
+
+
+def _shareable(contents: Any) -> bool:
+    """Check that sidebar contents are plain links and sections"""
+    if not isinstance(contents, list):
+        return False
+    for item in contents:
+        if isinstance(item, str):
+            if "*" in item or item == "auto":
+                return False
+        elif isinstance(item, dict):
+            if "auto" in item:
+                return False
+            if "contents" in item and not _shareable(item["contents"]):
+                return False
+        else:
+            return False
+    return True
+
+
+def _leaves(contents: Any) -> Iterator[Any]:
+    """Yield the sidebar's links in order, sections with links included"""
+    for item in contents or []:
+        if _href(item):
+            yield item
+        if isinstance(item, dict) and isinstance(item.get("contents"), list):
+            yield from _leaves(item["contents"])
+
+
+def _hrefs(contents: Any) -> set[str]:
+    return {_output(_href(item)) for item in _leaves(contents)}
+
+
+def _input_hrefs(contents: Any) -> Iterable[str]:
+    return (_href(item) for item in _leaves(contents))
+
+
+def _trail(contents: Any, href: str) -> list[Any]:
+    """Return the sections around a sidebar link and the link, as Quarto finds them"""
+    for item in contents or []:
+        if _output(_href(item)) == href:
+            return [item]
+        if isinstance(item, dict) and isinstance(item.get("contents"), list):
+            inner = _trail(item["contents"], href)
+            if inner:
+                return [item, *inner]
+    return []
+
+
+def _href(item: Any) -> str:
+    """Return a sidebar or navbar item's target as a project path, or `""`"""
+    if isinstance(item, str):
+        href = item
+    elif isinstance(item, dict) and isinstance(item.get("href"), str):
+        href = item["href"]
+    else:
+        return ""
+    href = href.strip()
+    while href.startswith("./"):
+        href = href[2:]
+    return href.lstrip("/")
+
+
+def _text(item: Any) -> str | None:
+    if isinstance(item, dict):
+        for key in ("text", "section"):
+            if isinstance(item.get(key), str):
+                return item[key]
+    return None
+
+
+def _output(href: str) -> str:
+    """Return the output page of a project input, or the target unchanged"""
+    path = PurePosixPath(href)
+    if path.suffix in _INPUT_SUFFIXES:
+        return str(path.with_suffix(".html"))
+    return href
+
+
+def _ancestors(page: str) -> Iterator[str]:
+    """Yield a page's directories, innermost first, ending with the project"""
+    parent = PurePosixPath(page).parent
+    while True:
+        yield "" if str(parent) == "." else str(parent)
+        if str(parent) in (".", ""):
+            return
+        parent = parent.parent
+
+
+def _common_dir(pages: Iterable[str]) -> str:
+    parents = [str(PurePosixPath(page).parent) for page in pages]
+    common = os.path.commonpath(parents) if parents else ""
+    return "" if common == "." else common
+
+
+# ── Writing ──────────────────────────────────────────────────────────────────
+
+
+def _tag_directory(directory: Path, sidebar_id: str) -> None:
+    """Name a sidebar in a directory's metadata, keeping what is there"""
+    path = directory / "_metadata.yaml"
+    if not path.is_file():
+        path = directory / "_metadata.yml"
+    meta: Any = {}
+    if path.is_file():
+        meta = parse_yaml(path.read_text(encoding="utf-8")) or {}
+    meta = {**meta, "sidebar": sidebar_id}
+    path.write_text(format_yaml(meta) + "\n", encoding="utf-8")
+
+
+def _write_template(path: Path, plan: _Plan) -> None:
+    title = plan.sidebar.get("title")
+    meta = {
+        "title": title if isinstance(title, str) and title else plan.id,
+        "sidebar": FULL_PREFIX + plan.id,
+        "search": False,
+        "page-navigation": False,
+        "bread-crumbs": False,
+    }
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(f"---\n{format_yaml(meta)}\n---\n", encoding="utf-8")

From ebd1fef0f878f47a00cc2d455a2843c65410735a Mon Sep 17 00:00:00 2001
From: Richard Iannone <riannone@me.com>
Date: Thu, 22 Oct 2026 18:32:56 -0400
Subject: [PATCH 4/6] Refresh shared sidebars after version rewrites

---
 great_docs/_versioned_build.py | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/great_docs/_versioned_build.py b/great_docs/_versioned_build.py
index aa6f0b33..481ba4f3 100644
--- a/great_docs/_versioned_build.py
+++ b/great_docs/_versioned_build.py
@@ -34,6 +34,7 @@
     version_url_segment,
 )
 from great_docs._website import page_metadata
+from great_docs._website.navigation import shared_sidebar
 
 if TYPE_CHECKING:
     from great_docs._api_diff import ApiSnapshot
@@ -2270,6 +2271,8 @@ def run_versioned_build(  # pragma: no cover
         _prune_missing_sidebar_pages(ver_dir)
         _rewrite_quarto_yml_for_version(ver_dir, entry, latest_tag)
         _sync_status_inline_script(ver_dir)
+        # Last, so the trimmed sidebars reflect every change above
+        shared_sidebar.prepare(ver_dir)
         pages_by_version[entry.tag] = pages
         dir_by_tag[entry.tag] = ver_dir
 

From feb695f43a34edbfc79493b15af99cc94c8dedc2 Mon Sep 17 00:00:00 2001
From: Richard Iannone <riannone@me.com>
Date: Thu, 22 Oct 2026 18:33:10 -0400
Subject: [PATCH 5/6] Document reference sidebar reuse during builds

---
 docs/user_guide/13-building.qmd | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/user_guide/13-building.qmd b/docs/user_guide/13-building.qmd
index a581a81a..37637cfa 100644
--- a/docs/user_guide/13-building.qmd
+++ b/docs/user_guide/13-building.qmd
@@ -54,7 +54,8 @@ package metadata. See [Agent Skills](38-agent-skills.qmd) for details.
 package documentation. See [llms.txt](39-llms-txt.qmd) for details.
 
 11. Quarto renders all the source files into HTML, writing a companion Markdown (`.md`) file beside
-each page as it goes.
+each page as it goes. A long reference sidebar is rendered once and then copied into each of its
+pages, since building it again for every page takes much of the render time on a large API.
 
 After all steps complete, the finished site is in `docs/_site/`.
 

From 98ff92b7bf4ba08810038cb6cde461f829702fc5 Mon Sep 17 00:00:00 2001
From: Richard Iannone <riannone@me.com>
Date: Thu, 22 Oct 2026 18:33:30 -0400
Subject: [PATCH 6/6] Add shared sidebar regression tests

---
 tests/test_shared_sidebar.py | 536 +++++++++++++++++++++++++++++++++++
 1 file changed, 536 insertions(+)
 create mode 100644 tests/test_shared_sidebar.py

diff --git a/tests/test_shared_sidebar.py b/tests/test_shared_sidebar.py
new file mode 100644
index 00000000..c90e6281
--- /dev/null
+++ b/tests/test_shared_sidebar.py
@@ -0,0 +1,536 @@
+"""
+Reference sidebars rendered once and copied into their pages
+
+`shared_sidebar.prepare()` trims each long reference sidebar before Quarto
+renders the project, and `share-sidebars.py` copies the full sidebar into the
+pages afterwards. The rendered pages and search index must match those of a
+plain Quarto render.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import re
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+import yaml
+
+from great_docs._website.navigation import shared_sidebar
+
+_SCRIPT = Path(__file__).parent.parent / "great_docs" / "assets" / shared_sidebar.SCRIPT
+
+_QUARTO_YML = """\
+# Generated by Great Docs - Do not modify this file by hand.
+# Configure settings in great-docs.yml instead.
+
+project:
+  type: website
+  output-dir: _site
+website:
+  title: Shared
+  site-url: https://example.com/shared
+  page-navigation: true
+  navbar:
+    left:
+      - text: Guide
+        href: guide.qmd
+      - text: Reference
+        href: reference/index.qmd
+  sidebar:
+    - id: guide
+      contents:
+        - guide.qmd
+    - id: reference
+      contents:
+        - text: Reference
+          href: reference/index.qmd
+        - section: Classes
+          contents:
+            - text: Frame
+              href: reference/Frame.qmd
+            - section: Frame methods
+              contents:
+                - text: Frame.select
+                  href: reference/Frame.select.qmd
+                - text: Frame.filter
+                  href: reference/Frame.filter.qmd
+        - section: Functions
+          contents:
+            - reference/load.qmd
+    - id: cli-reference
+      title: CLI
+      contents:
+        - text: CLI
+          href: reference/cli/index.qmd
+        - section: group
+          contents:
+            - section: nested
+              contents:
+                - reference/cli/group/run.qmd
+            - reference/cli/group/stop.qmd
+"""
+
+_REFERENCE = "page-navigation: false\nbread-crumbs: false\n"
+_CLI = _REFERENCE + "sidebar: cli-reference\n"
+
+_PAGES = {
+    "index.qmd": "---\ntitle: Home\n---\n\nHome.\n",
+    "guide.qmd": "---\ntitle: Guide\n---\n\nGuide.\n",
+    "reference/_metadata.yml": "gd-auto-generated: true\n",
+    "reference/index.qmd": f"---\ntitle: Reference\n{_REFERENCE}---\n\nIndex.\n",
+    "reference/Frame.qmd": f"---\ntitle: Frame\n{_REFERENCE}---\n\n## Usage\n\nA frame.\n",
+    "reference/Frame.select.qmd": f"---\ntitle: Frame.select\n{_REFERENCE}---\n\nSelect.\n",
+    "reference/Frame.filter.qmd": f"---\ntitle: Frame.filter\n{_REFERENCE}---\n\nFilter.\n",
+    "reference/load.qmd": f'---\ntitle: "[load]{{.doc-object-name}}"\n{_REFERENCE}---\n\nLoad.\n',
+    "reference/cli/index.qmd": f"---\ntitle: CLI\n{_CLI}---\n\nCommands.\n",
+    "reference/cli/group/run.qmd": f"---\ntitle: run\n{_CLI}---\n\nRun.\n",
+    "reference/cli/group/stop.qmd": f"---\ntitle: stop\n{_CLI}---\n\nStop.\n",
+}
+
+
+def _write_project(root: Path, quarto_yml: str = _QUARTO_YML, pages: dict | None = None) -> Path:
+    root.mkdir(parents=True, exist_ok=True)
+    (root / "_quarto.yml").write_text(quarto_yml, encoding="utf-8")
+    for name, text in (_PAGES if pages is None else pages).items():
+        path = root / name
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(text, encoding="utf-8")
+    return root
+
+
+def _config(root: Path) -> dict:
+    return yaml.safe_load((root / "_quarto.yml").read_text(encoding="utf-8"))
+
+
+def _sidebar(config: dict, sidebar_id: str) -> dict:
+    return next(s for s in config["website"]["sidebar"] if s.get("id") == sidebar_id)
+
+
+def _load_script():
+    spec = importlib.util.spec_from_file_location("share_sidebars", _SCRIPT)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+# ── Preparing the project ────────────────────────────────────────────────────
+
+
+def test_prepare_trims_sidebars_and_adds_full_copies(tmp_path: Path):
+    root = _write_project(tmp_path / "proj")
+    original = _config(root)
+
+    assert shared_sidebar.prepare(root) == ["reference", "cli-reference"]
+
+    config = _config(root)
+    # The short sidebar keeps the navbar's link; the full copy keeps everything
+    assert _sidebar(config, "reference")["contents"] == [
+        {"text": "Reference", "href": "reference/index.qmd"}
+    ]
+    full = _sidebar(config, "gd-full-reference")
+    assert full["contents"] == _sidebar(original, "reference")["contents"]
+    # The navbar doesn't link to the CLI sidebar, which keeps its first link
+    assert _sidebar(config, "cli-reference")["contents"] == [
+        {"text": "CLI", "href": "reference/cli/index.qmd"}
+    ]
+    assert _sidebar(config, "gd-full-cli-reference")["title"] == "CLI"
+    # Other sidebars and settings are untouched
+    assert _sidebar(config, "guide") == _sidebar(original, "guide")
+    assert config["project"]["post-render"] == "scripts/share-sidebars.py"
+    assert (root / "scripts" / "share-sidebars.py").read_text() == _SCRIPT.read_text()
+    assert (root / "_quarto.yml").read_text().startswith("# Generated by Great Docs")
+
+
+def test_prepare_names_the_sidebar_for_pages_listed_in_it(tmp_path: Path):
+    root = _write_project(tmp_path / "proj")
+    shared_sidebar.prepare(root)
+
+    # API pages are found by their sidebar, so their directory now names it
+    assert yaml.safe_load((root / "reference" / "_metadata.yml").read_text()) == {
+        "gd-auto-generated": True,
+        "sidebar": "reference",
+    }
+    # CLI pages already name theirs; no other directory gains metadata
+    assert not (root / "reference" / "cli" / "_metadata.yml").exists()
+    # Pages are not edited, so their freeze cache stays valid
+    for name, text in _PAGES.items():
+        if name.endswith(".qmd"):
+            assert (root / name).read_text() == text
+
+
+def test_prepare_writes_templates_and_manifest(tmp_path: Path):
+    root = _write_project(tmp_path / "proj")
+    shared_sidebar.prepare(root)
+
+    template = yaml.safe_load(
+        (root / "reference" / "gd-sidebar-reference.qmd").read_text().split("---\n")[1]
+    )
+    assert template["sidebar"] == "gd-full-reference"
+    assert template["search"] is False
+    assert (root / "reference" / "cli" / "gd-sidebar-cli-reference.qmd").is_file()
+
+    manifest = json.loads((root / shared_sidebar.MANIFEST).read_text())
+    assert manifest["output_dir"] == "_site"
+    reference, cli = manifest["sidebars"]
+    assert reference["template"] == "reference/gd-sidebar-reference.html"
+    assert reference["pages"] == [
+        "reference/Frame.filter.html",
+        "reference/Frame.html",
+        "reference/Frame.select.html",
+        "reference/index.html",
+        "reference/load.html",
+    ]
+    # Crumbs follow Quarto: the navbar item, the sections, then the link text
+    # (or, for a bare path, the page's title)
+    assert reference["crumbs"]["reference/Frame.select.html"] == [
+        "Reference",
+        "Classes",
+        "Frame methods",
+        "Frame.select",
+    ]
+    assert reference["crumbs"]["reference/load.html"] == [
+        "Reference",
+        "Functions",
+        "[load]{.doc-object-name}",
+    ]
+    assert reference["crumbs"]["reference/index.html"] == ["Reference"]
+    # A page naming its sidebar takes the first navbar link's text
+    assert cli["crumbs"]["reference/cli/group/run.html"] == ["Guide", "group", "nested", "run"]
+
+
+def test_prepare_extends_existing_post_render(tmp_path: Path):
+    quarto_yml = _QUARTO_YML.replace(
+        "  output-dir: _site\n", "  output-dir: _site\n  post-render: scripts/mine.py\n"
+    )
+    root = _write_project(tmp_path / "proj", quarto_yml)
+    shared_sidebar.prepare(root)
+
+    assert _config(root)["project"]["post-render"] == [
+        "scripts/mine.py",
+        "scripts/share-sidebars.py",
+    ]
+
+
+def test_prepare_twice_changes_nothing(tmp_path: Path):
+    root = _write_project(tmp_path / "proj")
+    shared_sidebar.prepare(root)
+    before = (root / "_quarto.yml").read_text()
+
+    assert shared_sidebar.prepare(root) == []
+    assert (root / "_quarto.yml").read_text() == before
+
+
+@pytest.mark.parametrize(
+    ("page", "front_matter"),
+    [
+        # Quarto builds breadcrumbs and previous/next links from the sidebar
+        ("reference/Frame.qmd", "title: Frame\npage-navigation: false\n"),
+        ("reference/Frame.qmd", "title: Frame\nbread-crumbs: false\n"),
+    ],
+)
+def test_prepare_skips_sidebar_whose_pages_use_it_otherwise(
+    tmp_path: Path, page: str, front_matter: str
+):
+    pages = {**_PAGES, page: f"---\n{front_matter}---\n\nText.\n"}
+    root = _write_project(tmp_path / "proj", pages=pages)
+
+    assert shared_sidebar.prepare(root) == ["cli-reference"]
+    assert "sidebar" not in (root / "reference" / "_metadata.yml").read_text()
+
+
+def test_prepare_skips_sidebar_when_metadata_would_move_another_page(tmp_path: Path):
+    # A page in the directory that no sidebar lists shows no sidebar today
+    pages = {**_PAGES, "reference/extra.qmd": "---\ntitle: Extra\n---\n\nText.\n"}
+    root = _write_project(tmp_path / "proj", pages=pages)
+
+    assert shared_sidebar.prepare(root) == ["cli-reference"]
+
+
+def test_prepare_skips_generated_contents(tmp_path: Path):
+    quarto_yml = _QUARTO_YML.replace(
+        "            - reference/load.qmd\n", '            - "reference/l*.qmd"\n'
+    )
+    root = _write_project(tmp_path / "proj", quarto_yml)
+
+    assert shared_sidebar.prepare(root) == ["cli-reference"]
+
+
+def test_prepare_skips_sidebar_with_nothing_to_trim(tmp_path: Path):
+    quarto_yml = re.sub(r"    - id: cli-reference\n.*", "", _QUARTO_YML, flags=re.S) + (
+        "    - id: cli-reference\n"
+        "      contents:\n"
+        "        - text: CLI\n"
+        "          href: reference/cli/index.qmd\n"
+    )
+    root = _write_project(tmp_path / "proj", quarto_yml)
+
+    assert shared_sidebar.prepare(root) == ["reference"]
+
+
+def test_prepare_skips_project_without_sidebars(tmp_path: Path):
+    assert shared_sidebar.prepare(tmp_path) == []
+    (tmp_path / "_quarto.yml").write_text("project:\n  type: website\n", encoding="utf-8")
+    assert shared_sidebar.prepare(tmp_path) == []
+    assert (tmp_path / "_quarto.yml").read_text() == "project:\n  type: website\n"
+
+
+def test_prepare_skips_sidebar_listing_a_notebook(tmp_path: Path):
+    # The options of a notebook aren't read, so it may show breadcrumbs
+    quarto_yml = _QUARTO_YML.replace("reference/load.qmd", "reference/load.ipynb")
+    pages = {k: v for k, v in _PAGES.items() if k != "reference/load.qmd"}
+    pages["reference/load.ipynb"] = '{"cells": [], "metadata": {}, "nbformat": 4}\n'
+    root = _write_project(tmp_path / "proj", quarto_yml, pages)
+
+    assert shared_sidebar.prepare(root) == ["cli-reference"]
+
+
+def test_prepare_skips_sidebar_listing_pages_at_the_root(tmp_path: Path):
+    # Naming the sidebar for the project's own directory would reach every page
+    quarto_yml = _QUARTO_YML.replace(
+        "        - text: Reference\n          href: reference/index.qmd\n",
+        "        - text: Reference\n          href: reference/index.qmd\n        - index.qmd\n",
+    )
+    pages = {**_PAGES, "index.qmd": f"---\ntitle: Home\n{_REFERENCE}---\n\nHome.\n"}
+    root = _write_project(tmp_path / "proj", quarto_yml, pages)
+
+    assert shared_sidebar.prepare(root) == ["cli-reference"]
+
+
+def test_prepare_skips_sidebar_whose_template_name_is_taken(tmp_path: Path):
+    pages = {**_PAGES, "reference/gd-sidebar-reference.qmd": "---\ntitle: Mine\n---\n"}
+    root = _write_project(tmp_path / "proj", pages=pages)
+
+    assert shared_sidebar.prepare(root) == ["cli-reference"]
+    assert (root / "reference" / "gd-sidebar-reference.qmd").read_text().endswith("Mine\n---\n")
+
+
+def test_prepare_skips_sidebars_a_sidebar_without_id_takes_over(tmp_path: Path):
+    # Quarto shows a sidebar without an id on every page that names none
+    quarto_yml = _QUARTO_YML.replace("    - id: guide\n      contents:\n", "    - contents:\n")
+    root = _write_project(tmp_path / "proj", quarto_yml)
+
+    assert shared_sidebar.prepare(root) == ["cli-reference"]
+
+
+def test_prepare_reads_options_from_directory_metadata(tmp_path: Path):
+    pages = {
+        name: text.replace(_REFERENCE, "")
+        for name, text in _PAGES.items()
+        if name != "reference/_metadata.yml"
+    }
+    # A page that shows no sidebar stays that way under the directory's metadata
+    pages["reference/plain.qmd"] = "---\ntitle: Plain\nsidebar: false\n---\n\nText.\n"
+    pages["reference/_metadata.yaml"] = _REFERENCE
+    pages["reference/cli/_metadata.yml"] = _REFERENCE
+    root = _write_project(tmp_path / "proj", pages=pages)
+
+    assert shared_sidebar.prepare(root) == ["reference", "cli-reference"]
+    # The directory's own metadata file gains the sidebar
+    assert not (root / "reference" / "_metadata.yml").exists()
+    assert yaml.safe_load((root / "reference" / "_metadata.yaml").read_text()) == {
+        "page-navigation": False,
+        "bread-crumbs": False,
+        "sidebar": "reference",
+    }
+
+
+def test_prepare_leaves_out_crumbs_it_cant_work_out(tmp_path: Path):
+    quarto_yml = _QUARTO_YML.replace(
+        "  navbar:\n    left:\n",
+        "  search:\n    merge-navbar-crumbs: false\n"
+        "  navbar:\n    left:\n      - text: More\n        menu:\n          - guide.qmd\n",
+    )
+    # A bare link to a page without a title has no crumb text
+    pages = {**_PAGES, "reference/load.qmd": f"---\n{_REFERENCE}---\n\nLoad.\n"}
+    root = _write_project(tmp_path / "proj", quarto_yml, pages)
+    shared_sidebar.prepare(root)
+
+    reference = json.loads((root / shared_sidebar.MANIFEST).read_text())["sidebars"][0]
+    assert "reference/load.html" not in reference["crumbs"]
+    # Without merged navbar crumbs, the trail starts at the sidebar
+    assert reference["crumbs"]["reference/Frame.select.html"] == [
+        "Classes",
+        "Frame methods",
+        "Frame.select",
+    ]
+
+
+@pytest.mark.parametrize(
+    "contents",
+    [
+        "auto",
+        ["reference/index.qmd", {"section": "All", "contents": "auto"}],
+        ["reference/index.qmd", {"auto": "reference/*.qmd"}],
+        ["reference/index.qmd", 3],
+    ],
+)
+def test_shareable_rejects_generated_or_unknown_contents(contents):
+    assert not shared_sidebar._shareable(contents)
+
+
+def test_href_normalizes_relative_and_absolute_paths():
+    assert shared_sidebar._href("./reference/a.qmd") == "reference/a.qmd"
+    assert shared_sidebar._href({"href": "/reference/a.qmd"}) == "reference/a.qmd"
+    assert shared_sidebar._href({"text": "No link"}) == ""
+
+
+# ── Copying the sidebar into pages ───────────────────────────────────────────
+
+_NAV = """
+<div class="sidebar-menu-container">
+<ul class="list-unstyled mt-1">
+<li class="sidebar-item">
+  <div class="sidebar-item-container">
+  <a href="../reference/index.html" class="sidebar-item-text sidebar-link"> <span class="menu-text">Index</span></a>
+  </div>
+</li>
+<li class="sidebar-item sidebar-item-section">
+  <div class="sidebar-item-container">
+    <a class="sidebar-item-text sidebar-link text-start collapsed" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-1"  role="navigation" aria-expanded="false"> <span class="menu-text">Deep</span></a>
+    <a class="sidebar-item-toggle text-start collapsed" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-1" role="navigation" aria-expanded="false" aria-label="Toggle section">
+      <i class="bi bi-chevron-right ms-2"></i>
+    </a>
+  </div>
+  <ul id="quarto-sidebar-section-1" class="collapse list-unstyled sidebar-section depth2 ">
+<li class="sidebar-item">
+  <div class="sidebar-item-container">
+  <a href="../reference/sub/b.html" class="sidebar-item-text sidebar-link"> <span class="menu-text">B</span></a>
+  </div>
+</li>
+  </ul>
+</li>
+</ul>
+</div>
+"""
+
+
+def test_for_page_rebases_links_marks_current_and_opens_sections():
+    script = _load_script()
+    nav = script._for_page(_NAV, "reference/gd-sidebar-reference.html", "reference/sub/b.html")
+
+    assert 'href="../../reference/index.html" class="sidebar-item-text sidebar-link">' in nav
+    assert 'href="../../reference/sub/b.html" class="sidebar-item-text sidebar-link active">' in nav
+    assert 'class="collapse list-unstyled sidebar-section depth2 show">' in nav
+    assert "collapsed" not in nav
+    assert 'aria-expanded="false"' not in nav
+
+
+def test_for_page_leaves_other_sections_closed():
+    script = _load_script()
+    nav = script._for_page(_NAV, "reference/gd-sidebar-reference.html", "reference/index.html")
+
+    assert 'href="../reference/index.html" class="sidebar-item-text sidebar-link active">' in nav
+    assert nav.count(" active") == 1
+    assert 'sidebar-section depth2 ">' in nav
+    assert nav.count('aria-expanded="false"') == 2
+
+
+def test_share_keeps_template_while_previewing(tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+    script = _load_script()
+    monkeypatch.setattr(script, "cache_dir", tmp_path / "_gd_sidebars")
+    site = tmp_path / "_site"
+    template = site / "reference" / "gd-sidebar-reference.html"
+    page = site / "reference" / "sub" / "b.html"
+    page.parent.mkdir(parents=True)
+    html = '<body><nav id="quarto-sidebar" class="sidebar">{}</nav></body>'
+    sidebar = {"id": "reference", "template": "reference/gd-sidebar-reference.html"}
+    sidebar["pages"] = ["reference/sub/b.html"]
+
+    # `quarto preview` reads the template after the script runs
+    monkeypatch.setenv(shared_sidebar.PREVIEW_ENV, "1")
+    for previewing in (True, False):
+        if not previewing:
+            monkeypatch.delenv(shared_sidebar.PREVIEW_ENV)
+        template.write_text(html.format(_NAV), encoding="utf-8")
+        page.write_text(html.format(""), encoding="utf-8")
+
+        assert script._share(sidebar, site, None) == 1
+        assert template.exists() is previewing
+        assert 'sub/b.html" class="sidebar-item-text sidebar-link active"' in page.read_text()
+
+
+def test_for_page_without_its_own_link_only_rebases():
+    script = _load_script()
+    nav = script._for_page(_NAV, "reference/gd-sidebar-reference.html", "reference/other.html")
+
+    assert nav == _NAV
+
+
+# ── Rendering with Quarto ────────────────────────────────────────────────────
+
+_needs_quarto = pytest.mark.skipif(shutil.which("quarto") is None, reason="Quarto not installed")
+
+_SIDEBAR_NAV = re.compile(r'<nav id="quarto-sidebar".*?</nav>', re.S)
+
+
+def _render(root: Path, *args: str) -> None:
+    subprocess.run(["quarto", "render", *args], cwd=root, check=True, capture_output=True)
+
+
+def _search(site: Path) -> list[dict]:
+    entries = json.loads((site / "search.json").read_text(encoding="utf-8"))
+    return sorted(entries, key=lambda e: e["objectID"])
+
+
+@pytest.fixture(scope="module")
+def sites(tmp_path_factory: pytest.TempPathFactory) -> tuple[Path, Path]:
+    plain = _write_project(tmp_path_factory.mktemp("plain") / "proj")
+    shared = _write_project(tmp_path_factory.mktemp("shared") / "proj")
+    assert shared_sidebar.prepare(shared) == ["reference", "cli-reference"]
+    _render(plain)
+    _render(shared)
+    return plain / "_site", shared / "_site"
+
+
+@_needs_quarto
+@pytest.mark.parametrize("page", [n.replace(".qmd", ".html") for n in _PAGES if n.endswith(".qmd")])
+def test_rendered_pages_match_plain_render(sites: tuple[Path, Path], page: str):
+    plain, shared = sites
+
+    assert (shared / page).read_text(encoding="utf-8") == (plain / page).read_text(encoding="utf-8")
+
+
+@_needs_quarto
+def test_rendered_pages_show_full_sidebar(sites: tuple[Path, Path]):
+    _, shared = sites
+    nav = _SIDEBAR_NAV.search((shared / "reference" / "Frame.select.html").read_text()).group(0)
+
+    assert nav.count('<a href="') == 5
+    assert (
+        'href="../reference/Frame.select.html" class="sidebar-item-text sidebar-link active"' in nav
+    )
+
+
+@_needs_quarto
+def test_rendered_search_index_matches_plain_render(sites: tuple[Path, Path]):
+    plain, shared = sites
+
+    assert _search(shared) == _search(plain)
+
+
+@_needs_quarto
+def test_rendered_site_drops_templates(sites: tuple[Path, Path]):
+    plain, shared = sites
+
+    assert sorted(p.relative_to(shared) for p in shared.rglob("*.html")) == sorted(
+        p.relative_to(plain) for p in plain.rglob("*.html")
+    )
+    assert "gd-sidebar-" not in (shared / "sitemap.xml").read_text(encoding="utf-8")
+
+
+@_needs_quarto
+def test_rerendering_one_page_reuses_cached_sidebar(sites: tuple[Path, Path]):
+    plain, shared = sites
+    page = shared / "reference" / "cli" / "group" / "run.html"
+    page.unlink()
+
+    # As `quarto preview` does after an edit, render only the changed page
+    _render(shared.parent, "reference/cli/group/run.qmd")
+
+    assert page.read_text(encoding="utf-8") == (
+        plain / "reference" / "cli" / "group" / "run.html"
+    ).read_text(encoding="utf-8")