Generate a complete MkDocs documentation site with GitHub Pages CI/CD for any TypeScript/Node.js codebase. Covers discovery, architecture, scaffold, content generation, CI/CD setup, and cross-reference verification. Use when setting up docs for a new or existing project.
Generates a complete MkDocs documentation site with GitHub Pages CI/CD for any TypeScript/Node.js codebase.
Phase 0: Pre-flight checks (Python, conflicts, GH Pages status)
Phase 1: Deep codebase discovery (identity, API surface, feature mapping, test examples)
Phase 2: Documentation architecture (nav structure, content plan, diagram plan)
Phase 3: Configuration scaffold (mkdocs.yml, requirements.txt, directory tree, workflow)
3.5: Theme compatibility check (verify features work with chosen theme)
Phase 4: Content generation (home, getting-started, guides, reference, changelog)
Phase 5: GitHub Actions workflow (deploy-pages or mike, enable GH Pages)
Phase 6: Build, test, deploy (local build --strict, PR, merge, verify)
Phase 7: Quality checklist (content, technical, CI/CD, deployment)
Critical path: Phase 1.8 (feature area mapping) determines Phase 2 (nav structure) determines Phase 4 (what pages to write). Get 1.8 right and everything else follows.
| Parameter | Type | Default | Description |
|---|---|---|---|
project_root | path | cwd | Project root directory |
theme | "material" | "readthedocs" | "readthedocs" | MkDocs theme |
site_url | string | inferred from repo | Published URL |
custom_domain | string | null | null | Custom domain (creates CNAME) |
versioning | boolean | false | Enable mike for versioned docs |
api_docs | "typedoc" | "manual" | "none" | "manual" | API docs strategy |
reference_projects | path[] | [] | Projects to match patterns from |
Before starting, verify the environment and check for conflicts.
# Python available?
python3 --version # Need 3.10+
# pip available?
pip --version
# gh CLI available and authenticated?
gh auth status
# Are we in a git repo?
git rev-parse --is-inside-work-tree
Check for existing docs infrastructure:
- docs/ directory → Existing content to migrate or avoid overwriting
- mkdocs.yml → Already configured — update don't overwrite
- .readthedocs.yml → ReadTheDocs hosted — different setup
- requirements.txt → Merge deps, don't overwrite
- .github/workflows/docs* → Existing workflow — update don't duplicate
- site/ in .gitignore → Already excluded (good)
- gh-pages branch → May indicate previous docs deployment
If ANY exist, switch to "update" mode — merge with existing, don't clobber.
# Check if Pages is already configured
gh api "/repos/{OWNER}/{REPO}/pages" 2>/dev/null
# 404 = not configured (we'll set it up)
# 200 = already configured (check build_type, may need update)
Goal: Understand the project completely before writing a single line of docs.
Read and extract:
package.json (or pyproject.toml, Cargo.toml):
- name → site title, install commands
- version → changelog reference
- description → site_description, hero text
- author → site_author, copyright
- license → footer
- repository → repo_url, repo_name
- homepage → site_url fallback
- keywords → SEO, categorization
- engines → prerequisites section
Extract from scripts/Makefile/justfile:
- install command → Installation page
- build command → Contributing page
- test command → Contributing page
- lint command → Contributing page
- any docs command → Existing docs setup (avoid conflicts)
For each directory under src/:
1. List all .ts files (excluding .test.ts, .spec.ts)
2. Identify index.ts / barrel exports
3. Count exported symbols per file
4. Note directory nesting depth
Output: Module map with hierarchy
src/
├── index.ts (re-exports: 25 symbols)
├── types.ts (10 types, 4 interfaces)
├── bus.ts (1 function, 1 interface)
├── transport/
│ └── memory.ts (1 function)
├── store/
│ └── noop.ts (1 function)
└── ...
For EVERY exported symbol, capture:
- Symbol name
- Kind: type | interface | class | function | const | enum
- Module path (e.g., clock/types.ts)
- Signature (params + return type for functions)
- Properties (for interfaces/classes)
- JSDoc/TSDoc comment (if any)
- Generic parameters
- Related symbols (extends, implements, uses)
Critical: Read the main entry point (index.ts) to get the EXACT public API. Only document what's exported.
Identify and document:
- Core abstractions (interfaces that define plugin points)
- Default implementations (what ships out of the box)
- Factory functions (createX pattern)
- Dependency graph (what imports what)
- Extension model (how users plug in custom implementations)
- Signal flow / data flow (how data moves through the system)
Check for:
- README.md → Reuse intro, examples, badges
- CHANGELOG.md → Link or include
- CONTRIBUTING.md → Link or include
- LICENSE → Footer reference
- docs/ directory → Existing content to migrate
- JSDoc comments → Pull into API reference
- Code examples in tests → Extract as doc examples
- Architecture diagrams → Include or recreate
If reference projects provided, extract:
- mkdocs.yml config → Match theme, extensions, features
- docs/ tree structure → Match navigation pattern
- .github/workflows/ → Match CI/CD pattern
- Custom CSS/JS → Match styling
- Plugin choices → Match tooling
This is the most important analysis step. Map the codebase to user-facing feature areas. This determines guide pages.
Heuristic: Group by user capability, not by file/directory.
Step 1: List all factory functions / constructors the user calls directly
(e.g., createSignalBus, createIntervalClock, createFileWatcherSource)
Step 2: Group them by what the user is trying to DO:
- "I want to set up a signal bus" → Signal Bus guide
- "I want to schedule things" → Clock System guide
- "I want to react to external events" → Sources guide
- "I want to customize behavior" → Pluggable Layers guide
Step 3: For each group, identify:
- Primary factory function(s)
- Configuration types/options
- Related interfaces
- Common patterns from tests
- Edge cases / gotchas
Step 4: Order guides by dependency / learning path:
- Core concept first (the thing everything else plugs into)
- Then producers (things that create events/signals)
- Then customization (swappable implementations)
- Then advanced topics (testing, integration)
Key rule: If a user would say "I want to do X" and that X maps to a coherent set of APIs, it's a guide page. If it's a single function with no configuration, it belongs in the reference section, not a dedicated guide.
Tests are the source of truth for working code examples.
For each test file:
1. Scan for describe/it blocks that demonstrate core usage patterns
2. Look for setup patterns (beforeEach) — these show idiomatic initialization
3. Find integration tests — these show multi-component examples
4. Extract the ARRANGE section of arrange-act-assert — this is the user's code
Priority for example extraction:
1. Integration tests (show real-world usage)
2. "basic usage" or "happy path" tests
3. Configuration/options tests (show available options)
4. Edge case tests (show gotchas for "Advanced" sections)
Decision tree based on feature area count (from Phase 1.8 mapping):