---
phase: 08-mkdocs-infrastructure
plan: "02"
type: execute
wave: 1
depends_on: []
files_modified:
  - mkdocs.yml
  - docs/_config.yml
  - docs/agentic-workflows.md
  - docs/commands.md
  - docs/concepts.md
  - docs/configuration.md
  - docs/development.md
  - docs/index.md
  - docs/installation.md
  - docs/mcp.md
  - docs/obsidian.md
  - docs/paradigms.md
  - docs/quickstart.md
  - docs/troubleshooting.md
  - docs/tutorial.md
  - pyproject.toml
autonomous: true
requirements:
  - INFR-01
  - INFR-03
  - INFR-05
must_haves:
  truths:
    - "`mkdocs build --strict` exits 0 with no warnings"
    - "docs/plans/ content does not appear in site/ build output"
    - "mkdocs.yml exists at project root with theme: name: shadcn"
    - "docs/_config.yml is deleted"
    - "No docs/*.md file contains nav_order: in its front matter"
    - "pyproject.toml dev group includes mkdocs, mkdocs-shadcn, mkdocs-redirects"
  artifacts:
    - path: "mkdocs.yml"
      provides: "MkDocs site configuration"
      contains: "name: shadcn"
    - path: "pyproject.toml"
      provides: "Dev dependency declarations"
      contains: "mkdocs"
  key_links:
    - from: "mkdocs.yml"
      to: "docs/"
      via: "docs_dir: docs"
      pattern: "docs_dir: docs"
    - from: "mkdocs.yml"
      to: "docs/plans/"
      via: "exclude_docs"
      pattern: "exclude_docs"
---

<objective>
Set up the MkDocs build pipeline: create mkdocs.yml at project root, add mkdocs dev dependencies to pyproject.toml, delete docs/_config.yml, strip nav_order: front matter from all 13 public docs files. After this plan, `mkdocs build --strict` must pass.

Purpose: This is the core infrastructure migration — Jekyll config out, MkDocs config in, all 13 docs files in MkDocs-compatible format.
Output: mkdocs.yml, updated pyproject.toml, docs/_config.yml deleted, 13 docs files with clean front matter.
</objective>

<execution_context>
@/Users/shparki/.claude/get-shit-done/workflows/execute-plan.md
@/Users/shparki/.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/phases/08-mkdocs-infrastructure/08-CONTEXT.md
@.planning/phases/08-mkdocs-infrastructure/08-RESEARCH.md

