Skip to content

MkDocs

MkDocs🔗

= ("[Website](" + this.url + ")") | = ("[Source](" + this.source + ")") | = ("[Documentation](" + this.docs + ")")
= ("> " + this.desc-short)

Caveats

  • use only relative links, not absolute links, for compatibility between different Markdown viewers/editors
    • using Markdown extensions such as mkdocs-ezlinked locate files and make it significantly easier to use links
    • obsidian: activate shortest possible paths in settings to achieve compatible links.

Getting Started🔗

  1. install mkdocs package and other requirements (from package repos or via pip, consider creating a new Python virtual environment)

    1
    pip install -r requirements.txt

    or only MkDocs package

    1
    pip install mkdocs

  2. create new project

    1
    mkdocs new my-project

    will create files/folders

    1
2
3
4
    my-project/
├── docs/
│   └── index.md
└── mkdocs.yml

  3. dump our Markdown files in docs/, e.g. as Git submodule

    1
    git submodule add URL docs

    or in separate subdirectories if you include more sources. Git’s sparse checkout can be helpful if you want to integrate repos containing more than documentation as this lets you chose which files and directories you want to have present.

  4. start server for local testing or build (output to public/)

    1
2
3
    mkdocs serve
# or
mkdocs build

CLI🔗

MkDocs documentation: CLI

Config🔗

In file mkdocs.yml.

Examples

Themes🔗

Mkdocs-Material🔗

See Website | PyPI

1
2
3
4
5
theme:
  features:

    - navigation.top  # back-to-top button
    - toc.follow  # auto-scroll toc sidebar

Markdown in MkDocs🔗

To ensure compatibility between MkDocs and other Markdown renderers, try to stick to Python-Markdown Specifications.
A number of Markdown extensions and MkDocs plugins is used, see mkdocs.yml. The script util/markdown.sh contains a number of functions to edit Markdown files in a batch

  • md_fix_lists_empty_line: add empty lines before Markdown lists that wouldn’t render as lists in MkDocs otherwise
  • md_fix_linestart_obsidian-tag: add text before Obsidian inline tage that would render as headings in MkDocs otherwise
  • fm_fix_tags_format: ensure tags in YAML front matter are proper YAML arrays (Obsidian accepts just a space as separator)
Markdown Extensions🔗

Clean

  • categorise extensions/plugins

See MkDocs documentation on markdown extensions, list of Python-Markdown extensions and Python-Markdown

  • TOC
  • Footnotes
  • Admonition: not configurable, full compatibility with Obsidian call-outs would require work (open/closed with > [!info]-) #todo/contrib
  • Definition Lists
  • mdx_truly_sane_lists: pip install mdx-truly-sane-lists

    Extension for Python-Markdown that makes lists truly sane. Custom indents for nested lists and fix for messy linebreaks and paragraphs between lists.

Issues: #16: doesn’t support mixing indentations | [#7: list not rendering without preceding empty line] #todo/tech/markdown/mkdocs

  • mdx-breakless-lists: don’t require empty line before lists, uses regex to enter empty line in processing, so one doesn’t have to change the source

mkdocs-material documentation

Example mkdocs.yml configuration 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
---
# some sections error'd with 2 spaces indentation, keep 4!
site_name:
# site_url:
repo_name: GitLab
repo_url:
edit_uri_template: '-/wikis/{path!q}/edit'  # doesn't work yet
# dev_addr: '127.0.0.1:8000'  # address used when running mkdocs serve
plugins:

    - search:
        lang: en
theme:
  name: material
  palette:
    primary: custom  # see https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/#custom-colors
extra_css:
  - assets/css/extra.css
markdown_extensions:
    - pymdownx.tasklist
    - footnotes
    - toc:
        permalink: "🔗"  # Generate permanent links at the end of each header
        baselevel: 2
        # marker: '[[_TOC_]]'  # no effect, material documentation doesn't mention this keyword
        # permalink_title:  # can maybe used with variable/template to get heading text instead of icon?
    - wikilinks  # see https://python-markdown.github.io/extensions/wikilinks/
    - attr_list
    - pymdownx.emoji:
        emoji_index: !!python/name:materialx.emoji.twemoji
        emoji_generator: !!python/name:materialx.emoji.to_svg
    - pymdownx.superfences:
        custom_fences:
            - name: mermaid
              class: mermaid
              format: !!python/name:pymdownx.superfences.fence_code_format
    - pymdownx.highlight:
        linenums: true
...

Plugins🔗

Editing🔗

See also Markdown.

MkDocs uses the Python Markdown library to translate Markdown files into HTML

YAML Metadata or Front Matter

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
---
title: My Document
summary: A brief description of my document.
authors:

    - Waylan Limberg
    - Tom Christie
date: 2018-07-10
some_url: https://example.com
---

Live-reload running mkdocs serve

This command by default rebuilds every page, without caching. When editing a single page this can be very frustrating as it may take a while until the results are rendered. With certain caveats,3 mkdocs serve --dirty can be used, to only rebuild pages that were changed.

Features🔗

Integrations🔗

A search plugin is provided by default with MkDocs which uses lunr.js as a search engine.1

Compatibility🔗

Obsidian🔗

As can be expected not all Markdown renders the same as different specifications are used.2 I have been working on a [MkDocs template] with some changes to the default Markdown config and adding some extensions/plugins to achieve as much as possible compatibility. The [list of to-dos] is getting shorter, but some critical features are yet missing.

Then there are some quite helpful plugins in Obsidian, especially Dataview. There have been requests in the forums, but no solution yet.
Maybe one day there will be a MkDocs DataView plugin, or system-independent plugins. For now, export rendered DataView results from Obsidian.

add missing links

References🔗

  1. https://www.mkdocs.org/user-guide/configuration/#search ↩

  2. Obsidian: mostly CommonMark vs MkDocs: Python-Markdown ↩

  3. https://github.com/mkdocs/mkdocs/issues/2384 ↩