Release v1.2.3

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -28,7 +28,7 @@ body:
     attributes:
       label: DocSprout version
       description: Output of `docsprout --version`.
-      placeholder: docsprout 1.2.2
+      placeholder: docsprout 1.2.3
     validations:
       required: true
   - type: input

.github/workflows/publish-docs.yml

@@ -32,7 +32,7 @@ jobs:
       - uses: actions/setup-python@v7
         with:
           python-version: '3.11'
-      - run: python -m pip install "git+https://github.com/ikelaiah/docsprout.git@v1.2.2"
+      - run: python -m pip install "git+https://github.com/ikelaiah/docsprout.git@v1.2.3"
       - run: docsprout check
       - if: inputs.versioned
         run: docsprout check-release

CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 1.2.3
+
+A reading-navigation and style-freshness patch. No configuration, route,
+machine-format, public CSS token or dependency change is required. Update
+package and workflow pins to `v1.2.3`, then rebuild.
+
+### Changed
+
+- Reading pages gain linked breadcrumb navigation, an always-present footer
+  with a back-to-top link, and hover heading anchors on sections.
+- Search highlights every query term with a result count, and the results
+  popover anchors to the search control instead of the page shell.
+- The mobile navigation carries a landmark, and the inline outline opens
+  automatically on the active section.
+- Generated `site.css`, `site.js` and `math.js` carry stable content-hash
+  `?v=` URLs, so rebuilt sites can never serve stale styles or scripts.
+- Tables, admonitions, hero, capability cards and print output are polished;
+  print hides navigation chrome including the sidebar while keeping the
+  footer in ink.
+
+### Fixed
+
+- Breadcrumb separators align on the text baseline with even gutters.
+- The glassmorphic hero title no longer prints as invisible transparent text.
+- Narrow tables no longer force a scroll frame; small tables fit their column.
+
 ## 1.2.2
 
 A reading and link-validation patch. No configuration, route, machine-format,

README.md

@@ -1,6 +1,6 @@
 # 🌱 DocSprout
 
