镜像站点 · 本页由第三方 GitHub 只读镜像提供,非 GitHub 官方站点,不接受任何登录或凭据输入。前往 github.com
Skip to content

Docs: reconcile BunPress 0.2 output manifest #527

Closed

Description

@chrisbbreuer

Parent: #494
Related: docs/DOCS_ACCURACY_PLAN.md

Problem

bun run docs:build currently renders successfully through the owner-maintained ../../Tools/bunpress checkout, then fails its output-manifest gate because the renderer identity changed from BunPress 0.1.21 to 0.2.0. The new tree adds search-index.json and changes every rendered page, so this is a renderer-wide release boundary rather than an incidental docs-data update.

Observed on 2026-08-10 from clean tracked zig-js main after #526:

  • manifest generator: 0.1.21
  • active owner renderer: 0.2.0
  • added output: search-index.json
  • changed output: every documented HTML page, with substantial byte/hash deltas

Scope

  • Audit the owner BunPress 0.2.0 change and rendered output for intended markup, assets, search-index content, links, escaping, and deterministic ordering.
  • Resolve defects in ../../Tools/bunpress, not through a zig-js-local renderer substitute.
  • Regenerate docs/.data/bunpress-output-v1.json only after the complete rendered-tree diff is reviewed and stable.
  • Make bun run docs:build pass from clean tracked zig-js and BunPress inputs and keep CI reproducible.

No-workaround rules

  • No bypass of --check-manifest, stale-version spoof, selective hash omission, committed dist/, or blanket manifest acceptance without inspecting the renderer-wide change.
  • Do not conflate unrelated source/evidence edits with the renderer upgrade.

Acceptance

  • BunPress 0.2.0 output and search-index.json are audited for correctness, determinism, and safe escaping.
  • Any renderer defect is fixed and tested in the owned BunPress source.
  • bun run docs:manifest records only the accepted final tree and the exact generator identity.
  • Two clean consecutive bun run docs:build runs reproduce the manifest byte-for-byte.
  • The resulting zig-js commit reports flips 0 test262 cases and links the exact BunPress revision used.

Activity

  1. added
    bugSomething isn't working
    dependenciesDependency ownership and offline build policy
    toolingBuild, test, documentation, and developer tooling
    on Aug 10, 2026
  2. chrisbbreuer commented on Aug 11, 2026

    @chrisbbreuer
    MemberAuthor

    Completed and landed on main.

    • Owner renderer fix: stacksjs/bunpress@ae928ff unifies rendered headings, search records, and SEO checks on one slug-reservation path; it covers punctuation, numbered headings, Markdown markup, duplicates, and custom-anchor collisions.
    • Accepted zig-js evidence: f98a34a2 records BunPress 0.2.0, 49 pages, 53 outputs, and tree SHA-256 d301b1cf2a2c8684ed2ac008d0bdc1883d0e52e1e55b4c90c7d3f067f1e19170.

    Audit results:

    • 357 unique search records; maximum stored section text is the configured 800 characters.
    • Every indexed fragment resolves against the corresponding rendered HTML page; 0 missing pages, 0 missing anchors, and 0 duplicate URLs.
    • Search rendering escapes query, URL, breadcrumb, title, and preview text before its controlled match-highlighting markup is inserted.
    • Two independent output directories produced byte-identical manifests, and two subsequent bun run docs:build runs passed the checked-in manifest gate.
    • BunPress: 504/504 tests and TypeScript checking pass.
    • Flips 0 test262 cases.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't workingdependenciesDependency ownership and offline build policytoolingBuild, test, documentation, and developer tooling

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions