Skip to content

mkdocs

install

virtualenv

$ virtualenv project
$ cd project
$ source bin/activate
$ pip3 install --upgrade pip
$ pip3 --version

mkdocs + material

$ pip3 install mkdocs
$ pip3 install mkdocs-material 
$ mkdocs new .

config

mkdocs.yml

site_name: Notepad on trantor.systems
site_url: https://notepad.trantor.systems

# only if using theme material
extra_css:
    - custom.css
extra_javascript:
    - js/script.js

nav:
    - index: index.md
    - mkdocs: mkdocs.md
theme:
    name: material
    custom_dir: overrides
markdown_extensions:
    - admonition            # to get: note, warning
    - attr_list
    - pymdownx.caret
    - pymdownx.highlight    # needs .superfences
    - pymdownx.keys         # for keys buttons
    - pymdownx.superfences
pymdownx.keys docs

usage

Start by editing .md files in docs/

Visualize changes during edition phase
$ mkdocs serve

Build site
$ mkdocs build

admonition: note, warning, etc...

Check that admonition is present in mkdocs.yml
Different kinds: note, warning, danger, info, tip, success, failure, bug... full list

!!! info

    4 spaces after 1 line blank

misc

plausible

js/plausible.js
/* script to add plausible script import in <HEAD> section */
document.addEventListener("DOMContentLoaded", function() {
    var script = document.createElement("script");
    script.defer = true;
    script.setAttribute("data-domain", "<DOMAIN>");
    script.src = "https://plausible.io/js/script.js";
    document.head.appendChild(script);
});