-[![CI](https://github.com/ikelaiah/docsprout/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/ikelaiah/docsprout/actions/workflows/ci.yml?query=branch%3Amain) [![Docs](https://img.shields.io/website?url=https%3A%2F%2Fikelaiah.github.io%2Fdocsprout%2F1.2.2%2F&label=docs)](https://ikelaiah.github.io/docsprout/1.2.2/) [![Latest release](https://img.shields.io/github/v/release/ikelaiah/docsprout?display_name=tag&sort=semver)](https://github.com/ikelaiah/docsprout/releases/latest) [![Python 3.10–3.14](https://img.shields.io/badge/python-3.10%E2%80%933.14-3776AB?logo=python&logoColor=white)](https://github.com/ikelaiah/docsprout/blob/main/docs/qualification.md#supported-python-versions) [![License: MIT](https://img.shields.io/github/license/ikelaiah/docsprout)](https://github.com/ikelaiah/docsprout/blob/main/LICENSE)
+[![CI](https://github.com/ikelaiah/docsprout/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/ikelaiah/docsprout/actions/workflows/ci.yml?query=branch%3Amain) [![Docs](https://img.shields.io/website?url=https%3A%2F%2Fikelaiah.github.io%2Fdocsprout%2F1.2.3%2F&label=docs)](https://ikelaiah.github.io/docsprout/1.2.3/) [![Latest release](https://img.shields.io/github/v/release/ikelaiah/docsprout?display_name=tag&sort=semver)](https://github.com/ikelaiah/docsprout/releases/latest) [![Python 3.10–3.14](https://img.shields.io/badge/python-3.10%E2%80%933.14-3776AB?logo=python&logoColor=white)](https://github.com/ikelaiah/docsprout/blob/main/docs/qualification.md#supported-python-versions) [![License: MIT](https://img.shields.io/github/license/ikelaiah/docsprout)](https://github.com/ikelaiah/docsprout/blob/main/LICENSE)
 
 ![DocSprout banner — Build documentation people can use.](docs/assets/docsprout-banner.svg)
 
@@ -23,7 +23,7 @@ Open a terminal in your project's top-level folder—the folder that normally
 contains files such as `README.md`, `src/` or `.git/`—and run:
 
 ```bash
-python -m pip install "https://github.com/ikelaiah/docsprout/archive/refs/tags/v1.2.2.zip"
+python -m pip install "https://github.com/ikelaiah/docsprout/archive/refs/tags/v1.2.3.zip"
 docsprout init
 docsprout serve
 ```

docs/architecture.md

@@ -77,6 +77,6 @@ needs no custom CSS; the custom stylesheet mechanism is a deliberately bounded
 escape hatch whose inclusion mechanics DocSprout owns and whose accessibility
 the author owns.
 
-Downstream projects should pin released tags such as `v1.2.2`, never the main
+Downstream projects should pin released tags such as `v1.2.3`, never the main
 branch. The stable boundary and deprecation policy are in [Machine-readable
 contracts](machine-contracts.md).

docs/beginners-guide.md

@@ -26,7 +26,7 @@ that normally contains `README.md` or `src/`.
 Open a terminal in your project folder and run:
 
 ```bash
-python -m pip install "https://github.com/ikelaiah/docsprout/archive/refs/tags/v1.2.2.zip"
+python -m pip install "https://github.com/ikelaiah/docsprout/archive/refs/tags/v1.2.3.zip"
 ```
 
 Then check that the command is available:
@@ -254,7 +254,7 @@ appear in the navigation.
   in [How DocSprout renders Markdown](markdown-showcase.md).
 - Learn the three configuration files in [Configuration](configuration.md).
 - Copy a small working project from the
-  [minimal example](https://github.com/ikelaiah/docsprout/tree/v1.2.2/examples/minimal).
+  [minimal example](https://github.com/ikelaiah/docsprout/tree/v1.2.3/examples/minimal).
 - When you truly want a public site, choose the simpler or historical path in
   [GitHub Pages](github-pages.md).
 - Look up unfamiliar words in the [glossary](glossary.md).

docs/building.md

@@ -24,7 +24,7 @@ asset is local, and `index.html` opens directly in a browser.
 ## Ship a ZIP
 
 ```bash
-docsprout build --release 1.2.2 --offline-archive dist/docsprout-docs-1.2.2.zip
+docsprout build --release 1.2.3 --offline-archive dist/docsprout-docs-1.2.3.zip
 ```
 
 The release label used for an offline archive must start with a letter or

docs/ci-cd.md

@@ -40,7 +40,7 @@ jobs:
         with:
           python-version: "3.12"
       - name: Install DocSprout
-        run: python -m pip install "https://github.com/ikelaiah/docsprout/archive/refs/tags/v1.2.2.zip"
+        run: python -m pip install "https://github.com/ikelaiah/docsprout/archive/refs/tags/v1.2.3.zip"
       - name: Validate the site
         run: docsprout check
       - name: Audit publications
@@ -52,7 +52,7 @@ jobs:
           path: audit.json
 ```
 
-Pin a released tag (`v1.2.2` above), never a branch. `--format json` writes the
+Pin a released tag (`v1.2.3` above), never a branch. `--format json` writes the
 machine-readable report; the artifact keeps it after the job, including when
 the audit fails.
 
@@ -76,7 +76,7 @@ is yours. The same checks in GitLab CI:
 docs-checks:
   image: python:3.12
   script:
-    - python -m pip install "https://github.com/ikelaiah/docsprout/archive/refs/tags/v1.2.2.zip"
+    - python -m pip install "https://github.com/ikelaiah/docsprout/archive/refs/tags/v1.2.3.zip"
     - docsprout check
     - docsprout audit --strict
 ```

docs/customisation.md

@@ -70,8 +70,8 @@ identity asset:
 
 Fields that are not relevant here, such as `banner` and `homepage`, are
 omitted for brevity. You can inspect the complete maintained
-[`docs/docsprout.json`](https://github.com/ikelaiah/docsprout/blob/v1.2.2/docs/docsprout.json)
-and its [local SVG asset](https://github.com/ikelaiah/docsprout/blob/v1.2.2/docs/assets/docsprout-mark.svg).
+[`docs/docsprout.json`](https://github.com/ikelaiah/docsprout/blob/v1.2.3/docs/docsprout.json)
+and its [local SVG asset](https://github.com/ikelaiah/docsprout/blob/v1.2.3/docs/assets/docsprout-mark.svg).
 On generated DocSprout pages, purple is the accent and highlight colour; the
 potted sprout mark (green leaves, brown soil and a beige pot) appears immediately
 before the project name in the top header;

docs/existing-repository.md

@@ -18,7 +18,7 @@ Run both commands from the repository's top-level folder—the one that contains
 `README.md` or `.git/`:
 
 ```bash
-python -m pip install "https://github.com/ikelaiah/docsprout/archive/refs/tags/v1.2.2.zip"
+python -m pip install "https://github.com/ikelaiah/docsprout/archive/refs/tags/v1.2.3.zip"
 docsprout init
 ```
 

docs/github-pages.md

@@ -48,7 +48,7 @@ from feature branches do not deploy Pages.
 workflow are current, it makes no repository changes.
 
 The generated workflow carries a DocSprout ownership marker and pins the reusable
-workflow to the installed release, such as `@v1.2.2`. It never follows
+workflow to the installed release, such as `@v1.2.3`. It never follows
 `@main`. If a recognised managed workflow is older, ordinary setup reports the
 version and leaves it unchanged. Update only that workflow deliberately:
 
@@ -101,13 +101,13 @@ jobs:
       contents: read
       pages: write
       id-token: write
-    uses: ikelaiah/docsprout/.github/workflows/publish-docs.yml@v1.2.2
+    uses: ikelaiah/docsprout/.github/workflows/publish-docs.yml@v1.2.3
     with:
       versioned: false
       release: latest
 ```
 
-The maintained [single-version example](https://github.com/ikelaiah/docsprout/tree/v1.2.2/examples/single-version)
+The maintained [single-version example](https://github.com/ikelaiah/docsprout/tree/v1.2.3/examples/single-version)
 uses this form.
 
 ## Historical site for versioned projects
@@ -129,7 +129,7 @@ jobs:
       contents: read
       pages: write
       id-token: write
-    uses: ikelaiah/docsprout/.github/workflows/publish-docs.yml@v1.2.2
+    uses: ikelaiah/docsprout/.github/workflows/publish-docs.yml@v1.2.3
 ```
 
 Check a historical release locally after creating its tag and before pushing:
@@ -140,7 +140,7 @@ docsprout check-release
 docsprout build-all --output build/docs-site
 ```
 
-The maintained [historical example](https://github.com/ikelaiah/docsprout/tree/v1.2.2/examples/historical)
+The maintained [historical example](https://github.com/ikelaiah/docsprout/tree/v1.2.3/examples/historical)
 uses this form. Follow the [pre-publish checklist](pre-publish-checklist.md)
 for the exact release order.
 

docs/historical-docs.md

@@ -71,6 +71,6 @@ the release check and full build, then push the tag. Use the exact commands in t
 [pre-publish checklist](pre-publish-checklist.md).
 
 The maintained
-[historical example](https://github.com/ikelaiah/docsprout/tree/v1.2.2/examples/historical)
+[historical example](https://github.com/ikelaiah/docsprout/tree/v1.2.3/examples/historical)
 demonstrates two small releases. Its automated test builds the same Git history
 twice and compares every generated byte.

docs/homepage-recipes.md

@@ -18,7 +18,7 @@ which is a top-level setting, are `homepage` values.
 ## See it in DocSprout
 
 DocSprout uses the same configuration on this site. Its
-[`docs/docsprout.json`](https://github.com/ikelaiah/docsprout/blob/v1.2.2/docs/docsprout.json)
+[`docs/docsprout.json`](https://github.com/ikelaiah/docsprout/blob/v1.2.3/docs/docsprout.json)
 uses these exact values for its home-page banner and capability cards:
 
 ```json

docs/migration.md

@@ -3,7 +3,7 @@
 The 1.x upgrades are deliberately boring: v1.0.0 froze the qualified v0.18.1
 surface, and every later 1.x release adds no configuration schema change. Pin
 the released package and workflow, then run the same checks you already use.
-Current guidance targets `v1.2.2`; each section below remains authoritative for
+Current guidance targets `v1.2.3`; each section below remains authoritative for
 its own step.
 
 ## DocKit to DocSprout (1.x rebrand)
@@ -64,7 +64,7 @@ each published release manifest on immutable tags while upgrading.
 ## Upgrade directly from any supported 0.x release
 
 All released 0.x configurations use schema version 1. Upgrade the pinned package
-and workflow to the latest 1.x release (`v1.2.2`), then use this table before
+and workflow to the latest 1.x release (`v1.2.3`), then use this table before
 running `doctor`, `check`, and the appropriate publish build.
 
 | Starting release | Required compatibility work |
@@ -96,6 +96,17 @@ segments and option-like refs, requires the current source to match `HEAD`, and
 requires documentation changes to be committed. These checks make existing
 valid manifests more dependable; they do not change generated routes.
 
+## v1.2.2 to v1.2.3
+
+No configuration or content migration is required. Update package and workflow
+pins to `v1.2.3`, then rebuild. Reading pages gain linked breadcrumb
+navigation, an always-present footer with a back-to-top link, hover heading
+anchors, multi-term search highlighting with result counts, and a search
+popover anchored to the search control. Generated `site.css`, `site.js` and
+`math.js` now carry stable content-hash `?v=` URLs, so rebuilt sites can never
+serve stale styles or scripts from a cache. Print keeps the footer in ink and
+hides navigation chrome including the sidebar.
+
 ## v1.2.1 to v1.2.2
 
 No configuration or content migration is required. Update package and workflow
@@ -284,7 +295,7 @@ the contract qualified by v0.18.1:
 
 1. Pin the package archive or source installation to `v1.0.0` and pin the
    reusable Pages workflow to `@v1.0.0`; never use `main`. For a new upgrade
-   today, pin the latest 1.x release (`v1.2.2`) instead.
+   today, pin the latest 1.x release (`v1.2.3`) instead.
 2. Keep `"schema_version": 1` in `docsprout.json`, `layout.json` and
    `versions.json`. There is no schema rewrite or generated-route migration.
 3. If custom CSS still uses pre-v0.18 generic names such as `--bg`, `--text`
@@ -416,9 +427,9 @@ safe, readable plain code.
 
 Version 1.0 is the formal commitment point for the contracts that v0.18.1
 qualified, and later 1.x releases keep that contract. There is no schema change.
-Before adopting the latest 1.x release (`v1.2.2`):
+Before adopting the latest 1.x release (`v1.2.3`):
 
-1. Upgrade the pinned package and Pages workflow to `v1.2.2` following this
+1. Upgrade the pinned package and Pages workflow to `v1.2.3` following this
    guide's patterns (config-compatible, then rebuild).
 2. Remove references to any pre-v0.18 generic theme token names
    (`--bg`, `--text`, `--interactive`, …) in custom CSS; the `--dk-*` names

docs/pre-publish-checklist.md

@@ -62,18 +62,18 @@ This path updates the public site from a branch such as `main`.
 ## Historical site
 
 This path publishes an immutable site for every listed release. In the example
-below, replace `1.2.2` with your version.
+below, replace `1.2.3` with your version.
 
-1. Add release `1.2.2` and source ref `v1.2.2` to `docs/versions.json`. Set
-   `current` to `1.2.2`.
+1. Add release `1.2.3` and source ref `v1.2.3` to `docs/versions.json`. Set
+   `current` to `1.2.3`.
 2. Run `docsprout check`.
 3. Commit all release files, including package metadata, documentation,
    examples and workflows, on a branch named `release/vX.Y.Z`:
 
    ```bash
    git add pyproject.toml src/docsprout/__init__.py README.md CHANGELOG.md docs .github examples tests
    git diff --cached --check
-   git commit -m "Prepare v1.2.2 documentation"
+   git commit -m "Prepare v1.2.3 documentation"
    ```
 
 4. Push the qualified branch and open a PR against `main`. Wait for every
@@ -83,7 +83,7 @@ below, replace `1.2.2` with your version.
 5. Check out the merged `main` commit and create the tag on that exact commit:
 
    ```bash
-   git tag -a v1.2.2 -m "v1.2.2"
+   git tag -a v1.2.3 -m "v1.2.3"
    ```
 
 6. Run the release checks and historical build:
@@ -100,7 +100,7 @@ below, replace `1.2.2` with your version.
 8. Push the annotated tag (the merge commit is already on `main`):
 
    ```bash
-   git push origin v1.2.2
+   git push origin v1.2.3
    ```
 
 9. Create the GitHub Release from the tag. Confirm both CI and the Documentation
@@ -111,7 +111,7 @@ below, replace `1.2.2` with your version.
 ## If you find a mistake
 
 If the tag exists only on your computer, correct and commit the files, delete
-the local tag with `git tag -d v1.2.2`, then create it again on the corrected
+the local tag with `git tag -d v1.2.3`, then create it again on the corrected
 commit.
 
 If the tag has been pushed, do not move or replace it. Publish the correction

docs/qualification.md

@@ -1,6 +1,6 @@
-# Qualification evidence for DocSprout v1.2.2
+# Qualification evidence for DocSprout v1.2.3
 
-DocSprout v1.2.2 improves keyboard access and reading-page behavior
+DocSprout v1.2.3 improves reading-page navigation, search and style freshness
 while preserving JSON and Markdown layout compatibility and the v1.0.0 stable
 contract. The claims below are the contract that CI and the maintained fixtures
 exercise. Every row names how it is verified. "Supported" means the combination
@@ -287,6 +287,18 @@ site configuration; no schema, route or token value changes:
   distinguish page structure from home-page presentation, and the glossary
   covers the navigation, theme and command vocabulary.
 
+## v1.2.3 additions
+
+- Generated-page tests cover linked breadcrumb navigation, the always-present
+  footer with back-to-top link, hover heading anchors, a search popover
+  anchored to the search control with multi-term highlighting and result
+  counts, the mobile navigation landmark and auto-opening inline outline.
+- Build tests cover stable content-hash `?v=` asset URLs, print rules that
+  hide navigation chrome while keeping the footer in ink, and the shared
+  z-index and sticky-offset token contract.
+- The visual fixture checklist records the manual keyboard, phone-width and
+  progress checks. Browser and screen-reader checks remain manual release steps.
+
 ## v1.2.2 additions
 
 - Generated-page tests cover the skip link, focusable article target, compact

docs/themes.md

@@ -43,7 +43,7 @@ footer—never underlines, signalling hover with a background tint or colour
 shift instead, and buttons never underline.
 
 The maintained
-[single-version example](https://github.com/ikelaiah/docsprout/tree/v1.2.2/examples/single-version)
+[single-version example](https://github.com/ikelaiah/docsprout/tree/v1.2.3/examples/single-version)
 starts in Paper (`"style": "paper"`), so its built opening page shows the
 warm reading surface before a visitor changes the control.
 
@@ -110,7 +110,7 @@ hexadecimal values:
 Test custom colours in both Light and Dark mode. Links, selected navigation and
 keyboard focus must remain easy to see. A preset is safer when you are unsure.
 The maintained
-[minimal example](https://github.com/ikelaiah/docsprout/tree/v1.2.2/examples/minimal)
+[minimal example](https://github.com/ikelaiah/docsprout/tree/v1.2.3/examples/minimal)
 uses the exact teal values shown above; its built links, selected navigation
 and focus state use that accent.
 

docs/versions.json

@@ -1,7 +1,8 @@
 {
   "schema_version": 1,
-  "current": "1.2.2",
+  "current": "1.2.3",
   "versions": [
+    {"release": "1.2.3", "source_ref": "v1.2.3"},
     {"release": "1.2.2", "source_ref": "v1.2.2"},
     {"release": "1.2.1", "source_ref": "v1.2.1"},
     {"release": "1.2.0", "source_ref": "v1.2.0"},

examples/github-pages/.github/workflows/docsprout-pages.yml

@@ -13,7 +13,7 @@ concurrency:
 jobs:
   documentation:
     if: github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
-    uses: ikelaiah/docsprout/.github/workflows/publish-docs.yml@v1.2.2
+    uses: ikelaiah/docsprout/.github/workflows/publish-docs.yml@v1.2.3
     with:
       versioned: false
       release: latest

examples/historical/.github/workflows/documentation.yml

@@ -12,7 +12,7 @@ permissions:
 
 jobs:
   documentation:
-    uses: ikelaiah/docsprout/.github/workflows/publish-docs.yml@v1.2.2
+    uses: ikelaiah/docsprout/.github/workflows/publish-docs.yml@v1.2.3
     permissions:
       contents: read
       pages: write

examples/single-version/.github/workflows/documentation.yml

@@ -12,7 +12,7 @@ permissions:
 
 jobs:
   documentation:
-    uses: ikelaiah/docsprout/.github/workflows/publish-docs.yml@v1.2.2
+    uses: ikelaiah/docsprout/.github/workflows/publish-docs.yml@v1.2.3
     with:
       versioned: false
       release: latest