MultiMarkdown

• Intro
• Features
• Download
• Install
• Use
• Help

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
• FreeBSD

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 install 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

On the Mac, you can choose from using an installer to install the program and required library 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!

You can also install MultiMarkdown with the package manager [MacPorts] with the following command:

sudo port install multimarkdown

Or using homebrew:

brew install multimarkdown

NOTE: I don’t maintain either of these ports/packages and can’t vouch that they are up to date or working properly.

If you don’t know what any of that means, just grab the installer.

If you want to compile for yourself, be sure you have the Developer Tools installed, and then follow the directions for Linux.

If you want to make your own installer, you can use the make mac-installer command after compiling the multimarkdown binary itself.

Windows

Basic

The easiest way to get peg-multimarkdown running on Windows is to download 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 multimarkdown binary, as well as several convenience scripts are installed for use from the command line.

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. 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.

As a shortcut, if running on a linux machine you can use:

make windows

This creates the multimarkdown.exe binary. You can then install this manually.

The make win-installer command is what I use to package up the BitRock installer into a zipfile. You probably won’t need it.

Linux

Basic compiling

You can either download the source from [peg-multimarkdown], or (preferentially) you can use git:

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

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 wherever you like.

make

Advanced compiling

One additional step to include if you use git to clone the source, and if you have Perl installed is to run the update_submodules.sh script to ensure that the submodule configurations in .git/config have the proper URL format, e.g.:

[submodule "Support"]
    url = git://github.com/fletcher/MMD-Support.git

instead of:

[submodule "Support"]
    url = git@github.com:fletcher/MMD-Support.git

If the update_submodules.sh script won’t run you can make the changes by hand, and then run git submodule update to ensure you have the latest submodule source.

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 mmd-test
make latex-test
make compat-test

NOTE As of version 3.2, the tests including obfuscated email addresses will also fail due to a change in how random numbers are generated.

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

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.)