edison/chanora
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update spec and plan for Docusaurus consistency

Browse Source
This commit is contained in:
Edison Jwa
2026-06-13 03:39:23 +09:00
parent 033cf2d7aa
commit d97118bb6a
2 changed files with 33 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files
dev-docs/superpowers/specs/2026-06-13-documentation-site-design.md
+28 -32
View File
@@ -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 |