Appearance
Maturity Model
Every repo should reach Level 3 before moving to the next project.
Level 1: Foundation
| Check | Description |
|---|---|
| VitePress config | docs/.vitepress/config.mts exists |
| Home page | docs/index.md with project overview |
| Getting started | Setup instructions for new developers |
| Auto-deploy | GitHub Actions workflow deploys to Cloudflare Pages |
| Gitignore | docs/.vitepress/dist and cache excluded |
Level 2: Structure
| Check | Description |
|---|---|
| Auto-discovered sidebar | readdirSync in config — new files appear without manual edits |
| Subdirectories | Docs organized in folders (guide/, architecture/, etc.) |
| Local search | search: { provider: 'local' } in config |
| Last updated | lastUpdated: true — shows git commit dates |
Level 3: Decisions & Diagrams
| Check | Description |
|---|---|
| ADR directory | docs/adr/ with template |
| At least one ADR | A real decision recorded (not just the template) |
| Mermaid plugin | vitepress-plugin-mermaid configured |
| At least one diagram | A Mermaid diagram in any doc page |
| Alternatives documented | ADRs include "Why rejected" for alternatives |
Level 4: API & Types
| Check | Description |
|---|---|
| API reference | Documented endpoints (manual or from OpenAPI spec) |
| Data models | Key types/schemas with field descriptions |
| Environment variables | All required env vars documented |
Level 5: Polish
| Check | Description |
|---|---|
| Versioned docs | Docs match release tags |
| Changelog | Release notes page |
| Access control | Cloudflare Zero Trust or similar |