Troubleshooting — tablez-docs¶

Common issues with the MkDocs documentation site build, local preview, and Cloudflare Pages deployment.

Table of Contents¶

Local Build Errors
Deployment Failures
Content Issues
Escalation

Local Build Errors¶

`mkdocs build` fails — missing plugin¶

Symptom: ModuleNotFoundError: No module named 'mkdocs_material' or similar.

Fix:

pip install mkdocs-material
# Or install all requirements at once
pip install -r requirements.txt

Mermaid diagrams not rendering¶

Symptom: Mermaid code blocks show as raw text in the built site.

Fix: 1. Ensure pymdownx.superfences with the mermaid custom fence is in mkdocs.yml 2. Check the theme supports JavaScript — material theme does 3. Ensure the mermaid JS CDN is reachable (blocked in some environments)

`mkdocs serve` shows warnings about broken internal links¶

Symptom: WARNING - Doc file 'page.md' contains a link to 'other.md' but that file does not exist.

Fix: Update the link to the correct path relative to docs/. MkDocs resolves links relative to the current file:

<!-- Wrong -->
[Architecture](../architecture.md)
<!-- Correct (relative to this file's location in docs/) -->
[Architecture](architecture.md)

Deployment Failures¶

Cloudflare Pages build fails¶

Symptom: Pages deployment fails in GitHub Actions.

Diagnose: Check the deployment job logs in GitHub Actions.

Common fixes:

Cause	Fix
Python version mismatch	Pin Python version in workflow: `python-version: '3.11'`
Missing `requirements.txt`	Add pip dependencies file to repo root
`mkdocs build` error	Run locally to reproduce: `mkdocs build --strict`
Cloudflare API token expired	Rotate `CLOUDFLARE_API_TOKEN` in repo secrets

404 on deployed pages¶

Symptom: Page exists locally but 404 on the deployed site.

Fix: 1. Check mkdocs.yml nav: section — page must be listed or it won't be built 2. Check the Cloudflare Pages deployment output — was the file included in site/? 3. Check for case sensitivity — Cloudflare Pages is case-sensitive; local macOS is not

Content Issues¶

Search not finding content¶

Symptom: Site search returns no results for a term that exists in a page.

Fix: Ensure the search plugin is enabled in mkdocs.yml:

plugins:
  - search

Rebuild the site — the search index is generated at build time.

Table of contents not generating¶

Symptom: No TOC sidebar for a page.

Fix: Ensure headings follow proper hierarchy (H2 → H3, not H1 → H3). The material theme generates TOC from H2/H3 headings by default.

Escalation¶

Issue	Escalate to
Cloudflare Pages account access	Stig-Johnny
Major docs restructure	Codi-E (coordinate nav changes across all repos)
Broken deployment pipeline	Codi-E