# mkdocs-authoring

> Guidelines for writing docs content — mermaid diagrams, formatting, dark mode compatibility

- Author: Andrew Holder
- Repository: drewswiredin/vincent-chappie
- Version: 20260209202943
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-10
- Source: https://github.com/drewswiredin/vincent-chappie
- Web: https://mule.run/skillshub/@@drewswiredin/vincent-chappie~mkdocs-authoring:20260209202943

---

---
name: mkdocs-authoring
description: Guidelines for writing docs content — mermaid diagrams, formatting, dark mode compatibility
domain: Documentation
scope: internal
user-invocable: false
allowed-tools: Read, Write, Edit, Grep, Glob
---
# MkDocs Authoring

Load this skill when creating or editing documentation content.

## Mermaid Diagrams

Use fenced code blocks with `mermaid` language identifier:

````
```mermaid
flowchart LR
    A[Step 1] --> B[Step 2]
```
````

### No Hardcoded Colors

Never use `style` directives with `fill:` or `stroke:` in mermaid diagrams. mkdocs-material auto-switches mermaid between light and dark themes — hardcoded light colors become unreadable in dark mode.

```
# BAD — breaks dark mode
style MyNode fill:#e8f5e9,stroke:#4caf50

# GOOD — let the theme handle it
(no style directives)
```

If you need to visually distinguish nodes, use mermaid's built-in class system or subgraphs for grouping.

### Subgraph Labels

Keep subgraph labels short — long labels overlap their first child node in rendered output. Move details to surrounding prose or node text.

```
# BAD — label overlaps child nodes
subgraph Orchestrator["Orchestrator (Claude Code)"]
subgraph P1["Phase 1: Foundation (First sessions)"]

# GOOD — short labels, details elsewhere
subgraph Orchestrator["Orchestrator"]
subgraph P1["Phase 1: Foundation"]
```

## Gotchas

- Mermaid diagrams only render via `mkdocs serve`, not when opening built HTML as static files
- Always validate with `mkdocs build --strict` after editing docs