Displaying markdown code instead of mindmap / Missing requirement

[redtux]

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:

[neatc0der]

Please provide your mkdocs.yml

[redtux]

@neatc0der, here are the relevant changes to my mkdocs.yml. Hope this helps! 👍🏼

Just in case: My markdown files (including mindmap.mm.md) are in ./docs, and everything seems to work fine - otherwise I would not see the included mindmap file as fenced code block, right? Hence, I guess I have an issue with parsing the markmap and generating the html - i.e., there is just a code block - and not a mindmap as expected.

@@ -143,6 +144,10 @@ plugins:
     - git-revision-date-localized
+    - markmap:
+          base_path: docs
+          encoding: utf-8
+          file_extension: .mm.md
     - minify:
           minify_html: true
           minify_js: true

@@ -168,6 +173,7 @@ markdown_extensions:
           permalink: true
     - markdown.extensions.smarty:
           smart_quotes: false
+    - markmap
     - pymdownx.arithmatex:
           generic: true
     - pymdownx.betterem:

[neatc0der]

The api was simplified with version 2.0.0, which removes the demand for defining markmap as markdown extension. Try to remove it from that section (second code block from your latest comment) and recreate/serve your pages again.

If that doesn't help I'll need more insight into your project.

[neatc0der]

Another thought on this: Looking at your plugins there may be some plugin combinations that are not getting along too well. minify sounds like a bummer for markmap, but I've just tested its version 0.4.0 and it currs 🐈.

[redtux]

Thank you a lot for your help! Unfortunately, I still cannot see what might be wrong.

What I did

Deleting - markmap below markdown_extensions in mkdocs.yml and disabling other plugins or extensions did not help. The described issue also happens with a clean new project without any other dependencies - no matter whether I use the default theme or material, as you can see (screenshots attached).

As far as I understand the readme, we would expect a "beautiful mindmap", right? As I could find no screenshots, I am not sure if I misunderstood the purpose of this plugin. I am looking for a way to integrate markdown mindmaps in my docs. I still hope that I am just missing something in my mkdocs.yml, but I don't know what. :)

Please find below all steps in detail for easy testing.

tree

.
├── docs
│   ├── index.md
│   └── mindmap.mm.md
├── mkdocs.yml
└── requirements.txt

1 directory, 4 files

mkdocs.yml

site_name: My Docs
theme: material
plugins:
  - markmap:

requirements.txt

mkdocs-material>=7.1.1
mkdocs-markmap>=2.0.1

Screenshots

• Markmap using default theme: https://2share.su/EAACA/
• Markmap using material design: https://2share.su/485D3/
• Generated mindmap.mm site: https://2share.su/D110A/

Create new project

mkdocs new mkdocs-project
INFO    -  Creating project directory: mkdocs-project
INFO    -  Writing config file: mkdocs-project/mkdocs.yml
INFO    -  Writing initial docs: mkdocs-project/docs/index.md

Use material design

cd  mkdocs-project
echo "mkdocs-material>=7.1.1" > requirements.txt
pip install --upgrade -r requirements.txt
echo "theme: material" >> mkdocs.yml

Install markmap plugin

echo "mkdocs-markmap>=2.0.1" >> requirements.txt
pip install --upgrade -r requirements.txt

Create a mindmap

Go to https://markmap.js.org/repl/ and save the markdown sample (see gist) in docs/mindmap.mm.md, and include it in docs/index.md using {!mindmap.mm.md!}.

Serve my site

mkdocs serve -s

[neatc0der]

Ok, so here's what I did:

conda create -n markmap-test python=3.8
conda activate markmap-test
pip install mkdocs==1.1.2 mkdocs-markmap==2.0.1 mkdocs-material==7.1.1 urllib3
mkdocs new foobar
cd foobar
cp docs/index.md docs/mindmap.mm.md
echo "{!mindmap.mm.md!}" >> docs/index.md
echo "plugins:\n - markmap" >> mkdocs.yml
mkdocs serve -sv

