MkDocs

MkDocs is a static site generator for Python projects that builds project documentation from Markdown sources using YAML configuration.

Installation and Setup

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

Windows PowerShell 
PS> py -m pip install mkdocs
PS> mkdocs --version
Shell 
$ 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:

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

Add pages and structure them in mkdocs.yml:

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

Build the site for production:

Shell 
$ mkdocs build

Deploy to GitHub Pages:

Shell 
$ 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.