markmap / mkdocs-markmap

MkDocs plugin and extension to create mindmaps from markdown using markmap

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

pip install mkdocs-markmap

Configure

Add this to mkdocs.yml:

plugins:
  - markmap

Usage

This plugin supports code blocks of markdown as follows:

```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:

Look at this beautiful mindmap:

{!mindmap.mm.md!}

Advanced Settings

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

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

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

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/[email protected]/dist/browser/index.js
  - https://unpkg.com/[email protected]/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.

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 👏

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)

mkdocs-markmap's Issues

mkdocs serve no longer works with mkdocs-markmap

Error log when mkdocs-markmap is enabled in mkdocs.yml:

❯ mkdocs serve
INFO     -  Building documentation...
INFO     -  Cleaning site directory
ERROR    -  Error reading page 'index.md': extendMarkdown() missing 1 required positional argument: 'md_globals'
Traceback (most recent call last):
  File "/Users/andy/Devel/code-vault2/vaultenv/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
  File "/Users/andy/Devel/code-vault2/vaultenv/lib/python3.9/site-packages/click/core.py", line 1130, in __call__
    return self.main(*args, **kwargs)
  File "/Users/andy/Devel/code-vault2/vaultenv/lib/python3.9/site-packages/click/core.py", line 1055, in main
    rv = self.invoke(ctx)
  File "/Users/andy/Devel/code-vault2/vaultenv/lib/python3.9/site-packages/click/core.py", line 1657, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/Users/andy/Devel/code-vault2/vaultenv/lib/python3.9/site-packages/click/core.py", line 1404, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/Users/andy/Devel/code-vault2/vaultenv/lib/python3.9/site-packages/click/core.py", line 760, in invoke
    return __callback(*args, **kwargs)
  File "/Users/andy/Devel/code-vault2/vaultenv/lib/python3.9/site-packages/mkdocs/__main__.py", line 181, in serve_command
    serve.serve(dev_addr=dev_addr, livereload=livereload, watch=watch, **kwargs)
  File "/Users/andy/Devel/code-vault2/vaultenv/lib/python3.9/site-packages/mkdocs/commands/serve.py", line 63, in serve
    config = builder()
  File "/Users/andy/Devel/code-vault2/vaultenv/lib/python3.9/site-packages/mkdocs/commands/serve.py", line 58, in builder
    build(config, live_server=live_server, dirty=dirty)
  File "/Users/andy/Devel/code-vault2/vaultenv/lib/python3.9/site-packages/mkdocs/commands/build.py", line 292, in build
    _populate_page(file.page, config, files, dirty)
  File "/Users/andy/Devel/code-vault2/vaultenv/lib/python3.9/site-packages/mkdocs/commands/build.py", line 174, in _populate_page
    page.render(config, files)
  File "/Users/andy/Devel/code-vault2/vaultenv/lib/python3.9/site-packages/mkdocs/structure/pages.py", line 171, in render
    md = markdown.Markdown(
  File "/Users/andy/Devel/code-vault2/vaultenv/lib/python3.9/site-packages/markdown/core.py", line 96, in __init__
    self.registerExtensions(extensions=kwargs.get('extensions', []),
  File "/Users/andy/Devel/code-vault2/vaultenv/lib/python3.9/site-packages/markdown/core.py", line 125, in registerExtensions
    ext.extendMarkdown(self)
TypeError: extendMarkdown() missing 1 required positional argument: 'md_globals'

How to turn off INFO debug information

how can I turn off these

Need parameters to change the size of the map window

When the content has a lot, it is hard to see other contents of the page:

Are there any parameters like "height = 200px; font = 20px" to decrease the size/ font of the diagram?

nav tree displaying root from markmap

Config:

mkdocs.yml:

site_name: test

theme:
    name: 'material'
    palette:

    # Light mode
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: pink
      accent: indigo
      toggle:
        icon: material/toggle-switch-off-outline
        name: Switch to dark mode

    # Dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: pink
      accent: blue
      toggle:
        icon: material/toggle-switch
        name: Switch to light mode

# Extensions
markdown_extensions:
  - footnotes
  - toc:
      permalink: true

plugins:
  - search
  - markmap

docs:

index.md:

Look at this beautiful mindmap:

{!mindmap.mm.md!}

mindmap.mm.md:

# Root 1
* Point 1
# Root 2

## Branch 1

* Branchlet 1a
* Branchlet 1b

## Branch 2

* Branchlet 2a
* Branchlet 2b

Logs:

INFO     -  script downloaded: https://unpkg.com/[email protected]/dist/d3.min.js
INFO     -  script downloaded: https://unpkg.com/[email protected]/dist/browser/index.min.js
INFO     -  script downloaded: https://unpkg.com/[email protected]/dist/index.min.js
INFO     -  no markmap found: mindmap.mm

---

Problem:

Root from mindmap is on nav bar:

Doesn't work with pymdownx.superfences (9.0)

#19 only supports pymdown-extensions < 9.0, but with the update the support is broken again.

imports not working

First of all, thanks for this great plugin!

I would like to use this in my mkdocs installation and it seems to work great for inlined mindmaps. However, I can't get it to show mindmaps imported with {!mindmap.mm.md!}. It seems to simply skip that import statement. How can I deboug / fix this?

I'm running mkdocs 1.4.0 and mkdocs-markmap 2.3.0.

Thanks!

Error to download javascript dependencies with corporate proxy

I'm using version 2.2.0 and the problem is there.

I analyzed #20, but the problem remains, when I test on another non-corporate machine the download is done.

I downloaded it manually and referenced it in mkdocs.yml using extra_javascripts but without success.

can you help? the plugin is excellent! I'm very grateful!

Optimize markmap.js usage when centering graphs

Currently this is being done with a dirty implementation:

• issuing a timeout to wait for proper resizing of the container
• manually removing all children from svg
• recreating a markup object
• doing this for all markmaps on the page

In the future, this should be done by simply calling a single option of markmap.js. Unfortunately, I couldn't find any solution to that, yet.

Markmap does not work in SPA after navigation

• Version: 2.3.0
• Screenshot before refresh:

Does not work behind a corporate proxy

Thanks for this Excellent Plugin. Its very helpful for me in preparing Mindmaps
one thing where I face issue is when I am behind a proxy, the script hangs when trying to download the dependent javascripts.
I some how tried to make it work by making the below changes. Do you think this change make sense or if you can suggest some better ways to overcome this problem.

Does not work with pymdownx.superfences

First of all thank you very much for the plugin, very useful.

Is there any possibility to tweak it to work with pymdownx.superfences? pymdownx.superfences for me is very important, thank you very much.

I found an issue, but it seems they didn't come up with a solution #17.

Use of Katex and some other stuff

Firstly, many thanks for this extension, it makes it really easy.

• I'm trying to insert KaTeX math, I'm pretty sure it's possible, but I'm unable.

I saw that possibility here : https://marketplace.visualstudio.com/items?itemName=gera2ld.markmap-vscode

I'm using mkdocs-material with the macro plugin.

Could you confirm it's possible ? It would be nice, in that case, to show the configuration for that.

Again, many thanks,
Franck

Template files for javascript

Support for Markdown frontmatter

I'm trying to use the markmap frontmatter options as described in https://markmap.js.org/docs/json-options#markdown-frontmatter.

Is this possible with mkdocs-markmap?

I tried to use the following code without success:

```markmap
---
markmap:
  maxWidth: 50
