• October 9, 2025
• in dev, mkdocs, tips
• 1 min read

Serving MkDocs in Codespaces: a simple workaround

If you are using MkDocs inside GitHub Codespaces, you may notice that the usual:

mkdocs serve

does not rebuild your site when Markdown files change. The internal watcher seems broken in Codespaces, and no amount of --dirtyreload or watchdog tricks reliably triggers a rebuild.

Here’s a simple, working workaround I use:

---

Step 1 — Add a Makefile

Create a Makefile in the root of your repo: