3.1 MkDocs & Material¶

MkDocs is a fast, simple static site generator for Markdown. Paired with Material for MkDocs, the standard theme produces clean, professional websites with responsive design, built-in search, dark mode, and syntax highlighting out of the box.

This site runs on MkDocs Material. If you like what you see here, you'll have it running in under an hour.

MkDocs vs Material

MkDocs is the build engine; Material is the theme. In practice, nearly everyone installs them together and treats them as a single tool. Installing Material also installs MkDocs, so mamba/conda/pip install mkdocs-material is all you need.

What is it good for?¶

MkDocs works best for documentation and project websites where content is organized into pages and you want a polished look with minimal effort. See the tool comparison table for when to use MkDocs versus JupyterBook or Jekyll.

It's less suited to long-form books with heavy cross-referencing (use JupyterBook/MyST) or highly customized personal websites (use Jekyll).

Getting started¶

The official documentation covers everything. Here's the core workflow:

1. Install¶

pip install mkdocs-material

2. Create a new project¶

mkdocs new my-project
cd my-project

This creates a minimal project with a mkdocs.yml configuration file and a docs/ folder containing a single index.md.

3. Enable the Material theme¶

Edit mkdocs.yml:

site_name: My Project
theme:
  name: material

4. Preview locally¶

mkdocs serve

Open http://127.0.0.1:8000 in your browser. The site rebuilds automatically as you edit files.

5. Deploy¶

mkdocs gh-deploy

This builds the site and pushes it to the gh-pages branch of your GitHub repository. Enable Pages in the repository settings and your site is live. Alternatively, use a GitHub Actions workflow for automatic deployment on every push.

The plugin ecosystem¶

One of MkDocs Material's strengths is its plugin ecosystem. A few plugins we find particularly useful:

Plugin	What it does
`mkdocs-jupyter`	Render Jupyter Notebooks as pages (no need to export first)
`mkdocstrings`	Auto-generate API reference pages from Python docstrings
`mkdocs-bibtex`	BibTeX citation support
`mkdocs-git-revision-date-localized`	Show "last updated" dates on pages from git history
Blog plugin	Full blog support with tags and pagination — built into Material (no extra install)

Plugins are declared in mkdocs.yml under the plugins: key and installed via pip.

The `mkdocs.yml` file¶

All configuration lives in a single mkdocs.yml file at the root of the project. Beyond the basics (site name, theme, navigation), it controls extensions, plugins, and appearance. The Material setup documentation is the best reference for what is available — and there is a lot.