Introduction to MkDocs

MkDocs is a static site generator built around one idea: project documentation should be written in Markdown, kept in the repository next to the code, and published by a command that anyone can run. It was designed for a single job — building a documentation site for a software project — and it does that job with a very small core. Installation is one package, a new site is one command away, and the generated output is plain HTML and CSS with no client-side framework in it.

The two pieces of a project

Every MkDocs project has exactly two parts. The first is a directory of Markdown files, conventionally named docs, which holds the content. The second is a YAML file called mkdocs.yml at the project root, which holds every decision about the site: its name and description, the theme, the navigation, the plugins, and the Markdown extensions to enable. Nothing else is required.

my-project/
├── docs/
│   ├── index.md
│   ├── installation.md
│   └── reference/
│       └── configuration.md
└── mkdocs.yml

The separation is deliberate, and it is why MkDocs projects stay easy to review. Content changes are diffs of prose; configuration changes are diffs of a small, structured file. A reviewer can see at a glance whether a pull request rewrote a paragraph or reorganised the whole navigation tree.

How a page is built

The pipeline is short. MkDocs reads each Markdown file with Python-Markdown, a parser that follows the original Markdown syntax and is extended rather than replaced. The parsed document is handed to a theme, which is a set of Jinja2 templates that wrap the content in a layout and supply the navigation, the header, and the footer. The result is written to the output directory as HTML.

Two details follow from that pipeline and explain most of the tool’s behaviour.

The first is that Markdown extensions are additive. MkDocs enables a small set of them by default — metadata parsing, a table of contents, tables, and fenced code blocks — and everything richer comes from extensions you list yourself. Admonitions, tabbed content, footnotes, and most syntax highlighting are all extension features. A document that uses an extension in a place where it is not enabled will not fail the build in an obvious way; it will render as plain text, which is one of the most common sources of confusion for newcomers.

The second is that themes are complete replacements. A theme owns the whole page, not just the styling of the content. That gives a theme enormous freedom — Material for MkDocs can afford to implement tabs, code copy buttons, and a search dialog because it controls the templates those features live in — but it also means a theme is not a stylesheet you can layer on top of MkDocs. If you switch themes, you inherit a different layout and a different set of features.

Navigation is where most first-time confusion happens, and the rule is short enough to state in one sentence. If mkdocs.yml contains a nav section, that section is the navigation, exactly as written and in the order written. If it does not, MkDocs walks the docs directory and builds the sidebar from the folder structure, sorting alphabetically and listing an index file first within each section.

That fallback is what makes the tool pleasant to start with: create docs/installation.md and the page appears in the sidebar without any configuration. It is also what makes the tool awkward to grow, because a long list of files sorted by name is not an information architecture you can defend to a reader. Most projects that pass a certain size write an explicit nav, and that single decision is usually the point at which MkDocs stops being a toy.

An explicit navigation looks like this, and note that the paths are relative to the docs directory:

site_name: My Project
nav:
  - Home: index.md
  - Getting started:
      - Installation: installation.md
      - Configuration: reference/configuration.md

The configuration file

mkdocs.yml is YAML, and its keys fall into a small number of groups. site_name, site_description, site_url, site_author, and site_dir describe the site itself; site_name is the only one that is required. theme selects and configures a theme. nav sets the navigation. plugins lists the plugins to enable. markdown_extensions lists the Markdown extensions to enable. extra holds arbitrary key-value data that templates can read, which is how a theme is usually given a logo, a repository URL, or a social list.

site_name: My Project
site_description: Documentation for My Project
site_url: https://example.com/docs/
site_dir: site

theme:
  name: material
  features:
    - navigation.sections
    - content.code.copy

plugins:
  - search

markdown_extensions:
  - admonition
  - toc:
      permalink: true
  - pymdownx.highlight
  - pymdownx.superfences

Note the two different shapes in that file. A setting with no options of its own is written as a plain string. A setting with options becomes a mapping, with the option names nested one level down. The same rule applies to plugins and to Markdown extensions, and getting it wrong is the most common reason a configuration file is rejected at startup.

A useful habit is to treat this file as the project’s front door. The settings that affect a reader’s experience — the site name, the navigation, the theme features, the search behaviour — all live in one place, which means a change to the shape of the documentation is a reviewable, revertible commit rather than a scattering of edits across templates. For organisations that publish several sites from one repository, the file also supports inheritance: a parent configuration can hold the shared settings and a child file can inherit from it and override only what differs.

When MkDocs is the right answer

MkDocs fits well when the documentation belongs to a Python project, when the people who write it are comfortable in a Python environment, and when the site needs to be a reference rather than an application. It is fast to set up, cheap to host, and it produces output that will still load in ten years because there is no framework version to keep in step with.

It fits less well when the documentation site is really a product — a marketing page, a blog with heavy custom components, an interactive playground — because those needs pull the project towards a component framework. It also fits less well when the organisation has already standardised on a JavaScript toolchain, because then MkDocs adds a second ecosystem rather than reusing the first.

The reason to understand the core before reaching for a theme is that everything else in this chapter hangs off it: the theme system assumes a template pipeline, the plugin system assumes a build with named events, and the quick start assumes you know which directory holds the content. Learn the shape of the core and the rest of the tool becomes configuration.

Found an issue with this content?

Tell us what could be improved.