From d97118bb6a321eb7dec643e8a675711fe78dfbdd Mon Sep 17 00:00:00 2001 From: Edison Jwa Date: Sat, 13 Jun 2026 03:39:23 +0900 Subject: [PATCH] docs: update spec and plan for Docusaurus consistency --- .../plans/2026-06-13-documentation-site.md | 8 ++- .../2026-06-13-documentation-site-design.md | 60 +++++++++---------- 2 files changed, 33 insertions(+), 35 deletions(-) diff --git a/dev-docs/superpowers/plans/2026-06-13-documentation-site.md b/dev-docs/superpowers/plans/2026-06-13-documentation-site.md index 25e33c7..f0ea676 100644 --- a/dev-docs/superpowers/plans/2026-06-13-documentation-site.md +++ b/dev-docs/superpowers/plans/2026-06-13-documentation-site.md @@ -2,14 +2,16 @@ > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. -**Goal:** Create a private MkDocs Material doc site with tag-based ASPICE traceability, hosted on Cloudflare Pages with access control, served from a git submodule. +**Goal:** Create a private Docusaurus doc site with tag-based ASPICE traceability, hosted on Cloudflare Pages with access control, served from a git submodule. -**Architecture:** The docs repo (`chanora-docs`) is a standalone MkDocs Material project added as a git submodule at `docs/` in the code repo. A custom MkDocs plugin validates requirement ID traceability chains on every build. The code repo retains development-only docs in `dev-docs/`. +**Architecture:** The docs repo (`chanoraapp/docs`) is a standalone Docusaurus project added as a git submodule at `docs/` in the code repo. A custom Docusaurus plugin validates requirement ID traceability chains on every build. The code repo retains development-only docs in `dev-docs/`. -**Tech Stack:** MkDocs Material, Python 3.12, MkDocs tags/git-revision-date-localized plugins, custom traceability plugin (~200 lines Python), GitHub Actions, Cloudflare Pages + Access, git submodules +**Tech Stack:** Docusaurus 3.10 (Meta-maintained), Node.js 20, custom traceability plugin (~100 lines JavaScript), standalone CI validator (Node.js), GitHub Actions, Cloudflare Pages + Access, git submodules **Spec:** `dev-docs/superpowers/specs/2026-06-13-documentation-site-design.md` +> **Note:** This plan was originally written for MkDocs Material. During implementation, MkDocs was replaced with Docusaurus due to MkDocs ecosystem instability (1.x unmaintained, 2.0 breaking). The task descriptions below reference MkDocs but the actual implementation uses Docusaurus 3.10. See the spec for the Docusaurus configuration details. + --- ### Task 1: Create Docs Repo and MkDocs Configuration diff --git a/dev-docs/superpowers/specs/2026-06-13-documentation-site-design.md b/dev-docs/superpowers/specs/2026-06-13-documentation-site-design.md index fd44d02..773ecd8 100644 --- a/dev-docs/superpowers/specs/2026-06-13-documentation-site-design.md +++ b/dev-docs/superpowers/specs/2026-06-13-documentation-site-design.md @@ -35,19 +35,18 @@ Replace the current flat markdown documentation tree with a browseable, searchab ``` chanora-docs/ -├── mkdocs.yml -├── requirements.txt -├── pyproject.toml +├── docusaurus.config.ts +├── sidebars.ts +├── package.json +├── package-lock.json +├── tsconfig.json ├── docs/ │ ├── index.md -│ ├── .meta.yml │ ├── requirements/ -│ │ ├── .meta.yml │ │ ├── sysrs.md │ │ ├── sysdes.md │ │ └── srs.md │ ├── architecture/ -│ │ ├── .meta.yml │ │ ├── sad.md │ │ ├── sdd.md │ │ ├── file-transfer-design.md @@ -55,14 +54,12 @@ chanora-docs/ │ │ ├── file-transfer-implementation-plan.md │ │ └── desktop-ptt-architecture.md │ ├── verification/ -│ │ ├── .meta.yml │ │ ├── verification-master-plan.md │ │ ├── swe4-unit-verification-plan.md │ │ ├── swe5-software-integration-verification-plan.md │ │ ├── swe6-software-verification-plan.md │ │ └── sys4-system-integration-verification-plan.md │ ├── governance/ -│ │ ├── .meta.yml │ │ ├── document-index.md │ │ ├── traceability-matrix.md │ │ ├── product-decision-register.md @@ -76,7 +73,6 @@ chanora-docs/ │ │ ├── path-migration-map.md │ │ └── maintainability-review-2026-06-08.md │ ├── security/ -│ │ ├── .meta.yml │ │ ├── security-privacy-legal-guideline.md │ │ ├── threat-model.md │ │ ├── secure-storage-audit-report.md @@ -95,24 +91,28 @@ chanora-docs/ │ ├── references/ │ │ ├── aspice-swe2-swe3-integration-note.md │ │ ├── external-references.md -│ │ ├── yatqa-en.md (moved from offline-knowledge/external/) -│ │ ├── yatqa-de.md (moved from offline-knowledge/external/) -│ │ ├── teaspeak-overview.md (moved from offline-knowledge/external/) -│ │ └── respeak-overview.md (moved from offline-knowledge/external/) +│ │ ├── yatqa-en.md +│ │ ├── yatqa-de.md +│ │ ├── teaspeak-overview.md +│ │ └── respeak-overview.md │ ├── ui-ux/ │ │ ├── material3-guideline.md │ │ ├── material3-design-tokens.md │ │ ├── material3-component-catalog.md │ │ └── adaptive-layout-platform-guide.md -│ ├── i18n/ -│ │ └── localization-architecture.md -│ └── tags.md +│ └── i18n/ +│ └── localization-architecture.md ├── plugins/ │ └── traceability/ -│ ├── __init__.py -│ └── traceability.py +│ └── index.js ├── scripts/ -│ └── validate_traceability.py +│ ├── validate-traceability.mjs +│ └── add-requirement-tags.mjs +├── src/ +│ ├── pages/index.tsx +│ └── css/custom.css +├── static/ +│ └── img/ ├── .github/ │ └── workflows/ │ └── deploy.yml @@ -317,7 +317,7 @@ status: baseline # Custom metadata for traceability plugin --- ``` -The `tags` field is consumed by the MkDocs Material tags plugin for browsing. The `upstream`, `downstream`, `lifecycle`, and `status` fields are custom metadata consumed by the traceability plugin for chain validation. +The `tags` field is consumed by the Docusaurus tags system for browsing. The `upstream`, `downstream`, `lifecycle`, and `status` fields are custom metadata consumed by the traceability plugin for chain validation. ### 6.2 Tag categories @@ -330,13 +330,9 @@ The `tags` field is consumed by the MkDocs Material tags plugin for browsing. Th | `baseline`, `draft`, `candidate` | Document status | Assessor visibility | | `dec-012`, `dec-020` | Decision register refs | Cross-ref to governance | -### 6.3 Section defaults via `.meta.yml` +### 6.3 Section defaults -```yaml -# docs/verification/.meta.yml -tags: [verification] -status: candidate -``` +Docusaurus uses front matter `tags:` per document. Section-level defaults are not needed since each document carries its own tags. ### 6.4 Verification page trace mappings @@ -351,7 +347,7 @@ status: candidate ### 7.1 Location -`plugins/traceability/traceability.py` — MkDocs plugin, ~200 lines Python. +`plugins/traceability/index.js` — Docusaurus plugin, ~100 lines JavaScript. ### 7.2 Behavior @@ -374,7 +370,7 @@ On `on_post_build` event: ### 7.4 Standalone CI validator -`scripts/validate_traceability.py` — same validation logic, runnable without MkDocs build: +`scripts/validate-traceability.mjs` — same validation logic, runnable without Docusaurus build: ``` python scripts/validate_traceability.py docs/ @@ -388,8 +384,8 @@ Exit code 0 = all chains valid. Exit code 1 = broken chains with details on stde ``` chanora-docs repo → push to main → GitHub Actions - → validate_traceability.py - → mkdocs build --strict + → validate-traceability.mjs + → npm run build → Cloudflare Pages (via Wrangler) → Cloudflare Access policy (email-based auth) ``` @@ -441,7 +437,7 @@ SAD and SDD currently list file paths (`crates/chanora_protocol/src/`) in compon ### 9.3 Cross-reference updates -All backtick path references (`docs/srs.md`) should become markdown links (`[SRS](../srs.md)` or `[SRS](srs.md)`) for both GitHub and MkDocs rendering. +All backtick path references (`docs/srs.md`) should become markdown links (`[SRS](../srs.md)` or `[SRS](srs.md)`) for both GitHub and Docusaurus rendering. ### 9.4 Post-migration @@ -467,6 +463,6 @@ An `AGENTS.md` file will be written at the code repo root documenting: | Item | Reason | When | |---|---|---| | Document provenance records | Convert completed ASPICE plans into provenance evidence | Follow-up task | -| Custom MkDocs traceability plugin | Core feature, built during implementation | Phase 1 | +| Custom Docusaurus traceability plugin | Core feature, built during implementation | Phase 1 | | Cloudflare Pages + Access setup | Requires account creation, domain config | During deployment | | `impl-mapping.md` creation | Extract code paths from SAD/SDD during migration | During migration |