---
phase: 04-docs
plan: 01
subsystem: docs
tags: [mkdocs, mkdocs-material, documentation, css, svg, hero]

# Dependency graph
requires:
  - phase: 03.1-demo-chatbot
    provides: SDK fully implemented — docs can reference actual API signatures

provides:
  - MkDocs Material 9.x site skeleton buildable with mkdocs build --strict
  - Custom meshulash color scheme (#8b5cf6 AIM dashboard purple) via extra.css
  - Hero landing page via overrides/home.html template override
  - Full nav structure (Home, Quickstart, Concepts, Scanners, Deanonymize)
  - Stub pages for all nav entries (Plans 02+03 will fill content)
  - CNAME file preserved across gh-deploy cycles

affects:
  - 04-02 (Quickstart + scanner reference content — depends on mkdocs.yml nav structure)
  - 04-03 (Deanonymize + Concepts content — depends on site skeleton)

# Tech tracking
tech-stack:
  added:
    - mkdocs-material==9.7.3 (installed in .venv)
    - mkdocs==1.6.1 (installed as mkdocs-material dependency)
    - pymdown-extensions==10.21 (bundled)
    - pygments==2.19.2 (bundled)
  patterns:
    - Template override pattern: overrides/home.html extends main.html, overrides tabs block for hero section
    - Custom CSS color scheme: [data-md-color-scheme="meshulash"] CSS vars for AIM purple branding
    - Stub-first nav: all nav pages exist as stubs so build passes; content added incrementally

key-files:
  created:
    - mkdocs.yml
    - docs/stylesheets/extra.css
    - docs/images/logo.svg
    - docs/CNAME
    - overrides/home.html
    - docs/index.md
    - docs/quickstart.md
    - docs/concepts.md
    - docs/scanners/pii.md
    - docs/scanners/topic.md
    - docs/scanners/toxicity.md
    - docs/scanners/cyber.md
    - docs/scanners/jailbreak.md
    - docs/deanonymize.md
  modified: []

key-decisions:
  - "mkdocs-material 9.x installed into project .venv (not global Python)"
  - "Custom color scheme named 'meshulash' in CSS, referenced via theme.palette.scheme in mkdocs.yml"
  - "Logo copied directly from AIM/front/public/Meshulash.svg — no resizing needed for MkDocs header"
  - "CNAME placed in docs/ so mkdocs copies it to site/ and gh-deploy preserves custom domain"
  - "Stub pages created for all nav entries — build passes immediately, content added in Plans 02+03"
  - "MkDocs 2.0 compatibility warning from mkdocs-material is a banner (not a build error) — exit code 0"

patterns-established:
  - "Pattern: All nav pages must exist as stubs before mkdocs build --strict will pass"
  - "Pattern: overrides/ directory holds template customizations; home.html extends main.html and overrides tabs block"
  - "Pattern: custom_dir must be set in mkdocs.yml theme section for template overrides to work"

# Metrics
duration: 2min
completed: 2026-02-26
---

# Phase 4 Plan 01: Docs Site Skeleton Summary

**MkDocs Material 9.x site with AIM purple (#8b5cf6) custom color scheme, hero landing page template override, and full nav skeleton — buildable with mkdocs build --strict**

## Performance

- **Duration:** 2 min
- **Started:** 2026-02-26T20:40:57Z
- **Completed:** 2026-02-26T20:42:56Z
- **Tasks:** 2
- **Files modified:** 14

## Accomplishments

- MkDocs Material 9.7.3 installed and site skeleton buildable (`mkdocs build --strict` exits 0)
- AIM dashboard purple branding applied via custom CSS color scheme (`data-md-color-scheme="meshulash"`)
- Hero landing page with product pitch, CTA buttons (Get Started, Explore Scanners), and quickstart code snippet
- Complete nav structure with 9 pages (all stubs) — ready for content plans 02 and 03

## Task Commits

Each task was committed atomically:

1. **Task 1: Create mkdocs.yml, custom CSS, and copy logo** - `f47ed56` (feat)
2. **Task 2: Create hero landing page template and index.md content** - `bd34b95` (feat)

**Plan metadata:** (docs commit follows)

## Files Created/Modified

- `mkdocs.yml` - Full MkDocs Material config: theme, nav, markdown extensions, AIM purple scheme, social links
- `docs/stylesheets/extra.css` - Custom `meshulash` color scheme with `#8b5cf6` primary and light/dark variants
- `docs/images/logo.svg` - Meshulash logo copied from AIM frontend public assets
- `docs/CNAME` - Contains `docs.meshulash.ai` for GitHub Pages custom domain persistence
- `overrides/home.html` - Hero template: extends `main.html`, overrides `tabs` block with styled hero section
- `docs/index.md` - Landing page: `template: home.html`, hides nav/toc, quickstart pip+Python code snippet
- `docs/quickstart.md` - Stub (`# Quickstart`)
- `docs/concepts.md` - Stub (`# Concepts`)
- `docs/scanners/pii.md` - Stub (`# PIIScanner`)
- `docs/scanners/topic.md` - Stub (`# TopicScanner`)
- `docs/scanners/toxicity.md` - Stub (`# ToxicityScanner`)
- `docs/scanners/cyber.md` - Stub (`# CyberScanner`)
- `docs/scanners/jailbreak.md` - Stub (`# JailbreakScanner`)
- `docs/deanonymize.md` - Stub (`# Deanonymize`)

## Decisions Made

- mkdocs-material installed into project `.venv` (consistent with SDK macOS venv convention)
- Color scheme named `meshulash` — matches `theme.palette.scheme: meshulash` in mkdocs.yml
- Logo copied as-is from AIM frontend; SVG scales cleanly in MkDocs header without adjustment
- CNAME in `docs/` directory (not repo root) so MkDocs copies it to `site/` on every build
- Stub pages created immediately so `--strict` build passes before content is written
- MkDocs 2.0 compatibility warning is an informational banner from mkdocs-material itself — not treated as a build error (exit code still 0)

## Deviations from Plan

None - plan executed exactly as written.

## Issues Encountered

None. The `mkdocs build --strict` warning about MkDocs 2.0 compatibility appears in stderr but does not affect exit code (0) or build output. It is a promotional banner from mkdocs-material, not a lint warning caught by `--strict`.

## User Setup Required

None - no external service configuration required. To serve locally: `.venv/bin/mkdocs serve`

## Next Phase Readiness

- Site skeleton is complete and buildable — Plans 02 and 03 can write content into the stub pages
- All nav entries are wired up in mkdocs.yml — adding content to stubs automatically populates nav
- Hero landing page, custom CSS, and logo are final — no changes needed to site infrastructure
- To deploy: `mkdocs gh-deploy --force` (CNAME in docs/ ensures custom domain persists)

---
*Phase: 04-docs*
*Completed: 2026-02-26*
