MkDocs

Installation and Setup

Install from the Python Package Index (PyPI) into a virtual environment:

• Windows
• Linux + macOS

PS> py -m pip install mkdocs
PS> mkdocs --version

$ python -m pip install mkdocs
$ mkdocs --version

Key Features

• Markdown based authoring with a mkdocs.yml that controls navigation, theme, and plugins.
• Fast live preview with mkdocs serve that rebuilds and reloads the browser on file changes.
• Pluggable themes and extensions with a built in search plugin and many community options.
• Publishing flow that outputs a static site/ directory suitable for any static host.
• First class support for GitHub Pages deployment with a single command.

Usage

Start a new project and preview locally:

$ mkdocs new docs
$ cd docs
$ mkdocs serve  # Sever at http://127.0.0.1:8000

Add pages and structure them in mkdocs.yml:

nav:
  - Home: index.md
  - API:
      - Overview: api/index.md
      - Client: api/client.md

Build the site for production:

$ mkdocs build

Deploy to GitHub Pages:

$ mkdocs gh-deploy

Customize the look and feel by choosing a theme in mkdocs.yml and adding extra CSS or JavaScript in the docs/ folder. Use plugins to extend features such as redirects, macros, sitemap generation, or Python docstring extraction.

Related Resources

Tutorial

Build Your Python Project Documentation With MkDocs

In this tutorial, you'll learn how to build professional documentation for a Python package using MkDocs and mkdocstrings. These tools allow you to generate nice-looking and modern documentation from Markdown files and, more importantly, from your code's docstrings.

basics projects tools

For additional information on related topics, take a look at the following resources:

• Building Python Project Documentation With MkDocs (Course)