Why MkDocs Snippets Silently Ate My Content (and How to Fix It)

By Joe  ·  April 7, 2026  ·  Tutorial  ·  ~6 min read

Also published at info.manitec.pw/blog/mkdocs-snippets

Here’s a fun way to waste an afternoon: build an automated system that generates markdown files in CI, include them in your docs with pymdownx.snippets, deploy successfully, and then discover that every single page is completely blank where your content should be.

No errors. No warnings. Just… nothing.

This happened to me while building the Manitec Dashboard — a MkDocs site that auto-pulls GitHub Issues and renders them as live task lists. The CI pipeline ran fine. The deploy succeeded. The pages were empty.

Here’s exactly why it happens and how to fix it in two lines.

What is pymdownx.snippets?

The pymdownx.snippets extension lets you include the contents of one file inside another using a special syntax:

--8<-- "path/to/file.md"

It’s useful for auto-generated content, reusable blocks shared across pages, and CI-generated markdown injected into docs at build time. When it works, it’s magic. When it doesn’t, it fails silently — which makes debugging it particularly painful.

The Problem: Path Resolution

Here’s the thing nobody tells you upfront.

pymdownx.snippets resolves include paths relative to the docs/ directory by default. Not the repo root. Not where mkdocs.yml lives. The docs/ directory.

So if your generated files live at meta/tasks/tasks-hexbot.md in the repo root, snippets looks for that file at docs/meta/tasks/tasks-hexbot.md — which doesn’t exist. Instead of throwing an error, it silently produces nothing. Your page renders empty and MkDocs doesn’t say a word about it.

The Fix: base_path

The pymdownx.snippets extension accepts a base_path option that tells it where to look for included files. You can pass multiple paths and it searches them in order.

In your mkdocs.yml:

markdown_extensions:
  - pymdownx.snippets:
      base_path:
        - .       # repo root
        - docs    # docs directory (default behavior preserved)

That’s it. Two lines. Adding . to base_path means snippets can now find files anywhere in your repository, not just inside docs/.

Full Working Setup

1. Run your generator before the deploy in CI:

- run: python meta/generate_fragments.py   # BEFORE deploy
- run: mkdocs gh-deploy --force

2. Handle API failures gracefully in your generator:

if resp.status_code == 404:
    print(f"INFO: not found for '{slug}' — writing empty snippet.")
    return []
if resp.status_code == 403:
    print(f"INFO: 403 for '{slug}' — writing empty snippet.")
    return []

3. Add base_path to mkdocs.yml:

- pymdownx.snippets:
    base_path:
      - .
      - docs

Quick Reference

TL;DR

If your --8<-- includes are producing blank output with no errors:

• Add base_path: [., docs] to your snippets config
• Make sure your generator runs before mkdocs gh-deploy in CI
• Add graceful error handling so API failures don’t nuke your deploy

The fix is two lines. The diagnosis is the hard part.

Built by Joe — Manitec.pw

Back to Blog | Home