MkDocs

Project documentation with Markdown.

Installation

Attention

To install MkDocs, ensure that you have Python 3 installed on your system with pip installed.

With pip and Python 3 installed on your system, run the following command in the terminal:

1
pip install mkdocs

Theming

For this workshop we will be using the Material for MkDocs theme, which can be installed via the terminal:

1
pip install mkdocs-material

Now edit the config.yml file in the source folder to use the Material theme in MkDocs by adding these two lines:

1
2
theme:
    name: "material"

For more customization options using the Material theme, one can refer to Getting Started.

Site Configuration

The website is configured by editing the config.yml file.

A sample config.yml file is as follows:

1
2
3
4
5
6
site_name: Test
site_description: "This is a test site."
site_author: "Admin"
copyright: "Licensed under GNU GPL v3.0"
nav:
    - Home: index.md

Adding new pages

New pages can be added by creating new Markdown files and editing the nav section in config.yml.

An example could be an About page with the source code in about.md. We edit config.yml as follows:

1
2
3
4
5
6
7
site_name: Test
site_description: "This is a test site."
site_author: "Admin"
copyright: "Licensed under GNU GPL v3.0"
nav:
    - Home: index.md
    - About: about.md

Adding new sub-sections

Let's say you want to create two sub-sections under About, one to introduce the project (source code in project.md) and one for a writeup on yourself (source code in author.md).

config.yml can be modified as follows:

1
2
3
4
5
6
7
8
9
site_name: Test
site_description: "This is a test site."
site_author: "Admin"
copyright: "Licensed under GNU GPL v3.0"
nav:
 - Home: index.md
   - About:
      - The Project: project.md
      - The Author: author.md

Serving the site

To preview your documentation as you work on it, navigate to the subdirectory where all the source files are stored and run the following command:

1
mkdocs serve

A local server instance will be created at http://localhost:8000/ by default.

The local server will update automatically once changes in the source directory are detected.

Building the site

Attention

To build the site files using MkDocs, ensure that the local server instance is NOT running.
It can be killed by the keyboard shortcut Ctrl C.

To build the site files, run the following command in the terminal:

1
mkdocs build

By default, the site files can be found at /site/.