Quick Start
This page takes you from an empty directory to a published documentation site. It assumes you can install a Python package and run commands in a terminal. No prior knowledge of MkDocs, of Python web frameworks, or of front-end tooling is needed.
MkDocs is an ordinary Python package, so the usual tools work:
python -m pip install mkdocs
For day-to-day use on your own machine, an isolated install is better, because it keeps MkDocs and its dependencies out of your project’s virtual environment:
pipx install mkdocs
pipx is a small tool that installs command-line applications into their own environments and exposes them on your PATH. The same result can be had with uv tool install mkdocs if you prefer uv. Whichever route you take, check that the command is available:
mkdocs --version
Because mkdocs.yml is committed to the repository and the site has to build the same way on every machine, it is worth adding the tool to a development requirements file so that a colleague or a CI job installs exactly the same version.
The new command scaffolds a project:
mkdocs new my-project
cd my-project
You now have exactly two things:
my-project/
├── docs/
│ └── index.md
└── mkdocs.yml
The generated docs/index.md contains a heading and a placeholder paragraph, and the generated mkdocs.yml is a complete, valid configuration with the defaults spelled out. Read it once: it is the smallest useful example of the configuration file, and every key in it is one you may want to change.
site_name: my-project
site_description: ''
site_author: ''
site_dir: site
nav:
- Home: index.md
The development server rebuilds and reloads the page when you save a file:
mkdocs serve
Open http://127.0.0.1:8000 in a browser and you are looking at your site. The server watches the content directory, so editing index.md and saving refreshes the tab. This is the loop you will spend most of your time in, and it is worth knowing the two options that shape it:
mkdocs serve --dev-addr 127.0.0.1:8001 # use a different port
mkdocs serve -a 0.0.0.0:8000 # listen on every interface
The second form is how you test the site from a phone or another machine on the same network, and it is also how you would run the containerised image. The first is the fix for the most common startup error, which is a port that is already in use. The default address is 127.0.0.1:8000, and it can also be changed once in the configuration file rather than on every command line.
Create a file in the docs directory and it becomes a page:
docs/
├── index.md
└── installation.md
Open the site and the new page is in the sidebar, because MkDocs builds the navigation from the file tree when the configuration does not say otherwise. The URL follows the file path: by default a page is served from a directory of its own, so docs/installation.md is available at /installation/. Setting use_directory_urls: false in the configuration produces flat .html paths instead, which is what you need if the site is served from somewhere that cannot resolve a directory to its index.html.
Once there are more than a handful of pages, write the navigation explicitly, as the generated configuration invites you to. You control both the grouping and the order, and a reader’s path through the documentation becomes a decision you can defend.
The production build writes static files to the output directory:
mkdocs build
The result is a directory of HTML, CSS, JavaScript, and images that any web server, CDN, or object store can serve. Nothing in it needs a Python process or a database. Two flags are worth building into your habits:
mkdocs build --strict # turn warnings into errors
mkdocs build --clean # remove the output directory before writing
--strict is the important one for continuous integration. By default MkDocs reports warnings about broken internal links and about pages that are not reachable from the navigation, but it still produces a site. With --strict those warnings fail the build, which means a broken link cannot be merged unnoticed. Adding that flag to the CI command is the single highest-value thing you can do to keep a documentation set honest.
The output in site/ is deployable by any means you already use to ship static files: copy it to a host, upload it as the release asset of a GitHub Pages branch, or let a CI job publish it to object storage and put a CDN in front.
For GitHub Pages, MkDocs has a built-in command:
mkdocs gh-deploy
It commits the built site to a gh-pages branch and pushes it. It is convenient for a small project and awkward for continuous integration, where you usually want the build to publish without a long-lived credential; there, building the site and uploading the directory as a workflow artifact or with a storage client is the more controllable arrangement.
If you would rather not install Python at all on the machine that builds the site, the Material theme publishes a container image that contains MkDocs and the theme together:
docker run --rm -v "$PWD:/docs" squidfunk/mkdocs-material build
The working directory is mounted at /docs, the build runs inside the image, and the result appears in your local site directory. The same image serves the development server when serve replaces build.
You now have a site you can write, preview, build, and publish. Two things usually come next. The first is a theme, because the built-in themes are deliberately plain: installing Material for MkDocs and naming it in the configuration turns the same project into a site with a real navigation, a search box, and a dark mode. The second is navigation and metadata, because a documentation set earns its keep through its structure rather than through its styling.
Between those, one habit is worth forming now: keep the content directory free of anything that is not a page, and let the configuration file carry every decision about the site. When a page needs to be hidden, moved, or reordered, there is exactly one place to look.
