Building documentation webpages with MkDocs

Info

Mkdocs is a static site generator that is useful for building project documentation. It combines document source files written in Markdown, and is configured with a single YAML file.

Installing Mkdocs

To install Mkdocs, run the following command from a terminal:

pip install mkdocs

Getting started with Mkdocs

To create a simple project that you can use to learn Mkdocs, run the following command:

mkdocs new learning-mkdocs
cd learning-mkdocs

The following files have been created for you.

.
├── docs
│   └── index.md
└── mkdocs.yml

You should now have a mkdocs.yml configuration file, a docs directory, and a index.md file within the docs directory. These are all the files that are needed in order to create a simple site using Mkdocs. Mkdocs has the dev tools required to preview the documentation as it is created.

From the learning-mkdocs directory, run mkdocs serve command. Open localhost:8000 in a browser and you should see the following page.

If you edit the mkdocs.yml config file, for example, by changing the site_name and saving the file. You should see the changes automatically take effect in your browser.

site_name: Learning Mkdocs

Once your browser reloads, you'll see the new changes!

Changing the theme

To change how the documentation is displayed the configuration file can be changed using a different theme. Edit mkdocs.yml to include a theme setting.

site_name: Learning Mkdocs
theme:
    name: material

Requirement: Material extension installed

Install Material by running the following command.

pip install mkdocs-material

Save the changes, and you'll see the Material theme being used.

Adding pages

To add a second page to your documentation:

curl 'https://raw.githubusercontent.com/tjzegmott/TJZegmott.github.io/master/files/markdown-intro.md' > docs/markdown.md

Now edit the configuration file to include navigation on the right of our page. Add information about the order, title, and nesting of each page by adding a nav setting.

site_name: Learning Mkdocs
theme:
    name: material
nav:
    - Home: index.md
    - Markdown: markdown.md

To nest the navigation tree lets edit the mkdocs.yml once more.

site_name: Learning Mkdocs
theme:
    name: material
nav:
    - Home: index.md
    - Skills:
        - Markdown: markdown.md

Requirement: Material for MkDocs Extensions

You might've noticed that some of the documentation is not displaying nicely. This is because markdown.md was written using Material for MkDocs extensions. These extensions can be installed by running:

pip install mkdocs-material-extensions

They must also be included in the mkdocs.yml

site_name: Learning Mkdocs

theme:
  name: material

# Extensions
markdown_extensions:
  - markdown.extensions.admonition
  - markdown.extensions.attr_list
  - markdown.extensions.def_list
  - markdown.extensions.footnotes
  - markdown.extensions.meta
  - markdown.extensions.toc:
      permalink: true

nav:
  - Home: index.md
  - Markdown: markdown.md

Further information

https://www.mkdocs.org/user-guide/writing-your-docs/