20260914-0318-site-explorer-theme Replace the product-docs theme with a site-wide explorer layout

• status: completed
• createdAt: 2026-09-14 03:18
• approvedAt: 2026-09-14 03:25
• relatedTask: 20260914-0317-site-explorer-theme

Context

• What the site is. 266 published pages in a five-level tree: bizplan/governance/ (10), bizplan/product/ (17 package directories, about 60 pages), bizplan/research/ (three topic directories with 32 reports, four vendor categories with 99 records), docs/ (35 tasks, 22 plans, decisions, changelog, architecture, standard). Every directory has an index.md with a typed table, and every page under bizplan/ carries kind and status in frontmatter since 2026-09-14.
• What the theme does today. VitePress 1.6.4 default theme with sidebar: false. Navigation is the top nav (six entries), the breadcrumb above the content, and the directory index tables. The content column is 1104 px inside a 1360 px container after the 2026-09-14 table fix; the right-hand outline shows the current page's headings only. A reader sees one page at a time and must climb the breadcrumb or open an index to see what else exists. That is the "compression" the owner describes: the default theme is built for a linear product manual, not for browsing a corpus.
• What VitePress can do without leaving it. The default theme's sidebar accepts a nested items tree with collapsed groups and multi-sidebar by path prefix; it renders at 272 px width with the content at 688 px, both overridable by CSS variables (--vp-sidebar-width, --vp-layout-max-width) and scoped selectors. The sidebar config is plain data, so it can be generated in config.mts from the file system exactly as the breadcrumb map already is, using frontmatter title, kind and status. The default sidebar does not show icons, badges or file counts, but a custom item slot is not available; badges need either a small custom sidebar component or CSS on the generated text.
• Constraints. Clean URLs and the 63 redirects must keep working; search, DocMeta, the breadcrumb, diagram zoom and the table wrapper stay; docs/templates/ and refs/ stay excluded; the vendor catalogues (99 pages in four folders) must not turn the tree into a wall — folders have to start collapsed.

Proposal

Keep VitePress and the default theme's page machinery; replace navigation with a generated explorer tree and widen the layout. Three parts.

1. Generated site tree (.vitepress/site-tree.ts)

A build-time walker produces one tree of the whole site from the file system: every directory becomes a folder node labelled by its index.md title, every page a leaf labelled by its frontmatter title (H1 fallback), carrying kind and status. Ordering inside a folder: index.md first, then product package slots in slot order (spec, design, guide, brief, evaluations), then the rest alphabetically; research folders follow the order of their index tables where the page appears there. The tree feeds three consumers: the sidebar, the breadcrumb (replacing today's separate map), and a generated /sitemap page (part 3).

2. Explorer layout

• Left: the tree, always visible from 960 px up, as the VitePress sidebar with the generated items. Top-level folders 首页 / 治理文件 / 产品包 / 研究报告 / 供应商目录 / 项目记录; second level open by default, deeper levels collapsed. The vendor categories stay collapsed until opened. The current page is highlighted and its ancestors auto-expand (default theme behaviour).
• Badges on leaves: a small kind chip (规格 / 设计 / 说明 / 报告 / 目录 …) and a status dot (草案 amber, 现行 green, 已取代 grey) rendered with CSS on data attributes, using a lightly customised VPSidebarItem via the theme's Layout slots only if data attributes prove insufficient; the first attempt is pure CSS on the generated link text (文件名 · 规格), which needs no component override.
• Width: --vp-sidebar-width: 320px, --vp-layout-max-width: 1680px, content column 1100 px, outline 220 px on the right. Below 960 px the tree collapses into the existing hamburger drawer (default theme).
• Home page becomes an explorer landing: the same tree rendered as a two-level card grid (area → folders with page counts), replacing the current six feature cards.
• The breadcrumb stays (it is the path within the tree); DocMeta stays; the table wrapper and widths from 2026-09-14 are folded into the new CSS.

3. /sitemap page

A generated Markdown page listing every folder and page with kind and status, one line each, so the whole site can be read as a directory listing and searched with the browser; linked from the nav and the tree root.

Files: .vitepress/site-tree.ts (new), .vitepress/config.mts (sidebar, nav, breadcrumb source), .vitepress/theme/custom.css (layout variables, badges), .vitepress/theme/index.ts (unchanged unless a sidebar component is needed), index.md (home), docs/sitemap.md (generated at build, committed), docs/architecture.md, AGENTS.md (site facts), docs/changelog.md. About 8 files.

Risks

• Tree size. 266 leaves; with second level open and the rest collapsed the initial tree is about 40 rows, which fits a 1080 px viewport. If the owner wants everything open by default, the vendor folders alone are 99 rows.
• Badge rendering. Pure CSS on link text is the low-risk path; a component override of the default sidebar item ties the theme to VitePress internals and becomes an upgrade tripwire like the width overrides already are.
• Generated sidebar and the Chinese search index do not interact; search stays as is.
• Mobile: the drawer shows the same tree; fine.
• Breadcrumb duplication: with the tree visible the breadcrumb is redundant on desktop; keep it for mobile and for copy-paste of the path, or hide it above 960 px — decide at review with the screenshot.

Scope

Theme and configuration only: no Markdown content changes except the home page and the generated sitemap page; no change to the standard, lint or redirects. Verification: bun run docs:lint && bun run docs:build && git diff --check, plus screenshots at 1440 px and 1920 px of a product page, a vendor record, a task record and the home page.

Alternatives

• A. Default sidebar, generated, no badges (recommended first step). All of part 1 and the width changes, badges deferred. Two files touched in the theme, one session of work, zero dependence on theme internals. Gives the file-manager tree immediately.
• B. Custom explorer component. A hand-written Vue tree (folder icons, counts, badges, keyboard navigation) mounted in place of the default sidebar. Best fidelity to a file manager, roughly three times the work, and every visual detail becomes YBO's to maintain.
• C. Change generator (Astro Starlight, Docusaurus, a custom Vite app). Rejected: the corpus, search tokenizer, Mermaid/ELK, diagram zoom, table wrapper and redirects would all need re-implementing for a navigation change that VitePress can express.
• D. Keep the theme, add a sitemap page only. Cheapest, but the tree is still not visible while reading.

Annotations

• 2026-09-14 03:25 owner: "A" — implement alternative A: generated sidebar tree and the wider layout, badges deferred.
• 2026-09-14 03:45: Completed. Badges (part 2) and the explorer home page remain deferred; the breadcrumb was kept above the content since it doubles as the copyable path.