kata-docs-serve

---
name: kata-docs-serve
description: "Local Documentation Server (MkDocs). Local Markdown documentation server for the docs/ directory using MkDocs"
---

# Kata: Local Documentation Server (MkDocs)

> **Prefix:** `kata-` | **Type:** Repeatable Skill | **Scope:** Local Markdown documentation server for the `docs/` directory using MkDocs

## Workflow

```
Progress:
- [ ] 1. Read directives
- [ ] 2. Verify MkDocs installation
- [ ] 3. Resolve docs_dir
- [ ] 4. Check or generate mkdocs.yml
- [ ] 5. Start server
```

### Step 1: Read Directives

1. If `docs_dir` is provided as input, use it directly — skip to Step 2.
2. Otherwise, read `.ahrena/.directives` to obtain:
   - `paths.domain` — domain model documents (e.g., `docs/domain`)
   - `paths.oas` — API specification and documents (e.g., `docs/oas`)
   - `paths.events` — events documents (e.g., `docs/events`)
3. Derive `docs_dir` as the common parent directory of the three paths (e.g., `docs/` when all paths are `docs/{section}`)
4. If paths diverge and no common parent exists, use `docs/` as the default and warn the user

### Step 2: Verify MkDocs Installation

1. Run `mkdocs --version`
2. If MkDocs is not found:
   - Run `pip install mkdocs mkdocs-material`
   - If pip is unavailable, inform the user and stop with a clear message: "Install Python and pip first, then run `pip install mkdocs mkdocs-material`"
3. Check whether the Material theme is available: `python -c "import material"` (optional; used in Step 4)

### Step 3: Resolve docs_dir

1. Confirm `docs_dir` is a directory that exists at the project root
2. If it does not exist, create it: `mkdir -p {docs_dir}`
3. If `docs_dir` is empty, create a minimal `index.md`:
   ```markdown
   # Guardia Platform Docs

   Documentation generated by the Ahrena framework.
   Navigate using the sidebar.
   ```

### Step 4: Check or Generate mkdocs.yml

1. Check whether `mkdocs.yml` exists at the project root
2. **If it exists:** use it as-is — do not overwrite; proceed to Step 5
3. **If it does not exist:** generate a minimal `mkdocs.yml`:

```yaml
site_name: Guardia Platform Docs
docs_dir: {docs_dir}
theme:
  name: material   # falls back to 'mkdocs' if mkdocs-material is not installed
```

   - If Material theme is not installed (Step 2 check failed), use `name: mkdocs` instead
   - Write the file to the project root as `mkdocs.yml`
   - Inform the user: "`mkdocs.yml` generated at project root. Edit it to customize navigation, theme, or site name."

### Step 5: Start Server

1. Run `mkdocs serve --dev-addr 127.0.0.1:{port}` (default port: `8000`)
2. Report to the user:
   - URL: `http://127.0.0.1:8000` (or the configured port)
   - Docs directory being served: `{docs_dir}/`
   - Hot-reload: active (changes to `.md` files refresh automatically)
3. The server runs in the foreground; the user stops it with `Ctrl+C`

## Deliverable

A running MkDocs server at `http://127.0.0.1:8000` serving all `.md` files under `docs/` as a navigable site with auto-reload on changes.

## Notes

- MkDocs auto-discovers all `.md` files under `docs_dir` when no `nav` key is defined in `mkdocs.yml`. To customize navigation order, add a `nav:` section manually.
- The Material theme (`mkdocs-material`) provides search, dark mode, and better navigation. Install with `pip install mkdocs-material`.
- The server is for local development only — do not expose it publicly without authentication.