MkDocs

Last reviewed Aug 26, 2026 · 814 words

MkDocs is not a wiki and doesn't pretend to be one. There is no server, no database, no login, no edit button. It is a build step that turns a folder of Markdown plus one mkdocs.yml into a static site in well under a second for a homelab-sized set of pages. You self-host the output, not the tool. That is exactly why it is the right home for homelab documentation: the source lives in Git next to your Compose files, the build runs wherever your CI runs, and the result is a folder any web server can serve with a zero-line attack surface.

Git is the database

The thing MkDocs replaces in a self-hosted stack is the "notes about the servers" page that lives in somebody's head, or in a Nextcloud file nobody can find. Because the source is Markdown in a repository, your documentation gets the same history, review, and backup as the config it describes. When you change a port in docker-compose.yml, the docs change in the same commit. A Forgejo or Gitea repo, a branch, a pull request that updates both: that workflow is the actual feature, and it's one no wiki with a database gives you.

Nothing to a site in 4 commands

pip install mkdocs-material
mkdocs new homelab-docs && cd homelab-docs
mkdocs serve      # live reload at http://127.0.0.1:8000
mkdocs build      # writes ./site

Installing mkdocs-material pulls in MkDocs itself. The generated mkdocs.yml is 1 line; a real one is about 15:

site_name: Homelab
theme:
  name: material
  features:
    - navigation.tabs
    - content.code.copy
nav:
  - Home: index.md
  - Network: network.md
  - Services: services.md
  - Backups: backups.md
plugins:
  - search

Every entry in nav is a Markdown file under docs/. Leave nav out and MkDocs builds it from the directory structure, which is fine until you care about ordering. The built-in search plugin gives you client-side full-text search with no server component, which for a few hundred pages is instant.

Material is the reason people pick it

Plain MkDocs with its default theme is fine. MkDocs with the Material theme is why the project has 22,376 stars and why half the technical documentation you've read this year looks the same. Material adds tabs, admonitions, code annotations, a dark mode toggle, a decent mobile layout, and versioning via a companion tool called mike. It is maintained by one person, funded by a sponsorware model where new features ship to sponsors first and to everyone a while later; the free release is complete enough that I've never needed the sponsor tier. If you're choosing between MkDocs and Docusaurus, the honest split is: Material for documentation written by people who don't want to touch React, Docusaurus for a product site where someone will.

Serve the output with 4 lines of Caddy

The site/ folder is plain HTML. On the box that serves it:

docs.home.example.com {
    root * /srv/docs/site
    file_server
}

The rebuild belongs in CI. A Forgejo Actions or Gitea Actions job that runs pip install mkdocs-material && mkdocs build and then rsync copies site/ to the web host is about 12 lines of YAML and finishes in under 30 seconds. If your docs are public and you'd rather not host at all, mkdocs gh-deploy pushes the built site to a gh-pages branch. The point is that nothing in the serving path runs Python, which is what makes it the one service in my stack that has never needed patching.

What it is not, and when to pick BookStack instead

MkDocs is documentation-only. No comments, no page permissions, no web editor, no "anyone in the house can fix a typo". If the people writing the docs aren't comfortable with Git, or you need per-page access control, that's a BookStack or Wiki.js job, and both are good. The same goes for anything blog-shaped; MkDocs can be bent into it, but Hugo bends less. The catalogue lists "no collaborative editing" as a con, and it's right, but it's a con in the way a hammer lacks a screwdriver.

What I'd do

A docs/ folder in the same repository as the Compose files, MkDocs with Material, a CI job that rebuilds on every push to main, and Caddy serving the result on an internal hostname. For a household or a small team where everyone can use Git, I wouldn't consider a database-backed wiki at all; 128 MB of RAM during the build and 0 MB after is hard to argue with. Write the first three pages today: network layout, what runs where, how to restore backups. Those are the ones you'll need at 2 a.m.