MkDocs

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:

Text Only

pip install mkdocs

Creating a Project

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

Text Only

mkdocs new learning-mkdocs
cd learning-mkdocs

The following files should have then been created for you:

Text Only

.
├── 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.

Opening the Documentation in the Browser

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.

YAML

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 to use a different theme. Edit mkdocs.yml to include a theme setting.

YAML

site_name: Learning MkDocs
theme:
    name: material

Requirement: Material Extention Installed

Install Material by running the following command:

Text Only

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, firt run this to copy an example Markdown file to your project:

Text Only

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:

YAML

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:

YAML

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

Requirement: Material for MkDocs Extentions

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

Text Only

pip install mkdocs-material-extentions

They must also be included in the mkdocs.yml

YAML

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

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

Further Reading

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