MkDocs

1.6.1 · active · verified Sun Apr 05

MkDocs is a fast, simple, and downright gorgeous static site generator that's geared towards building project documentation with Markdown. It converts a directory of Markdown files and a YAML configuration into a static website. The current version is 1.6.1, and it maintains an active release cadence with several patch and minor releases per year to address bugs and introduce new features.

Warnings

breaking The `config.extra_javascript` option in `mkdocs.yml` changed behavior in version 1.5.0. It is no longer strictly a list of strings but can now contain mappings with keys like `type`, `async`, and `defer`. Plugins or themes directly manipulating this list must adapt.
Fix: Update plugin/theme code to expect either strings or dictionary objects in `config.extra_javascript`. When reading values, cast to `str(value)` or check `isinstance` for dictionary attributes. Refer to the official documentation for the new structure.
breaking In version 1.6.0, the `exclude_docs` configuration option no longer provides 'drafts' functionality during `mkdocs serve`. Files specified under `exclude_docs` are now *always* excluded. A new option, `draft_docs`, was introduced for files that should appear during `serve` but not `build`.
Fix: If you relied on `exclude_docs` to treat certain files as drafts (visible during `serve` but not `build`), you must migrate them to the new `draft_docs` configuration option. Files listed in `exclude_docs` will now be completely absent from the served site as well.
gotcha As of version 1.5.0, `mkdocs serve` no longer exits immediately after detecting re-build errors (e.g., in configuration or plugins). Instead, it freezes the server, waiting for the user to fix the issue. Initial build errors, however, still cause an exit.
Fix: When `mkdocs serve` appears unresponsive during development, check your console output for error messages. The server is likely paused, awaiting a fix to a detected problem in your documentation files or configuration. Correct the error, and the server should automatically resume.
gotcha The `site_url` configuration option is now effectively required for correct deployment, especially for features like sitemap generation and canonical URLs. Failing to set it, particularly when deploying to a subdirectory, can lead to broken links or incorrect metadata.
Fix: Always define `site_url` in your `mkdocs.yml`. Ensure it includes any subdirectories if your site is hosted at `https://example.com/foo/` rather than the root domain. Example: `site_url: https://example.com/foo/`.

Install

pip install mkdocs Install MkDocs
pip install mkdocs[i18n] Install with internationalization support

Imports

plugins
```
import mkdocs.plugins
```
Commonly imported by plugin developers to define event handlers.
config
```
from mkdocs import config
```
Used for programmatic access to MkDocs configuration, less common for typical users.

Quickstart

This quickstart demonstrates how to create a new MkDocs project and start its built-in development server. The `mkdocs new` command scaffolds a basic project structure with a `mkdocs.yml` configuration file and a `docs/` directory for your Markdown content. The `mkdocs serve` command then launches a local server with live-reloading for development.

import os

# Create a new MkDocs project
os.system("mkdocs new my-docs-project")

# Change into the project directory
os.chdir("my-docs-project")

# Start the development server (runs in the background for this example)
# In a real scenario, you'd run this from your terminal and visit http://127.0.0.1:8000
print("Run 'mkdocs serve' in your terminal in the 'my-docs-project' directory to preview your site.")
print("To open in browser automatically: 'mkdocs serve --open'")

view raw JSON →