Title: MultiMarkdown guide
Author: Tim van Werkhoven
Email: timvanwerkhoven@gmail.com
Date: 20121224
CSS: /Users/tim/.mdqlstyle.css
URL: https://gist.github.com/4473492
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.
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.
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.
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.
To markup a document, follow the MMD syntax.
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.
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 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.
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.
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).