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:

pip install mkdocs

Creating a Project¶

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 should have then 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.

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.

mkdocs-first-webpage

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

site_name: Learning MkDocs
theme:
    name: material

Requirement: Material Extention Installed

Install Material by running the following command:

pip install mkdocs-material

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

mkdocs-theme-change

Adding Pages¶

To add a second page to your documentation, firt run this to copy an example Markdown file to your project:

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

mkdocs-nav

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 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:

pip install mkdocs-material-extentions

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

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