MkDocs

MkDocs is the odd one out in this course, and that is exactly why it deserves a chapter of its own. The other three frameworks are JavaScript applications that happen to produce documentation: each carries a component model, a bundler, and a runtime that a reader’s browser may eventually download. MkDocs is a Python program that reads Markdown files and writes HTML files. There is no component system to learn, no bundler to configure, and no client-side framework in the output. A page that says what it needs to say arrives as an HTML file, a stylesheet, and possibly a small script for the search box.

That restraint is a design position rather than a gap. The argument behind MkDocs is that documentation belongs next to the code it describes, that publishing it should be a single command, and that the tool should be small enough to read from end to end. The practical consequence is that most of the interesting behaviour lives outside the core, in themes and plugins. The generator itself is deliberately thin, and learning it means learning where to look rather than memorising a large option surface.

This chapter builds that understanding in four movements. It starts with what MkDocs is and how a directory of Markdown files plus a single YAML configuration file becomes a website, including why that configuration file is where a documentation project’s real decisions are recorded. It then covers the first hour: installing the tool, creating a project, running the development server, understanding what the build produces, and getting that output onto a host. The third part takes up Material for MkDocs, the theme that most people meet first, with its feature flags, colour palette, admonitions, tabbed content, and code annotations. The last part covers the plugin system, both the plugins you install and the ones you write yourself when the built-in behaviour is not enough.

Two ideas carry through all of it. The first is that the file layout is the information architecture: with no explicit navigation tree, the directory structure becomes the sidebar, so moving a file is a design decision rather than a chore. The second is that configuration is data. The site name, the navigation, the theme options, and the plugin settings all live in one YAML file, which means the entire shape of the site can be reviewed in a pull request, reproduced exactly on another machine, and rolled back by reverting a commit.

Choosing this tool is also a statement about constraints, and it is worth being honest about both sides. If the team that maintains the documentation writes Python and would rather not add a Node toolchain to the build, MkDocs removes an entire category of work: no lockfile to keep current, no bundler configuration, no client-side framework to keep patched. The price is that the extension surface is Python plugins rather than framework components, so a page that needs genuinely interactive behaviour requires a custom plugin or an embedded script, and the richest out-of-the-box experience comes from a theme rather than from the generator itself.

By the end of the chapter you should be able to install MkDocs and a theme, create and serve a project, explain how navigation is derived from the file tree, configure a theme’s features and colours, add and write plugins, and produce a build you can publish to any static host. The pages that follow work through those capabilities in that order.

Chapters

Found an issue with this content?

Tell us what could be improved.