How to Build a Documentation Site with MkDocs

On this page

1. Create a separate Python environment #

Start in an empty working directory. Use a virtual environment so the documentation packages don't mix with unrelated Python projects. On Windows, run:

py -m venv .venv
.venv\Scripts\python -m pip install mkdocs==1.6.1

On macOS or Linux, use:

python3 -m venv .venv
.venv/bin/python -m pip install mkdocs==1.6.1

Version 1.6.1 is the latest upstream release shown in the official release record on October 9, 2026. The installation guide explains pip installation and checking the installed version. Keep the Python environment's executable in the following commands, so the command uses the package you just installed.

On Windows, check:

.venv\Scripts\python -m mkdocs --version

You should see MkDocs's version information. The macOS/Linux equivalent replaces the executable with .venv/bin/python. If installation fails, resolve that error before creating the site.

2. Build a documentation site with MkDocs in a new project #

From the same directory, run:

.venv\Scripts\python -m mkdocs new release-handbook

Use the Unix environment executable on macOS/Linux. Open the new release-handbook folder in your editor. You should find mkdocs.yml and docs/index.md, following the official project layout.

Keep source and generated output separate. The docs folder will contain the pages you edit. The build will later create a site folder for deployment. Files in that output folder are regenerated; they aren't the best place to make permanent corrections.

For editing options, compare Markdown editors or code editors. A code editor is convenient here because you'll edit both Markdown and YAML.

3. Write two original Markdown pages #

Replace docs/index.md with:

# Release Handbook

This practice handbook describes an invented website release.

## Start here

Read the [release checklist](release-checklist.md) before publishing.

## Owner

The release editor checks the approved files and records the release date.

Create docs/release-checklist.md:

# Release Checklist

## Before release

1. Review the homepage wording.
2. Check the navigation links.
3. Confirm the approved output folder.

## After release

1. Open the public homepage.
2. Open one nested page.
3. Record the release date in the team log.

The homepage links to the Markdown source filename. MkDocs resolves internal page links while building the site, as described in its writing guide. Keep link spelling and filename case identical so the same project works across operating systems.

4. Set the site name and navigation #

Replace mkdocs.yml with:

site_name: Release Handbook
nav:
  - Home: index.md
  - Release checklist: release-checklist.md

Use spaces for indentation. nav entries are relative to the documentation directory, so index.md is correct here; docs/index.md would add an extra directory segment. Save the file.

The configuration reference documents navigation and directory settings. Two pages make it easy to spot an incorrect path before the project grows. If a page isn't listed in your explicit navigation, decide whether it belongs there before treating the menu as complete.

5. Preview the documentation site locally #

From the directory containing both .venv and release-handbook, run:

.venv\Scripts\python -m mkdocs serve -f release-handbook/mkdocs.yml

Open the local address printed by the command, normally http://127.0.0.1:8000/. You should see the Release Handbook site title and the two navigation entries. Open Release checklist, then follow Home to return.

Edit a sentence in docs/index.md and save. The documented development server rebuilds the site and refreshes the browser. If it reports a build error, inspect the named file and line before changing the theme or adding plugins.

This preview server is for development. Keep it local and use a proper static host for the finished website. Stop it with Ctrl+C when you're ready for the build step.

6. Build and inspect the static output #

Run:

.venv\Scripts\python -m mkdocs build -f release-handbook/mkdocs.yml --strict

The --strict option makes warnings fail the build, helping you catch mistakes before deployment. Look for a successful result and a new release-handbook/site directory. It should contain HTML pages and the theme's assets.

Deploy the contents of site, following your host's build/output instructions. Don't upload only docs, because browsers need the generated site. GitHub Pages, Cloudflare Pages and Netlify are possible destinations, with their own deployment rules.

After hosting, check the homepage, the checklist page, the link between them and Search. A local preview doesn't verify the public site's address or base-path settings. Add the final site_url in configuration when you know the real address.

Known problems and practical fixes #

An October 2025 MkDocs issue reported rebuild failure when configuration was piped through standard input with serve -f -. Use a real mkdocs.yml file and pass its path, as this example does. The server can then reread the configuration after an edit.

A June 2025 issue reported a Python HTML-parser error on a page containing raw PDF-like angle-bracket text. Put literal syntax examples in backticks or fenced code blocks instead of leaving them as possible HTML. If the error remains, reduce the page to the failing example and check the exact Python and package versions in your environment.

Troubleshooting table #

Variations for a larger handbook #

Group pages under a section

Add a directory such as docs/releases and point navigation entries at releases/checklist.md. Group related task pages under one navigation heading. Keep the menu task-oriented so readers can locate what they need without knowing your team's internal department names.

Change the built-in theme

The official tutorial demonstrates theme: readthedocs as a built-in alternative. Review the long checklist, code blocks and search after a theme change. A third-party theme or plugin adds another dependency; record its version and verify compatibility before relying on it.

Track source in Git

Commit mkdocs.yml, docs and dependency information. Ignore the generated site directory unless your deployment workflow explicitly requires committed output. A Git GUI client can help writers inspect changes before a commit. Keep the build instructions in the repository README.

Completion checklist #

• MkDocs runs from the intended virtual environment.
• The two Markdown files contain only public practice material.
• The YAML navigation names the correct files.
• Both pages and their links work in local preview.
• A strict build completes without warnings.
• Deployment uses generated output rather than raw Markdown.
• Public navigation and search are checked after hosting.

Next steps #

Compare Docusaurus if released documentation versions or React examples become a requirement. VitePress is another option for Vue-oriented projects. Keep this first handbook small enough that a new editor can understand its source and build steps in one sitting.