Title: MultiMarkdown guide
Author: Tim van Werkhoven
Email: [email protected]
Date: 20121224
CSS: /Users/tim/.mdqlstyle.css
URL: https://gist.github.com/4473492

Intro

The multimarkdown documetation is a little confusing, so here's an attempt to document some features that I found tricky to find.

I will abbreviate MultiMarkdown to MMD in the remainder of this document.

Getting MultiMarkdown

Core program

Get MMD and the extensions from github. Install both using the provided packages.

N.B. Note that the main MMD package only installs the binaries!

N.B. The extensions are installed to ~/Library/Application Support/MultiMarkdown, make sure to add that to your PATH! Symlinking binaries in /usr/local/bin (or somewhere else) apparently does not work due to hardcoded path-dependencies on support files.

XSLT files

The XSLT files are not installed by default. Get these from github.

Install these anywhere you like, but ~/Library/Application Support/MultiMarkdown/XSLT/ is a nice spot.

Quicklook plugin

To view MMD documents formatted in Quick Look (for OS X), you can use MMD-QuickLook which is a fork of Fletcher's Quicklook plugin but adds some CSS styling and customisation.

Using MultiMarkdown

Syntax

To markup a document, follow the MMD syntax.

Generating output

To format a MMD file to HTML, use:

multimarkdown -o html input.md > output.html

which is the same as

multimarkdown -b input.md mmd input.md

N.B. mmd is not an alias for multimarkdown, but calls multimarkdown -b for all files provided.

Adding CSS

The MMD-QuickLook plugin listed above comes with some CSS files. To use these, use the header CSS, like:

CSS:         ./path/to/style.css

The style file should be absolute, or relative to the output HTML document.

Adding XSLT TOC

Adding a table of contents can be done using XSLT files, (see [XSLT files]). We post-process the XHTML file with xsltproc to add the TOC:

multimarkdown input.md | xsltproc -nonet -novalid -o output.html ./xhtml-toc-h1.xslt -

where ./xhtml-toc-h1.xslt is the XSLT file we want to use. This file can be linked to from the md file using the XHTML XSLT header, like:

XHTML XSLT:  ./xhtml-toc-h1.xslt

Then we can read out this header with

multimarkdown -e 'xhtml xslt' *md

and automate the command to use this file (adding globbing in the meantime):

multimarkdown *md | xsltproc -nonet -novalid -o $(ls *md).html $(multimarkdown -e 'xhtml xslt' *md) -

N.B. This assumes there is only one md file in the working directory.

Converting to PDF

To generate a PDF from the HTML file, I use the Webkit engine in through wkhtmltopdf.

wkhtmltopdf --page-size A4 $(ls *md).html $(ls *md).pdf

--page-size can be tuned to your liking.

Vector images

PDF viewers and browsers have almost none-overlapping image support, browsers support mostly bitmapped images, while vector graphics are preferable for PDF files due to the higher resolution.

The trade-off I'm using are SVG images, which works OK. To convert PDF to SVG I use pdf2svg using the Cairo and Poppler libraries. To convert all files:

for pdf in *.pdf; do test ! -f $pdf.svg && pdf2svg $pdf $pdf.svg; done

which also tests if the SVG file does not already exist, speeding up conversion.

To generate only bitmapped images, use

for pdf in *.pdf; do test ! -f $pdf.png && convert -density 150 $pdf $pdf.png; done

To replace all image files in a MMD document, use sed:

sed -i bak 's/\.pdf\.svg/\.pdf\.png/g' *md
sed -i bak 's/\.pdf\.png/\.pdf\.svg/g' *md

such that you can choose PNG files for HTML documents (run the first command) and SVG images for PDF (run the second command).

tvwerkhoven/MultiMarkdown_guide.md