MkDocs

Creating a New Site

Create a directory for the project first, and a virtualenv with mkdocs installed.

pip install mkdocs

Create the project:

mkdocs new <project path>

Set up the site by adding markdown content to the docs directory and configuring it in the mkdocs.yml file. Set site_name, site_author, site_description at least, repo_url to github repo URL, and site_url to the root URL of the site if necessary.

Themes

This theme is mkdocs-bootswatch

Set the navigation_depth setting to 3 if <h3> headers should be included in sidebar navigation.

theme:
    name: flatly
    hljs_style: xcode
    navigation_depth: 3

readthedocs is a good built-in theme for actual documentation and is used by a lot of projects.

Development and Deploy Commands

Run dev server:

mkdocs serve

Build release:

mkdocs build

Clean:

mkdocs build --clean

Built content goes into a directory called site, the contents of which can be deployed wherever.

Markdown Extensions

Some good markdown extensions to include

markdown_extensions:
    - smarty
    - sane_lists
    - admonition
    - toc:
        permalink: True

The permalink setting for toc creates permalink anchors after every header.

Note

To create notes like this, preceed an indented block with a line like this:

!!! Note

Warning

To create warnings like this, preceed an indented block with a line like this:

!!! Warning

Tip

To create tips like this, preceed an indented block with a line like this:

!!! Tip

More on the admonition extension here

def python_function():
  print("code highlighting is done by highlightjs, not markdown's codehilite")

This Site

For this site I used pipenv because I hadn’t discovered poetry yet, so any and all commands need to be prefixed with pipenv run