M12: Documentation Site — docs/v0.1.0-docusaurus
Version tag:
docs/v0.1.0-docusaurusPhase: P0: Foundation Target: Weeks 1--2 Sprint: S0
Phase Context
Goal: Consolidate all GospeLib documentation (~30+ markdown files, ~13K lines) into a Docusaurus v3 internal engineering documentation site with OpenAPI integration, full-text search, blog, and private GitHub Pages deployment.
Key constraint: The docs site must deploy behind shared authentication (private GitHub Pages) so only org members can access it. Docusaurus v3 requires React 18.3, isolated from the React 19 apps via pnpm workspaces.
ZenHub Configuration
| Field | Value |
|---|---|
| Milestone | M12: Documentation Site |
| Due Date | 2026-03-22 |
| Default Pipeline | Product Backlog |
| Primary Epic(s) | Docusaurus Scaffold & Content Migration, API Reference & Search, Blog & Deployment |
Prerequisites
None -- M12 executes immediately as the first deliverable. The docs site scaffolding and content migration are independent of other services.
Epic: Docusaurus Scaffold & Content Migration
Scaffold the apps/docs/ Docusaurus v3 application and migrate all existing documentation into the new site structure.
| Story Area | Scope |
|---|---|
| App scaffold | Create apps/docs/ with package.json, project.json, tsconfig.json, Docusaurus config |
| Configuration | docusaurus.config.ts, sidebars.ts, custom CSS with brand colors |
| Directory structure | docs/, blog/, src/, static/ dirs, _category_.json for all subcategories |
| Content migration | Copy + restructure all 30+ docs with frontmatter, kebab-case slugs, category placement |
| Landing page | Custom src/pages/index.tsx with hero, feature grid, quick links |
| Nx integration | project.json targets, pnpm workspace inclusion |
Issues
| Issue | Title | Status | Notes |
|---|---|---|---|
| M12-001 | Scaffold Docusaurus App | ✅ Done | apps/docs exists with package.json, docusaurus.config.ts, sidebars.ts |
| M12-002 | Configure Docusaurus | ✅ Done | Full config with OpenAPI plugin, local search, blog, brand settings, GitHub Pages URL |
| M12-003 | Create Directory Structure and Category Metadata | ✅ Done | _category_.json files in all subdirs |
| M12-004 | Migrate Architecture Docs | ✅ Done | docs/architecture/ with 9 pages and data/security subcategories |
| M12-005 | Migrate Specification Docs | ✅ Done | tech-spec, schemas, comprehensive data-sources pages |
| M12-006 | Migrate Milestone Specs | ✅ Done | All 12 milestone files (M00--M11) + overview.md migrated. PR #1326 |
| M12-007 | Migrate Guides | ✅ Done | docs/guides/ with development/, data/, frontend/, cli/, operations/ (40+ pages) |
| M12-008 | Migrate Service Documentation | ✅ Done | docs/services/ with 8 service subcategories |
| M12-009 | Migrate Product and Business Docs | ✅ Done | 5 of 6 product/business/legal docs migrated. PR #1326 |
| M12-010 | Migrate ADRs | ✅ Done | docs/decisions/ with index, template, 001-monorepo |
| M12-011 | Create Custom Landing Page | ✅ Done | src/pages/index.tsx and index.module.css |
| M12-012 | Nx Integration and Workspace Configuration | ✅ Done | project.json with dev, build, serve, typecheck targets |
Epic: API Reference & Search
| Issue | Title | Status | Notes |
|---|---|---|---|
| M12-013 | Install and Configure OpenAPI Plugin | ✅ Done | docusaurus-plugin-openapi-docs + theme installed; content service spec configured |
| M12-014 | Configure API Docs Generation Pipeline | ✅ Done | docs-deploy.yml runs generate:api before build; docs/api/ stubs |
| M12-015 | Install and Configure Local Search | ✅ Done | @easyops-cn/docusaurus-search-local configured |
| M12-016 | Validate API Reference and Search | ✅ Done | Build passes with zero broken links/anchors |
Epic: Blog & Deployment
| Issue | Title | Status | Notes |
|---|---|---|---|
| M12-017 | Set Up Blog Infrastructure | ✅ Done | Blog enabled with showReadingTime, blogSidebarCount: 10 |
| M12-018 | Create GitHub Actions Deployment Workflow | ✅ Done | docs-deploy.yml with full build + GitHub Pages deploy on push to master |
| M12-019 | Configure GitHub Pages | ✅ Done | Targets github-pages environment with actions/deploy-pages |
| M12-020 | Release Configuration | ✅ Done | docs component in release-please-config.json |
| M12-021 | Update Contribution Documentation | ✅ Done | docs/getting-started/ with 5 guide pages |
Progress: 21 Done · 0 Partial · 0 To Do (100%)
Summary
| Metric | Count |
|---|---|
| Total Issues | 21 |
| Sub-Issues | 0 |
| Total Estimate (pts) | 51 |
| Sprints | S0 |
| Dependencies (blocking) | 22 |
| Dependencies (blocked by) | 28 |