MkDocs Material Template

A MkDocs Material Template repository. It enables a useful set of extensions and plugins by default, and contains a Makefile that uses Docker to serve the documentation locally, and a Github workflow to publish the documentation on Github Pages by default.

• Getting Started
• Material for MkDocs documentation

This template is intended both for those that include the documentation in their main repository, and those that use a separate repository for the documentation.

Quick Start

To build the pages and see edits live using Docker:

cd docs/
make

Or using Python 3, creating and activating a virtual environment:

cd docs/

python3 -m venv .venv
source .venv/bin/activate

pip install -r requirements.txt
mkdocs serve

deactivate

Or using UV, creating and activating a virtual environment:

cd docs/

uv venv

uv pip install -r requirements.txt
uv run mkdocs serve

Navigate to localhost:8000 to see the documentation. The local documentation is automatically reloaded when changes occur. Changes pushed to the main branch are automatically deployed to Github Pages.

Updating Dependencies

Install the pip-check-updates tool in a virtual environment (e.g., using pip install pip-check-updates or uv pip install pip-check-updates). Usage:

cd docs/
pcu requirements.txt

And update the dependencies to their latest versions using:

cd docs/
pcu -u requirements.txt

Note

Install the updated dependencies using:

pip install -r requirements.txt

Or, when using UV:

uv pip install -r requirements.txt

License

To the extent possible under law, Daniel A. A. Pelsmaeker has waived all copyright and related or neighboring rights to the MkDocs Material Template repository. Feel free to use this as you see fit, no attribution required.