Mkdocs Site Generator

• Setting up docs for a new or existing TypeScript library
• Adding GitHub Pages deployment to a project
• Migrating from another docs system to MkDocs

Inputs

Phase 0: Pre-Flight Checks

Before starting, verify the environment and check for conflicts.

0.1 Environment

# 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

0.2 Conflict Detection

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.

0.3 GitHub Pages Status

# 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)

Phase 1: Deep Codebase Discovery

Goal: Understand the project completely before writing a single line of docs.

1.1 Project Identity

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

1.2 Build & Dev Commands

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)

1.3 Source Architecture Map

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)
  └── ...

1.4 Public API Surface

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.

1.5 Architecture Patterns

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)

1.6 Existing Documentation Inventory

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

1.7 Reference Project Analysis (Optional)

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

1.8 Feature Area Mapping

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.

1.9 Extract Examples from Tests

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)

Phase 2: Documentation Architecture

2.1 Navigation Structure Decision

Decision tree based on feature area count (from Phase 1.8 mapping):

Small Library (≤ 3 feature areas)