And it works for me...

Are you sure you've activated javascript in your browser? The mind map is not static content.

If you are absolutely sure you followed the above steps, please provide your mkdocs folder including the built sites.

[redtux]

I still get back a fenced code block instead of a mindmap.

• Javascript in Chromium is enabled, and uBlock is not blocking anything.
• I've tried with venv, with default theme (as in your example), and with material theme.
• Screenshot: https://2share.su/9738C/

Could you please send me a screenshot, so that I know what it should look like? Thanks a lot!

[neatc0der]

Ok, since you didn't provide the requested data, I'm sharing my test environment. Please find the attached zip file in order to:

1. Check if content in site shows your issue.
2. Verify that mkdocs build creates the exact same site content for you.

Also, to answer your question: The result should simply look like an embedded markmap graph.

[redtux]

Wow, great! As expected I am having a dependency issue. Sorry for not having provided the site directory - now I understand what you mean. When I first built the sites from your test environment the js folder was missing, but when using your requirements.txt it works. The issue with my original project persists, but now I have a better idea what to search for. 🎉

[neatc0der]

Please let me know, which dependency was missing, so I can add it for production requirements. I'll prepare a bug fix release for that.

[redtux]

I will have a look at it tomorrow and let you know. 👍🏼

So far the only thing I can say is that

1. disabling minify does not solve the issue,

2. not downloading the JS libs is part of the issue, i.e. this here does not happen

   INFO    -  Cleaning site directory
   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
   

3. as a consequence of this I am missing the links to js/unpkg.com/d3, js/unpkg.com/markmap-lib, and js/unpkg.com/markmap-view, and the div.mkdocs-markmap CSS in the generated index.html.

[neatc0der]

Well, that's odd... Let me know when you find something. #18 is prepared and ready to go, once we have solved the issue.

[redtux]

The only thing I can say so far is that the error occurs when using one of these two markdown extensions (or even both, as in my case 😄): pymdownx.magiclink or pymdownx.superfences

[redtux]

Okay, MagicLink is innocent. The issue might rather be a SuperFences bug.

mkdocs.yml

site_name: My Docs
theme: material
plugins:
  - markmap:
markdown_extensions:
  - pymdownx.superfences:
      preserve_tabs: true

pip show pymdown-extensions

Name: pymdown-extensions
Version: 8.1.1
Summary: Extension pack for Python Markdown.
Home-page: https://github.com/facelessuser/pymdown-extensions
Author: Isaac Muse
Author-email: [email protected]
License: MIT License
Location: /home/redtux/.local/lib/python3.8/site-packages
Requires: Markdown
Required-by: mkdocs-material

mkdocs build

INFO    -  Cleaning site directory 
INFO    -  Building documentation to directory: /home/redtux/src/webdev/mkdocs-project/site 
DEBUG   -  Reading markdown pages. 
DEBUG   -  Reading: index.md 
DEBUG   -  Reading: mindmap.mm.md 
/home/redtux/.local/lib/python3.8/site-packages/markdown/core.py:125: DeprecationWarning: The 'md_globals' parameter of 'mkdocs_markmap.e
xtension.MarkmapExtension.extendMarkdown' is deprecated.
  ext._extendMarkdown(self)
/home/redtux/.local/lib/python3.8/site-packages/jinja2/lexer.py:646: DeprecationWarning: invalid escape sequence '\s'
  self._normalize_newlines(value[1:-1])
INFO    -  Documentation built in 0.47 seconds 

[neatc0der]

Hm, I'm afraid this is out of this project's scope... Maybe there's a workaround. Try adding markmap explicitly before the malicious extension.

[redtux]

Thank you, I just commented out the extension! I am happy we at least found out what was causing the issue. Thx for your help and keep up the good work! 👌

[neatc0der]

Please see #19