CheatPress

MkDocs Docs from Markdown

Version 1.6 · source

MkDocs, Postcard, light preview Light · Postcard 102 × 152 mm · PDF MkDocs, Postcard, dark preview Dark · Postcard 102 × 152 mm · PDF MkDocs, Postcard, ink saver preview Ink saver · Postcard 102 × 152 mm · PDF
MkDocs, A5, light preview Light · A5 148 × 210 mm · PDF MkDocs, A5, dark preview Dark · A5 148 × 210 mm · PDF MkDocs, A5, ink saver preview Ink saver · A5 148 × 210 mm · PDF
MkDocs, A4, light preview Light · A4 210 × 297 mm · PDF MkDocs, A4, dark preview Dark · A4 210 × 297 mm · PDF MkDocs, A4, ink saver preview Ink saver · A4 210 × 297 mm · PDF
MkDocs, A4 landscape, light preview Light · A4 landscape 297 × 210 mm · PDF MkDocs, A4 landscape, dark preview Dark · A4 landscape 297 × 210 mm · PDF MkDocs, A4 landscape, ink saver preview Ink saver · A4 landscape 297 × 210 mm · PDF
MkDocs, A3, light preview Light · A3 297 × 420 mm · PDF MkDocs, A3, dark preview Dark · A3 297 × 420 mm · PDF MkDocs, A3, ink saver preview Ink saver · A3 297 × 420 mm · PDF
MkDocs, A3 landscape, light preview Light · A3 landscape 420 × 297 mm · PDF MkDocs, A3 landscape, dark preview Dark · A3 landscape 420 × 297 mm · PDF MkDocs, A3 landscape, ink saver preview Ink saver · A3 landscape 420 × 297 mm · PDF
MkDocs, Letter, light preview Light · Letter 8.5 × 11 in · PDF MkDocs, Letter, dark preview Dark · Letter 8.5 × 11 in · PDF MkDocs, Letter, ink saver preview Ink saver · Letter 8.5 × 11 in · PDF
MkDocs, Tabloid, light preview Light · Tabloid 11 × 17 in · PDF MkDocs, Tabloid, dark preview Dark · Tabloid 11 × 17 in · PDF MkDocs, Tabloid, ink saver preview Ink saver · Tabloid 11 × 17 in · PDF

Start here

pip install mkdocs
Install MkDocs
mkdocs new <dir>
Create a project
mkdocs serve
Live preview
mkdocs build
Build the site
mkdocs build --strict
Fail on warnings
mkdocs gh-deploy
Publish to GitHub Pages
mkdocs get-deps
List needed packages
mkdocs --version
Show version

Concepts

  1. docs/*.md your pages
  2. Config + theme nav, plugins
  3. site/ static HTML
  4. gh-pages hosted site

Project

mkdocs new <dir>
Create mkdocs.yml and docs/index.md
mkdocs new .
Scaffold in the current folder
pip install mkdocs
Install MkDocs
pip install mkdocs-material
Install the Material theme
mkdocs --version
Show installed version
mkdocs get-deps
Print packages the config needs
pip install $(mkdocs get-deps)
Install those packages

Preview

mkdocs serve
Serve at localhost:8000 with live reload
mkdocs serve -a <host:port>
Pick address and port
mkdocs serve -a 0.0.0.0:8000
Reachable from other machines
mkdocs serve --dirty
Rebuild only changed pages
mkdocs serve -w <path>
Also watch another dir or file
mkdocs serve --watch-theme
Reload on theme changes
mkdocs serve --no-livereload
Disable auto reload
mkdocs serve -f <file>
Use another config file

Build and deploy

mkdocs build
Write the site to site/
mkdocs build --strict
Abort on any warning
mkdocs build -d <dir>
Choose the output folder
mkdocs build -f <file>
Use another config file
mkdocs build --clean
Remove stale files first (default)
mkdocs build --no-directory-urls
Use page.html style URLs
mkdocs build -t readthedocs
Override the built-in theme
mkdocs gh-deploy
Build and push to gh-pages
mkdocs gh-deploy -m "<msg>"
Set the deploy commit message
mkdocs gh-deploy -b <branch>
Deploy to another branch
mkdocs gh-deploy -r <remote>
Deploy to another remote
mkdocs gh-deploy --force
Force-push the branch
mkdocs gh-deploy --no-history
Squash branch history

mkdocs.yml

site_name: <title>
Required site title
site_url: <url>
Canonical URL of the site
nav:
Page order and titles
theme: name: <theme>
Choose theme (mkdocs, readthedocs, ...)
plugins: [search]
Enable plugins (replaces defaults)
markdown_extensions:
Add Python-Markdown extensions
docs_dir: <dir>
Source folder (default docs)
site_dir: <dir>
Output folder (default site)
strict: true
Warnings fail the build
repo_url: <url>
Link to source repo
edit_uri: edit/main/docs/
Per-page edit link path
extra_css:
Extra stylesheets in docs_dir
validation:
Set link problems to warn or ignore
- Home: index.md
Title plus file path
- index.md
File only, title taken from page
- Guide: - Intro: guide/intro.md
Nested section
- Issues: https://<url>
External link, title required
Where things live
Path Purpose
mkdocs.yml configuration
docs/index.md home page
docs/img/ images, linked relatively
site/ build output

Recipes

New project, preview
pip install mkdocsmkdocs new mysitecd mysitemkdocs serve
Material theme with search
pip install mkdocs-material# mkdocs.ymltheme:  name: materialplugins:  - search
CI check, then publish
mkdocs build --strictmkdocs gh-deploy --force
Preview on the LAN
mkdocs serve -a 0.0.0.0:8000 --watch-theme