- Home
- Documentation Generators
- MkDocs
MkDocs
What it is
MkDocs is free software that builds static project-documentation sites from Markdown files and a YAML configuration. Its command-line tools create projects, run a local server, build output, retrieve dependencies, and deploy to GitHub Pages. The development server previews pages locally and reloads after edits. Generated sites are static HTML and include search that can link directly to matching sections. Built-in mkdocs and readthedocs themes are included, with support for third-party and custom themes, plugins, Markdown extensions, and configuration changes. MkDocs uses Python-Markdown and requires a recent Python version plus pip. Sites can be hosted on GitHub Pages, Amazon S3, or another static-file provider. The built-in theme supports locales including English, German, Spanish, French, Japanese, and Chinese. Deployment guidance covers GitHub Pages and Read the Docs. MkDocs runs on Linux, macOS, Windows, and self-hosted setups, and is distributed under the BSD license. Third-party themes and plugins execute their authors' code without sandboxing.
For and against
For
- Free BSD-licensed static site generator
- Live preview reloads after changes
- Built-in search links to page sections
- Supports custom and third-party themes
- Hosts on GitHub Pages or Amazon S3
Against
- Requires a recent Python version and pip
- Plugins execute unsandboxed author code
- Themes also execute unsandboxed code
- Documentation is written in Markdown
The verdict
MkDocs offers a direct Markdown-to-static-HTML workflow with previews, search, and flexible hosting. Its main cautions are the Python setup and the lack of sandboxing for third-party themes and plugins.
Who it suits
MkDocs suits people building project documentation from Markdown who can install Python and pip. It fits teams wanting static hosting, theme customization, and command-line deployment.
On the record
- Audience
- MkDocs is intended for people building project documentation sites from Markdown files.mkdocs.org · read 1 Oct 2026
- CLI
- The command-line interface provides build, get-deps, gh-deploy, new, and serve commands.mkdocs.org · read 30 Sep 2026
- Custom domain
- Yesmkdocs.org · read 20 Sep 2026
- Customization
- Users can customize themes, install plugins, enable Markdown extensions, and configure many options.mkdocs.org · read 1 Oct 2026
- Deployment
- MkDocs documents deployment to GitHub Pages and Read the Docs and states that any static-file hosting provider can be used.mkdocs.org · read 30 Sep 2026
- Deployment command
- The command-line interface includes gh-deploy for deploying documentation to GitHub Pages.mkdocs.org · read 1 Oct 2026
- Hosting
- Generated sites can be hosted on GitHub Pages, Amazon S3, or other hosting services.mkdocs.org · read 1 Oct 2026
- Installation
- MkDocs is installed with the Python package manager using pip install mkdocs.mkdocs.org · read 1 Oct 2026
- Integrations
- MkDocs documentation can be deployed to GitHub Pages and hosted on Amazon S3.mkdocs.org · read 1 Oct 2026
- License
- MkDocs is distributed under the BSD license, which permits redistribution and use in source and binary forms subject to its conditions.mkdocs.org · read 1 Oct 2026
- Live preview
- The built-in development server previews documentation and auto-reloads when files change.mkdocs.org · read 1 Oct 2026
- Localization
- The built-in mkdocs theme supports multiple locales, including English, German, Spanish, French, Japanese, and Chinese.mkdocs.org · read 30 Sep 2026
- Markdown engine
- MkDocs uses Python-Markdown to render Markdown and supports Markdown extensions.mkdocs.org · read 30 Sep 2026
- Output
- MkDocs builds static HTML files that can be hosted on GitHub Pages, Amazon S3, or any other static-file host.mkdocs.org · read 30 Sep 2026
- Plugin ecosystem
- Third-party plugins are installed as Python packages and can be listed in the MkDocs Catalog.mkdocs.org · read 1 Oct 2026
- Plugin security
- MkDocs warns that plugins execute their authors' Python code and provides no sandboxing.mkdocs.org · read 1 Oct 2026
- Purpose
- MkDocs is a static site generator geared toward building project documentation from Markdown and a single YAML configuration file.mkdocs.org · read 1 Oct 2026
- Requirements
- MkDocs requires a recent version of Python and pip.mkdocs.org · read 1 Oct 2026