<interfaces>
<!-- Current docs front matter format (Jekyll) — must be migrated to MkDocs format -->
<!-- Jekyll format (present in all 13 public docs/*.md files): -->
<!--   --- -->
<!--   title: Page Title -->
<!--   nav_order: N -->
<!--   --- -->
<!-- MkDocs format (after migration): -->
<!--   --- -->
<!--   title: Page Title -->
<!--   --- -->
<!-- The nav_order: line is removed; title: is kept. -->
<!-- Navigation ordering is controlled by the nav: block in mkdocs.yml, not front matter. -->

<!-- Current pyproject.toml dependency-groups structure: -->
<!-- [dependency-groups] -->
<!-- dev = [ -->
<!--   "commitizen>=4.1", "hatchling", "pre-commit>=4.0", "mypy>=1.13", -->
<!--   "types-networkx>=...", { include-group = "test" }, { include-group = "lint" } -->
<!-- ] -->
<!-- test = ["pytest>=8.3", "pytest-cov>=6.0"] -->
<!-- lint = ["ruff>=0.8"] -->
<!-- semantic-ci = ["sqlite-vec>=0.1"] -->
</interfaces>
</context>

<tasks>

<task type="auto">
  <name>Task 1: Add mkdocs dev dependencies</name>
  <files>pyproject.toml, uv.lock</files>

  <read_first>
    - pyproject.toml — read the [dependency-groups] section (lines 71-83) to understand the existing structure before uv add modifies it
  </read_first>

  <action>
    Run the following command to add mkdocs dependencies to the dev dependency group:
    ```
    uv add --group dev mkdocs mkdocs-shadcn mkdocs-redirects
    ```
    This command:
    - Resolves and installs mkdocs (target: 1.6.1), mkdocs-shadcn (target: 0.10.2), mkdocs-redirects (target: 1.2.2)
    - Updates pyproject.toml [dependency-groups] dev section
    - Updates uv.lock

    Do NOT manually edit pyproject.toml — let uv handle dependency resolution and lock file updates.
  </action>

  <verify>
    <automated>grep -c "mkdocs" pyproject.toml</automated>
  </verify>

  <acceptance_criteria>
    - `grep "mkdocs" pyproject.toml` shows at least 3 matches (mkdocs, mkdocs-shadcn, mkdocs-redirects)
    - `uv run mkdocs --version` exits 0 and prints a version string
    - pyproject.toml [dependency-groups] dev section still contains commitizen, hatchling, pre-commit, mypy entries (uv add must not have removed existing deps)
  </acceptance_criteria>

  <done>pyproject.toml dev group contains mkdocs, mkdocs-shadcn, and mkdocs-redirects; `uv run mkdocs --version` works</done>
</task>

<task type="auto">
  <name>Task 2: Create mkdocs.yml, delete _config.yml, strip nav_order from all docs</name>
  <files>mkdocs.yml, docs/_config.yml, docs/agentic-workflows.md, docs/commands.md, docs/concepts.md, docs/configuration.md, docs/development.md, docs/index.md, docs/installation.md, docs/mcp.md, docs/obsidian.md, docs/paradigms.md, docs/quickstart.md, docs/troubleshooting.md, docs/tutorial.md</files>

  <read_first>
    - docs/_config.yml — read before deleting; use site metadata (title, description, url, baseurl, footer_content) as reference for mkdocs.yml values
    - docs/index.md — read current state; it may already be modified by Plan 01 (three links removed)
    - docs/agentic-workflows.md — check exact front matter format before stripping nav_order
    - docs/commands.md — check exact front matter format before stripping nav_order
    - docs/concepts.md — check exact front matter format
    - docs/configuration.md — check exact front matter format
    - docs/development.md — check exact front matter format
    - docs/installation.md — check exact front matter format
    - docs/mcp.md — check exact front matter format
    - docs/obsidian.md — check exact front matter format
    - docs/paradigms.md — check exact front matter format
    - docs/quickstart.md — check exact front matter format
    - docs/troubleshooting.md — check exact front matter format
    - docs/tutorial.md — check exact front matter format
    - .planning/phases/08-mkdocs-infrastructure/08-RESEARCH.md — full mkdocs.yml example in "Complete mkdocs.yml for Phase 8" section
  </read_first>

  <action>
    **Step 1 — Create mkdocs.yml at project root:**

    Write the following content exactly to `mkdocs.yml`:
    ```yaml
    site_name: ZettelControl
    site_description: CLI utility and agentic note-taking ecosystem for knowledge graph management.
    site_url: https://thatdevstudio.github.io/ztlctl/
    repo_url: https://github.com/ThatDevStudio/ztlctl
    repo_name: ThatDevStudio/ztlctl

    docs_dir: docs

    theme:
      name: shadcn
      show_title: true
      show_stargazers: true
      show_datetime: false
      pygments_style:
        light: shadcn-light
        dark: github-dark

    exclude_docs: |
      plans/

    nav:
      - Home: index.md
      - Installation: installation.md
      - Quick Start: quickstart.md
      - Tutorial: tutorial.md
      - Core Concepts: concepts.md
      - Knowledge Paradigms: paradigms.md
      - Obsidian Starter Kit: obsidian.md
      - Command Reference: commands.md
      - Configuration: configuration.md
      - MCP Server: mcp.md
      - Agentic Workflows: agentic-workflows.md
      - Troubleshooting: troubleshooting.md
      - Development: development.md

    plugins:
      - search
      - redirects:
          redirect_maps: {}

    markdown_extensions:
      - admonition
      - attr_list
      - def_list
      - fenced_code
      - footnotes
      - tables
      - toc:
          permalink: true

    copyright: >-
      MIT License. Distributed under the
      <a href="https://github.com/ThatDevStudio/ztlctl/blob/develop/LICENSE">MIT License</a>.
    ```

    Key notes for this config:
    - `exclude_docs: |` uses block scalar syntax (the pipe `|`) — required for gitignore-pattern syntax
    - `plugins:` lists `- search` first — without it, search is silently dropped when `plugins:` is defined
    - `redirect_maps: {}` is empty — no URL changes occur in Phase 8 (all 13 files stay at docs/*.md)
    - The `nav:` lists exactly 13 pages — all files that remain after Plan 01 deletes the 3 internal artifacts

    **Step 2 — Delete docs/_config.yml:**
    ```
    git rm docs/_config.yml
    ```

    **Step 3 — Strip nav_order: from all 13 public docs files:**
    For each of these files, remove the `nav_order: N` line from the YAML front matter block (lines between the `---` delimiters). Keep the `title:` line. Do not alter any content below the closing `---`.

    Files to update (13 total):
    - docs/index.md — remove `nav_order: 1` (keep `title: Home`)
    - docs/installation.md — remove `nav_order: 2` (keep `title: Installation`)
    - docs/quickstart.md — remove `nav_order: 3` (keep `title: Quick Start`)
    - docs/tutorial.md — remove `nav_order: 4` (keep `title: Tutorial`)
    - docs/concepts.md — remove `nav_order: 5` (keep `title: Core Concepts`)
    - docs/commands.md — remove `nav_order: 6` (keep `title: Command Reference`)
    - docs/configuration.md — remove `nav_order: 7` (keep `title: Configuration`)
    - docs/agentic-workflows.md — remove `nav_order: 8` (keep `title: Agentic Workflows`)
    - docs/obsidian.md — remove `nav_order: 8` (keep `title: Obsidian Starter Kit`)
    - docs/paradigms.md — remove `nav_order: 9` (keep `title: Knowledge Paradigms`)
    - docs/mcp.md — remove `nav_order: 10` (keep `title: MCP Server`)
    - docs/development.md — remove `nav_order: 11` (keep `title: Development`)
    - docs/troubleshooting.md — remove `nav_order: 12` (keep `title: Troubleshooting`)

    After editing each file, the front matter should look like:
    ```yaml
    ---
    title: Page Title
    ---
    ```
    (Two lines: title field and closing delimiter — no nav_order line.)

    **Step 4 — Run build verification:**
    ```
    uv run mkdocs build --strict 2>&1
    ```
    The build must exit 0 with no warnings. If warnings appear, diagnose and fix before committing.

    Common warning fixes:
    - "Doc file 'X' is not included in the nav" → add the missing file to nav: in mkdocs.yml
    - "Config value 'plugins': The 'redirects' plugin is not installed" → run `uv add --group dev mkdocs-redirects` (Task 1 should have handled this)
    - "exclude_docs pattern syntax error" → ensure the `|` block scalar is present after `exclude_docs:`
  </action>

  <verify>
    <automated>uv run mkdocs build --strict 2>&1 && test -f mkdocs.yml && test ! -f docs/_config.yml && grep -c "nav_order" docs/index.md docs/installation.md docs/commands.md 2>/dev/null | grep -v ":0" | wc -l</automated>
  </verify>

  <acceptance_criteria>
    - `uv run mkdocs build --strict` exits 0 (zero warnings, zero errors)
    - `test -f mkdocs.yml` exits 0
    - `test ! -f docs/_config.yml` exits 0
    - `grep "nav_order" docs/index.md docs/installation.md docs/commands.md docs/concepts.md docs/configuration.md docs/development.md docs/installation.md docs/mcp.md docs/obsidian.md docs/paradigms.md docs/quickstart.md docs/troubleshooting.md docs/tutorial.md docs/agentic-workflows.md` returns no matches
    - `grep "name: shadcn" mkdocs.yml` returns a match
    - `grep "exclude_docs" mkdocs.yml` returns a match
    - `grep "plans/" mkdocs.yml` returns a match
    - `test ! -d site/plans` exits 0 (plans/ not in built site)
    - `ls site/ | grep -c "plans"` returns 0
  </acceptance_criteria>

  <done>mkdocs.yml created, docs/_config.yml deleted, nav_order stripped from all 13 docs, `mkdocs build --strict` exits 0</done>
</task>

</tasks>

<verification>
After both tasks complete:
- `uv run mkdocs build --strict 2>&1` — must exit 0 with no output after "INFO" lines
- `test ! -f docs/_config.yml` — Jekyll config gone
- `grep -r "nav_order" docs/*.md` — returns no matches
- `test ! -d site/plans` — plans directory not present in built site output
- `uv run pytest` — existing test suite still green (no Python source touched)
</verification>

<success_criteria>
`mkdocs build --strict` passes with zero warnings. mkdocs.yml exists at project root with `theme: name: shadcn`, `exclude_docs: plans/`, and all 13 public pages in `nav:`. docs/_config.yml is deleted. All 13 docs/*.md files have no `nav_order:` in their front matter.
</success_criteria>

<output>
After completion, create `.planning/phases/08-mkdocs-infrastructure/08-02-SUMMARY.md`
</output>
