# mkdocs-troubleshoot

> Diagnose and fix MkDocs build issues — broken mermaid diagrams, plugin errors, package 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-troubleshoot:20260209202943

---

---
name: mkdocs-troubleshoot
description: Diagnose and fix MkDocs build issues — broken mermaid diagrams, plugin errors, package compatibility
domain: Documentation
scope: internal
user-invocable: false
allowed-tools: Bash, Read, Edit, Grep, Glob, WebSearch
---
# MkDocs Troubleshooting

## Required Packages

```bash
pip install mkdocs mkdocs-material mkdocs-panzoom-plugin pymdown-extensions
```

Package name gotcha: the panzoom plugin is `mkdocs-panzoom-plugin` (not `mkdocs-panzoom`).

## Mermaid Diagrams

Mermaid requires this superfences config in `mkdocs.yml`:

```yaml
markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
```

### Diagrams Not Rendering

1. **Version mismatch**: `pymdown-extensions` must be >=10.x for `mkdocs-material` >=9.4. Upgrade both together.
2. **Verify in built HTML**: `grep -c 'class="mermaid"' site/<page>/index.html` — should match number of diagrams.
3. **Renders only via serve**: Mermaid needs JavaScript — `mkdocs build` output won't show diagrams when opened as static files. Must use `mkdocs serve`.

## Validation Commands

```bash
mkdocs build --strict          # Zero warnings = clean
bash scripts/validate-consistency.sh  # Docs ↔ nav sync
```

## Gotchas

- `mkdocs-material` and `pymdown-extensions` versions must be compatible — old pymdownx silently breaks mermaid fences
- Panzoom plugin registers as `panzoom` in mkdocs.yml, not `panzoom-plugin`
- `mkdocs build --strict` catches broken links and missing nav entries
- Dark mode issues with diagrams? Check for hardcoded `style` directives with `fill:`/`stroke:` colors — see `mkdocs-authoring` skill for the rule