How do I install MultiMarkdown?

How do I install MultiMarkdown?

The "Basic" instructions below will get you a functioning installation of MultiMarkdown, including the following commands:

• multimarkdown
• mmd
• mmd2tex
• mmd2opml
• mmd2odf

The "Advanced" instructions will help if you want to make use of some of the more advanced features, such as custom XSLT output, you will need to install the MultiMarkdown Support files.

If you want to use the LaTeX features, it would be helpful to install the LaTeX support files.

The instructions are provided for several operating systems:

• [Mac OS X]
• [Windows]
• [Linux]

Mac OS X

Basic

On the Mac, you can choose from using an installer to install the program and required libraries for you, or you can compile it yourself from scratch. If you know what that means, follow the instructions below in the Linux section. Otherwise, definitely go for the installer!

1. Download the latest version of the MultiMarkdown-Mac installer from the downloads page
2. Unzip the downloaded file, then run the installer and follow the onscreen directions.

Advanced

If you want to use XSLT to customize your output, or you want to use MultiMarkdown with Scrivener or TextMate, you should also download and run the MultiMarkdown-Support-Mac installer.

If you want to use LaTeX to generate PDFs, I recommend downloading the LaTeX support files and placing them in ~/Library/texmf/tex/latex/mmd.

Compiling

The instructions for compiling on Mac OS X are similar to the [Linux] instructions below. If you want to build an installer, you can switch to the mac-installer branch, and use the make mac-installer command.

On Mac OS X, please note that you will need to install the Developer Tools. You then need to install a few libraries. I used homebrew:

brew install pkg-config glib gettext

You can also use fink or something similar (though this caused some machine architecture incompatibilities for me):

fink install glib2-shlibs glib2-dev

Windows

Basic

The easiest way to install MMD on Windows is the MultiMarkdown-Windows installer from the downloads page and run it. The installer is built using software by BitRock.

Just as with the Mac OS X version, the installer includes the multimarkdown binary, as well as several convenience scripts.

You can use Windows Explorer to create shortcuts to the multimarkdown binary, and adjust the properties to allow you to create "drag and drop" versions of MMD as well.

Advanced

If you intend to use LaTeX to generate PDFs, you will need to install a working version of LaTeX. I have used TeX Live in the past, but the details of installing that are up to you. I would also recommend installing the LaTeX support files.

If you want to use XSLT to customize your output, you will need to install a working version of xsltproc and a program to allow you to run shell scripts so that you can use the MMD-Support utility scripts. This is fairly complicated to install on Windows, so I highly recommend that you determine whether you really need these features. Most of the customizations you need can actually be done within the LaTeX include files specified in the metadata, without requiring XSLT. Check out some of the examples in the [MultiMarkdown Gallery] and in the LaTeX Support files for ideas of what can be done.

Compiling

If you want to compile this yourself, you do it in the same way that you would install peg-markdown for Windows. The instructions are on the peg-multimarkdown [wiki] (https://github.com/fletcher/peg-multimarkdown/wiki/Building-for-Windows). I was able to compile for Windows fairly easily using Ubuntu linux following those instructions. I have not tried to actually compile on a Windows machine.

Otherwise, see the section on [Linux] for further tips.

(For those who are interested, I actually created an EC2 instance on Amazon and installed the necessary software to compile. It was pretty easy and probably cost me $0.02...)

Linux

Basic compiling

Currently the only way to install MultiMarkdown on *nix machines is to compile it yourself. You need to have glib2 installed. For example, on ubuntu:

sudo apt-get install libglib2.0-dev

For other linux distributions, you will need to do something similar.

Once you have the libraries installed, you can either download the source from the downloads page, or (preferentially) you can use git:

git clone --recursive git://github.com/fletcher/peg-multimarkdown.git

At this point you can compile with:

make

Advanced compiling

One additional step to include if you use git to clone the source, is to run the update_submodules.sh script. This script basically runs two commands, that you can also run by hand:

git submodule init
git submodule update

Then, simply run make to compile the source. You can also run some test commands to verify that everything is working properly. Of note, it is normal to fail one test in the Markdown tests, but the others should pass. You can then install the binary and utility scripts wherever you like, though for consistency /usr/local/bin would probably be best.

make
make test
make mmdtest
make latextest

As above, if you intend to use XSLT, LaTeX, and the like, I recommend also installing the LaTeX Support files and MultiMarkdown Support.

FreeBSD

If you want to compile manually, you should be able to follow the directions for Linux above. However, apparently MultiMarkdown has been put in the ports tree, so you can also use:

cd /usr/ports/textproc/multimarkdown
make install

(I have not tested this myself, and cannot guarantee that it works properly.)