mkdocs-markmap

Beautiful and simple mindmaps written in markdown.

This is a plugin and an extension for mkdocs to add markmap.

Prerequisits

This plugin was tested with, but is not limited to:

• Python 3.9
• mkdocs 1.3

Quickstart

Install

bashCopy
pip install mkdocs-markmap

Configure

Add this to mkdocs.yml:

yamlCopy
plugins:
  - markmap

Usage

This plugin supports code blocks of markdown as follows:

markdownCopy
```markmap
# Root

## Branch 1

* Branchlet 1a
* Branchlet 1b

## Branch 2

* Branchlet 2a
* Branchlet 2b
```

It can also make use of file includes to keep your markdown tidy:

markdownCopy
Look at this beautiful mindmap:

{!mindmap.mm.md!}

Advanced Settings

There are more options available for mkdocs.yml (shown values are defaults):

yamlCopy
plugins:
  - markmap:
      base_path: docs
      encoding: utf-8
      file_extension: .mm.md
      d3_version: 7
      lib_version: 0.18
      view_version: 0.18

In addition, feel free to define your favourite source urls like this:

yamlCopy
plugins:
  - markmap:
      # disable the default assets first
      d3_version: ''
      lib_version: ''
      view_version: ''

extra_javascript:
  - https://unpkg.com/d3@7/dist/d3.min.js
  - https://unpkg.com/markmap-lib@0.18/dist/browser/index.iife.js
  - https://unpkg.com/markmap-view@0.18/dist/browser/index.js

Troubleshooting

Nav tree lists markmaps

1. Move your markmap files to a separate folder next to docs, e.g. mindmaps
2. Configure base_path accordingly (see Advanced Settings)

Static javascript files not working

1. Ensure naming of javascript files matches the scheme (see Advanced Settings)
2. Copy all javascript files to doc/js/, otherwise mkdocs will not copy static files to site/
3. Define all files in extra_javascript, e.g.

yamlCopy
extra_javascript:
  - js/markmap-d3.js
  - js/markmap-lib.js
  - js/markmap-view.js

Usage of proxy is preventing download of javascript files

Usually proxies should be supported by requests, which is used for downloading all required javascript files. If the issue remains, try downloading the files yourself and store them accordingly (see Static javascript files not working)

Credits :clap:

Some of the development approaches are based on implementations provided by the following projects:

• markmap (key feature of this project)
• markdown-include (basis for extension support)
• mkdocs-mermaid2-plugin (basis for plugin support)