The MindMeister Markdown Showdown

Welcome Donald Curtis

I’d like to welcome Donald Curtis as a guest blogger today, here to talk about a very cool script we worked on to add some Markdown love to MindMeister. It started with a DM from Donald on Twitter with a link to a GitHub gist, and after some back and forth it became a very cool (and useful) tool. Cool enough that I really wanted to share it here. Since the script is his brainchild and almost entirely his handiwork, I thought it would be cool if Donald did the honors.

The backstory

I am nearing the end of my first semester as a professor at a small liberal arts college. My graduate school years left me fairly detached from some of the topics I learned in my undergrad years and so I spend a decent amount of time simply re-acquainting myself with material. It is easy to digest the second time around, but as I process the material I also have to think about how and what to present.

Mind maps have turned out to be an exceptionally useful tool for organizing the key ideas I want to cover. And for whatever style of teaching I employ, they end up being a great in-class reference.

When I first started toying with the idea of incorporating mind maps, I did the search for the right software tool. I considered software-only solutions such as iThoughts HD for iOS and My Thoughts for Mac, with Dropbox as the glue. Both of these apps look amazing and sometimes that’s all the motivation you need.

After reading Brett’s Appstravaganza I gave MindMeister a spin (because they offer a free as in beer account). By the time I started paying for the account, I was in. You can read more about the app in Brett’s discussion about mind mapping, but in summary: free trial, web-based (read: multi-platform), decent iOS app, looks good, and roughly equivalent yearly cost to software-only solutions. The added bonus for my application is–on the occasion I have an external link to a picture or movie–MindMeister works on the lecture machines.

Stepping back, I assume teaching isn’t a scenario that a lot of the readership can associate with. Not to worry, mind maps are useful in a wide variety of scenarios.

The MindMeister Markdown Showdown

MindMeister lacks one feature to satisfy the Markdown users among us: export to Markdown. Brett recently had a Quick Tip that showed how to use Mindjet MindManager to get a MindMeister map to HTML through Markdown. I don’t use Mindjet and I didn’t want to really have to install another piece of software and figure out how to migrate my maps through it. After all, the approach was described as a “quick hack” so I assume if I went ahead and described it as a bit contrived–in order to make myself sound smarter–there would be no hard feelings [Ed: there would not]. I would never say such a thing though. It gets the job done.

In order to have a more elegant solution and teach myself Ruby, I wrote up a small script that uses the MindMeister API to pull down maps as a markdown-formatted outline. I named the script for clarity as mindmeister2md.rb. With help from Brett to refine much of the output–clean up newlines, fix escaped characters, add notes, add pictures–the core script that I wrote is now very usable.

Overview

The script has two functions,

• list all your maps
• output a map as markdown

When run with no arguments, the script prints a menu of maps available for you to select:

Available MindMeister Maps
---
1: Software ( 2011-10-31 04:13:58 ) [ 117882387 ]
2: Internet Layer Protocols ( 2011-10-27 18:10:26 ) [ 120233062 ]
3: Network Layer ( 2011-10-27 16:41:09 ) [ 119115816 ]
4: HTML ( 2011-10-24 17:59:28 ) [ 117882606 ]
5: Newbie ( 2011-10-24 03:53:40 ) [ 119564927 ]
6: Ethernet ( 2011-10-24 03:53:00 ) [ 116616227 ]
7: My First iPad Map ( 2011-10-21 14:19:07 ) [ 119100256 ]
8: My First iPhone Map ( 2011-10-21 14:17:30 ) [ 119262965 ]
9: Threads ( 2011-10-20 15:14:29 ) [ 116945908 ]
10: Computer Hardware ( 2011-10-12 19:24:19 ) [ 117875898 ]
11: ACM Programming Tips ( 2011-10-11 04:03:21 ) [ 117550509 ]
12: Interprocess Communication ( 2011-10-04 02:54:56 ) [ 116511362 ]
Selection:

Optionally you can pass either the name of a map (case insensitive) or the map id (given in square brackets in the menu) as argument(s)¹. Both of these would return the “My First iPad Map”,

./mindmeister2md.rb my first ipad map
./mindmeister2md.rb 119100256

By default the script outputs the markdown to the screen. There is an optional command-line argument (-o) which will write the markdown to a file.

For the UNIX geeks: Only the generate markdown is sent to standard output (STDOUT). For Mac users this means the ability to copy the markdown to the copy buffer:

./mindmeister2md.rb my first ipad map | pbcopy

Configuration

There is one downside to using the MindMeister API with a script: each user needs to have a MindMeister api key and secret in order to use the script². Rather than edit the source code, the script relies on a configuration file named .mindmeister2md in the home directory. The file will be created automatically the first time you run the script; it will complain to you about you needing to update the configuration and specify an API key and your music being too loud.

The configuration file looks like this:

--- 
 indent: 4
 list_level: 2
 api_key: 
 secret:

You get both api_key and secret from the MindMeister api request page. The other two options you can set are:

list_level

The level in the map where lists should begin. At a list_level of 2, the first two levels of the map tree structure are represented as markdown headings, rather than as lists. A list_level of 0 will mean that the map will be exported as a single giant list.

indent

specifies the number of spaces that represent a single indent in the list.

Command Line Options

Most of the configuration file can also be changed at run-time using optional command line arguments. There is also an option to simply print the maps without actually printing any of them out as well as output to a file.

-l, --list

List available maps and exit.

-i, --indent <indent>

Set number of spaces for each indent level. Like temporarily setting indent in the configuration file.

-s, --listlevel <list_level>

Set the level at which lists should start. Like temporarily setting list_level in the configuration file.

-o, --output FILE

Write output to FILE.

-h, --help

Print command-line argument help.

Thanks to Brett for his major contributions to the script–which actually made it useful–and for letting me send him this writeup. You can find me on Twitter, Github, and I sometimes post bad prose on milkbox.net.

Check out mindmeister2md on GitHub, or download below.

Download