---

# Test1 Test1 Test1 Test1 Test1 

## Test2 Test2 Test2 Test2 Test2 

## Test3 Test3 Test3 Test3 Test3 
```

I've also tried to specify the latest versions of the libraries in the mkdocs.yml file as follows with no difference in the final result:

- markmap:
    lib_version: 0.14.4
    view_version: 0.14.4

Displaying markdown code instead of mindmap / Missing requirement

Hi, thank you for this nice plugin! Unfortunately, the extension is not creating a mindmap from my markmap file. The file has been tested with https://markmap.js.org/repl/ and vscode.

How to reproduce

I followed the docs, and mkdocs serve -s gives no error (only several deprecation warnings for the 'md_globals' parameter, see markdown/core.py:124).

Calling the file from another markdown file via {!mindmap.mm.md!} displays the raw file content in a code box. Including mindmap.mm.md to the nav section of mkdocs.yml generates a normal html site with all headings, links, and unordered lists - but no mindmap.

Am I missing a dependency, or is this maybe a dependency issue? As configuration is pretty simple (thanks for this!), I cannot see where I might have committed an error.

Installed versions

pip -V
pip 21.0.1 from /home/redtux/.local/lib/python3.8/site-packages/pip (python 3.8)

lsb_release -ds
Ubuntu 20.04.2 LTS

pip show mkdocs
Name: mkdocs
Version: 1.1.2
Summary: Project documentation with Markdown.
Home-page: https://www.mkdocs.org
Author: Tom Christie
Author-email: [email protected]
License: BSD
Location: /home/redtux/.local/lib/python3.8/site-packages
Requires: livereload, click, tornado, Markdown, PyYAML, Jinja2, lunr
Required-by: mkdocs-minify-plugin, mkdocs-material, mkdocs-markmap, mkdocs-git-revision-date-localized-plugin, mkdocs-exclude, mkdocs-awesome-pages-plugin

pip show mkdocs-material
Name: mkdocs-material
Version: 7.1.1
Summary: A Material Design theme for MkDocs
Home-page: https://squidfunk.github.io/mkdocs-material/
Author: Martin Donath
Author-email: [email protected]
License: MIT
Location: /home/redtux/.local/lib/python3.8/site-packages
Requires: mkdocs-material-extensions, markdown, mkdocs, pymdown-extensions, Pygments
Required-by: mkdocs-material-extensions

pip show mkdocs-markmap
Name: mkdocs-markmap
Version: 2.0.1
Summary: MkDocs plugin and extension to creates mindmaps from markdown using markmap
Home-page: https://github.com/neatc0der/mkdocs-markmap
Author: neatc0der
Author-email:
License: MIT
Location: /home/redtux/.local/lib/python3.8/site-packages
Requires: attrs, mkdocs, beautifulsoup4
Required-by:

mkdocs-markmap breaks <center> tag in new mkdocs-material 8.0.1 theme

Hi,

It seems that this simple code does not work anymore with mkdocs-material version 8.0.1, and your mkdocs-markmap plugin activated in mkdocs.yml :

<center>

|a|b|
|:-:|:-:|
|1|2|

</center>

I had to deactivate this plugin in mkdocs.yml to get the

tag work again.

Could you please solve this, and make them compatible again, if possible?

Please feel free to get back in touch if my request is unclear :)

Thanks a lot in advance

Support for mkdocs-encryptcontent-plugin

mkdocs.yml:

# Project information
site_name: 'Code Vault'
site_description: 'Programming Notes'
site_author: 'Andrzej Zahorski'

# Repository
# repo_name: ''
# repo_url: ''

# Copyright
copyright: 'Copyright © 2021 Andrzej Zahorski'

# Plugins
plugins:
  - markmap
  - search

  # - alternate-link
  # - literate-nav:
      # nav_file: SUMMARY.md
  - roamlinks
  - encryptcontent:
      password_button: True
      password_button_text: 'custome_text_button'

## Extensions
markdown_extensions:
  - footnotes
  - pymdownx.highlight:
      linenums: true           
  - pymdownx.superfences   
  - pymdownx.inlinehilite  
  - pymdownx.keys
  - pymdownx.snippets  
  - admonition
  - pymdownx.details  
  - attr_list





  # - attr_list
  # - pymdownx.arithmatex
  # - pymdownx.details
  # - pymdownx.magiclink
  # - pymdownx.tasklist:
  #     custom_checkbox: true
#  - pymdownx.emoji:
#      emoji_generator: !!python/name:pymdownx.emoji.to_svg
  # - admonition
  - mdx_truly_sane_lists

  - toc:
      permalink: true

# Configuration
theme:
  font:
    text: Sarala
  features:
    - search.suggest    
    - search.highlight     
    - search.share
  
  
  name: 'material'
  language: 'en'
  # logo: 'images/logo.png'
  # favicon: 'images/logo.png'
  palette:
    - media: "(prefers-color-scheme: light)"
      scheme: default
      toggle:
        icon: material/weather-night
        name: Switch to dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      accent: orange
      primary: red
      toggle:
        icon: material/weather-sunny
   # Configuration

theme:
  font:
    text: Roboto
  features:
    - search.suggest    
    - search.highlight     
    - search.share
    - navigation.indexes
  name: 'material'
  language: 'en'
  # logo: 'images/logo.png'
  # favicon: 'images/logo.png'
  palette:
    - media: "(prefers-color-scheme: light)"
      scheme: default
      toggle:
        icon: material/weather-night
        name: Switch to dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      accent: red
      primary: red
      toggle:
        icon: material/weather-sunny
        name: Switch to light mode
  
  

# Customisation
extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/andynameistaken


extra_css:
  - 'stylesheets/extra.css'

      
nav:
- Java:
    - Java/md-java/index.md
    - Object Oriented Programming: Java/md-java/Object-Oriented-Programming.md
    - Map: mindmap.mm.md

❯ tree docs:

docs
├── Java
│   ├── images
│   │   ├── bicycleObjPaint.png
│   │   ├── concepts-bikeHierarchy.png
│   │   ├── concepts-object.png
│   │   ├── package-tree.png
│   │   └── universe.jpeg
│   └── md-java
│       ├── Object-Oriented-Programming.md
│       └── index.md
├── index.md
├── mindmap.mm.md
└── stylesheets
    └── extra.css

4 directories, 10 files

Relax attrs version

Hi, would it be possible to relax the attrs version required and allow newer versions?
It is currently locked to attrs==20.3.0, but from what I can see in the code, the attrs use is fairly limited.

Integration of Mastodon

https://fosstodon.org/web/@neatc0der

Register extension automatically within plugin

Incompatibility between vscode-markmap and mkdocs-markmap

The syntax makes it unusable for VSCode users! I use mkdocs to render my notes in HTML, which I take in markdown. To render the mindmaps using the official markmap extension in VSCode I need to write a plain markdown document. To make it work in mkdocs-markmap I need to put it inside a code snippet with the triple quote. These two formats are incompatible. Is there any way I can make this work in both sides?

Provide javascript files locally

Current Behavior:

Markmap and D3 are provided via a link to unpkg.com

Expected Behavior:

During build all required javascript files are downloaded and stored locally.

Dependency conflict with mkdocs-material

When using mkdocs-material-8.1.11+insiders.4.8.3 and installing mkdocs-markmap (version 2.2.0) I get this:

ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts.
mkdocs-markmap 2.2.0 requires requests==2.25.1, but you have requests 2.27.1 which is incompatible.

superfences detected by markmap note when rendering mkdocs site

The plugin works well, thank you for building it.

I notice that we get the 'superfences detected by markmap' note when rendering mkdocs site (mkdocs build). This list (as in screenshot) increases with the number of pages in the site, consuming time as well as creating doubt of a conflict with superfences.

Any way to fix it?

Exception in mkdocs 1.5

mkdocs 1.5.0 and 1.5.1 introduces an issue in this plugin.

FWIW some other plugins have broken since the 1.5.0 release.

  File "/.pyenv/versions/3.11.4/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
             ^^^^^
  File "/.pyenv/versions/3.11.4/lib/python3.11/site-packages/click/core.py", line 1130, in __call__
    return self.main(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/.pyenv/versions/3.11.4/lib/python3.11/site-packages/click/core.py", line 1055, in main
    rv = self.invoke(ctx)
         ^^^^^^^^^^^^^^^^
  File "/.pyenv/versions/3.11.4/lib/python3.11/site-packages/click/core.py", line 1657, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/.pyenv/versions/3.11.4/lib/python3.11/site-packages/click/core.py", line 1404, in invoke
    return ctx.invoke(self.callback, **ctx.params)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/.pyenv/versions/3.11.4/lib/python3.11/site-packages/click/core.py", line 760, in invoke
    return __callback(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/.pyenv/versions/3.11.4/lib/python3.11/site-packages/mkdocs/__main__.py", line 270, in serve_command
    serve.serve(**kwargs)
  File "/.pyenv/versions/3.11.4/lib/python3.11/site-packages/mkdocs/commands/serve.py", line 98, in serve
    builder(config)
  File "/.pyenv/versions/3.11.4/lib/python3.11/site-packages/mkdocs/commands/serve.py", line 79, in builder
    build(config, live_server=None if is_clean else server, dirty=is_dirty)
  File "/.pyenv/versions/3.11.4/lib/python3.11/site-packages/mkdocs/commands/build.py", line 349, in build
    _build_page(
  File "/.pyenv/versions/3.11.4/lib/python3.11/site-packages/mkdocs/commands/build.py", line 235, in _build_page
    output = config.plugins.on_post_page(output, page=page, config=config)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/.pyenv/versions/3.11.4/lib/python3.11/site-packages/mkdocs/plugins.py", line 586, in on_post_page
    return self.run_event('post_page', output, page=page, config=config)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/.pyenv/versions/3.11.4/lib/python3.11/site-packages/mkdocs/plugins.py", line 507, in run_event
    result = method(item, **kwargs)
             ^^^^^^^^^^^^^^^^^^^^^^
  File "/.pyenv/versions/3.11.4/lib/python3.11/site-packages/mkdocs_markmap/plugin.py", line 109, in on_post_page
    self._load_scripts(soup, script_base_url, js_path)
  File "/.pyenv/versions/3.11.4/lib/python3.11/site-packages/mkdocs_markmap/plugin.py", line 62, in _load_scripts
    for script_url in self.markmap.values():
                      ^^^^^^^^^^^^
  File "/.pyenv/versions/3.11.4/lib/python3.11/site-packages/mkdocs_markmap/plugin.py", line 52, in markmap
    if f'markmap-{name}' in uri.lower():
                            ^^^^^^^^^
AttributeError: 'ExtraScriptValue' object has no attribute 'lower'

Minor rendering issues

Thanks for this interesting plugin! I am @fralau, the maintainer of the mermaid2 plugin. I believe that the idea of using markdown to represent mindmaps is sensible, and that the concept appears more mature than Mermaid minmaps!

Since it worked out of the box 👍 , I threw the whole demo diagram from markmap.js.org at it. It also worked immediately, so 👍 again!

Just a minor issue, the inline code is printed vertically:

 - `inline code`

(I also appreciated that it works directly with pymdownx.superfences, out of the box).