Title: MultiMarkdown 4 ReadMe
Author: Fletcher T. Penney
Base Header Level: 2
Markdown is a simple markup language used to convert plain text into HTML.
MultiMarkdown is a derivative of Markdown that adds new syntax features, such as footnotes, tables, and metadata. Additionally, it offers mechanisms to convert plain text into LaTeX in addition to HTML.
MultiMarkdown started as a Perl script, which was modified from the original Markdown.pl.
MultiMarkdown v3 (aka 'peg-multimarkdown') was based on John MacFarlane's peg-markdown. It used a parsing expression grammar (PEG), and was written in C in order to compile on almost any operating system. Thanks to work by Daniel Jalkut, MMD v3 was built so that it didn't have any external library requirements.
MultiMarkdown v4 is basically a complete rewrite of v3. It uses the same basic PEG for parsing (Multi)Markdown text, but otherwise is almost completely rebuilt:
- The code is designed to be easier to maintain --- it's divided into separate files on a more logical structure
- All memory leaks (to my knowledge) have been fixed
- greg is used instead of peg/leg to create the parser --- this allows the parser to be thread-safe
- The test suite has been modified to account for several improvements. MMD should fail one of the basic Markdown tests (see peg-markdown for more information).
- Command line options are slightly different.
You can compile for yourself, or download a precompiled binary from the downloads page.
- Download the source from the github web site using
git git submodule initand thengit submodule updateto downloadgregand the test suite- Run
maketo compile. - Run
make test-all | lessto verify that the build is correct. As mentioned, one of the tests is expected to fail; the rest should pass on all systems. - Run
sudo make installand (optionally)sudo make install-scriptsto installmultimarkdownand the helper scripts.
Once installed, you simply do something like the following:
-
multimarkdown file.txt--- process text into HTML. -
multimarkdown -c file.txt--- use a compatibility mode that emulates the original Markdown. -
multimarkdown -t latex file.txt--- output the results as LaTeX instead of HTML. This can then be processed into a PDF if you have LaTeX installed. You can further specify theLaTeX Modemetadata to customize output for compatibility withmemoirorbeamerclasses. -
multimarkdown -t odf file.txt--- output the results as an OpenDocument Text Flat XML file. Does require the plugin be installed in your copy of OpenOffice, which is available at the peg-multimarkdown-downloads page. LibreOffice includes this plugin by default. -
multimarkdown -t opml file.txt--- convert the MMD text file to an MMD OPML file, compatible with OmniOutliner and certain other outlining and mind-mapping programs (including iThoughts and iThoughtsHD). -
multimarkdown -h--- display help and additional options. -
multimarkdown -b *.txt----bor--batchmode can process multiple files at once, convertingfile.txttofile.htmlorfile.texas directed. Using this feature, you can convert a directory of MultiMarkdown text files into HTML files, or LaTeX files with a single command without having to specify the output files manually. CAUTION: This will overwrite existing files with thehtmlortexextension, so use with caution.
If you get an error that greg fails to build try touch greg/greg.c. I had an issue where the timestamp on that file might have been too old, which caused the build to fail.
Charles R. Cowan (https://github.com/crcowan) added support for conversion to LyX. Support for this should be considered to be in alpha/beta, and is not guaranteed. Issues related to LyX can be added to the MultiMarkdown issues page on github, but will need to be answered by Charles. I am happy to include this code in the main MMD repo, but since I don't use LyX I can't support it myself. If this arrangement becomes a problem, then LyX support can be removed and it can be kept as a separate fork.
To get more information about MultiMarkdown, check out the website or User's Guide.