MkDocs + material¶

Basic MkDocs and Material for MkDocs guides.

Tips¶

Note

Use a single # Header per page, or the Table of Content will disappear.

Reference¶

Material for MkDocs has a lot of interesting features. In this page there is an overview of some of them.

The source code to generate this examples is not shown, either check the source code of this page or follow the links in the headers to check the official documentation.

Admonitions ¶

Useful to include side content without significantly interrupting the document flow:

Note

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

Code blocks ¶

With title, line numbers and highlighted lines.

bubble_sort.py
def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

With code annotations (click the fancy + sign):

theme:
  features:
    - content.code.annotate # (1)!

I'm a code annotation! I can contain code, formatted text, images, ... basically anything that can be written in Markdown.

Math ¶

Easily write equations.

\[ \operatorname{ker} f=\{g\in G:f(g)=e_{H}\}{\mbox{.}} \]

Or use it inline: The homomorphism \(f\) is injective if and only if its kernel is only the singleton set \(e_G\), because otherwise \(\exists a,b\in G\) with \(a\neq b\) such that \(f(a)=f(b)\).

Content tabs ¶

Group alternative content under different tabs. Content tabs can be linked so that when clicking on a label all the tabs will switch:

CC++

#include <stdio.h>

int main(void) {
  printf("Hello world!\n");
  return 0;
}

#include <iostream>

int main(void) {
  std::cout << "Hello world!" << std::endl;
  return 0;
}

CC++

// more C code

// more C++ code

Lists ¶

On top of the standard ordered and unordered lists, material offers:

Definition lists:¶

key: value
other key: other value

Task lists:¶

Lorem ipsum dolor sit amet, consectetur adipiscing elit
Vestibulum convallis sit amet nisi a tincidunt
- In hac habitasse platea dictumst
- In scelerisque nibh non dolor mollis congue sed et metus
- Praesent sed risus massa
Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque

Commands¶

mkdocs new [dir-name] - Create a new project.
mkdocs serve - Start the live-reloading docs server.
mkdocs build - Build the documentation site.
mkdocs -h - Print help message and exit.
mkdocs gh-deploy --force - Publish the documentation to GitHub pages. Or use GitHub actions.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. ↩
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. ↩