mkdocs-flake¶

This project makes integrating mkdocs with many plugins to your project easy.

Pre-Bundled easy to use Mkdocs
Cool Mkdocs Material Design
Markdown-integrated PlantUML
Code Blocks with highlights and annotations
Available as Nix Flake
Available as Flake-parts module
Available as Docker Image

Try it¶

Nix¶

The best way to use this project is via Nix.

Install Nix

Run this command inside your mkdocs project:

nix run github:applicative-systems/mkdocs-flake

That's it, you can live-edit your documentation.

To do more, as publishing it on GitHub automatically via your CI, please have a look at our integration docs

Docker¶

This repo generates a docker image.

TODO: Document

TODO: Provide dockerhub image from https://hub.docker.com/r/applicativesystems/mkdocs

Plugins¶

Diagrams¶

Mermaid works out of the box, but we also added PlantUML support!

Plantuml is a bit more sophisticated than Mermaid and contains a standard library with many useful icons and styles.

Worth mentioning is especially the C4 standard library:

Code¶

The code blocks with annotation support as documented by mkdocs-material work out of the box:

bubble_sort.py

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

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

Math¶

You can use MathJax and KaTeX out of the box:

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