freeplane2md

freeplane2md converts mind maps in Freeplane format into Markdown.

Freeplane is a widely used mind mapping application used for notetaking, brainstorming, planning and similar tasks. Its file format (usual ending .mm) is a dialect of the Freemind XML format. Often though, one might want to continue to use your mind map as Markdown document, e.g. to

use the content in tools accepting Markdown (e.g. GitHub, issue tracker, Wikis, etc.),
edit it on mobile devices,
make it easier accessible to people not working with Freeplane,
integrate the content into your second brain or Zettelkasten, e.g. with Obsidian, Dendron, Foam or similar,
publish the result as a text document.

Furthermore, Freeplane can this way be used as a more visual tool to create Markdown in the first place, e.g. when brainstorming with many people.

There are already different scripts and plugins exporting or converting towards Markdown. However, these are so far very limited, as they mainly export all nodes as headers and also do not handle many Freeplane features, such as links and icons (e.g. https://github.com/memoryblade/mm2md/blob/master/mm2md.py, https://github.com/gelso/freeplane2markdown)

Features

Provides a command line interface and a scriptable function to convert Freeplane files to Markdown.
Freeplane nodes are converted to Markdown headers down to a configurable level and to list items below that level.
Frequently used icons are converted to emojis using shortcode syntax as understood by most Markdown tools.
Freeplane links are converted to Markdown links.
- Links to URLs or E-Mail addresses are converted to automatic links.
- For local links within the document, custom IDs are generated from the Freeplane node IDs.
- Links to local Markdown files are converted to [[WikiLinks]] as understood by many tools.
Freeplane connections between nodes are converted to document local links.
Checkbox icons are converted to Markdown extended syntax checkboxes (- [ ], - [x]).
Basic support of HTML embedded in nodes. (May disarray nesting of related nodes translated to consecutive paragraphs).

Usage

freeplane2md.py [options] <mindmap>

or depending on your python installation

python freeplane2md.py [options] <mindmap>

Arguments

<mindmap> Mind map file to be converted, usually with ending .mm. The output path name becomes the input path name with '.mm' replaced with '.md', unless explicitly given with --output.

Options

-h --help                   Show help.
-V --version                Show version.
-v --verbose                Output additional information to stderr.
-o --output=<markdownfile>  Specify Markdown-file to be written to.
                            "-o -" writes to stdout.
-n --no-clobber             Do not overwrite target file, if it already
                            exists. (Overwritten by -f) 
-f --force                  Force overwriting target file.         
--no-timestamp              Omit HTML comment with timestamp, which is
                            otherwise used to prevent eroneous overwrites.  
-l --headerlevel=<level>    Number of levels to be converted to
                            headers [default: 1] 
-t --todo                   Treat as to-do list. Translate non header
                            nodes without icons to tasks with checkboxes
                            (- [ ]) and nodes with checkmark icons to
                            done tasks (- [x]).

Examples

Several examples can be found in the folder test/. E.g. the mind map test.mm shows most supported features and is converted to test.md, if no options are set.

Installation

The script requires Python 3 and the following packages need to be installed:

docopt
validators
python-dateutil
pytest (if you want to run the automated tests)

The above packages can be installed with pip individually or all at once with:

pip install -r requirements.txt

Usage as library

freeplane2md can as well be used from other scripts by importing as a module and calling the function convert_file.

Planned improvements

Support further Freeplane features, such as embedded Markdown, $\LaTeX$ or notes.
Test and fix some edge cases, e.g. with empty nodes or connections and links overlapping within the same node.
Better HTML handling, when interfering with indentation and nesting of consecutive paragraphs.
Provide more examples.
Easier installation.

OliverCi/freeplane2md