## Usage

### Basic Command Line Usage

First, verify that you have properly installed MultiMarkdown:

multimarkdown --version
multimarkdown --v


multimarkdown --help
multimarkdown --h


To convert a file to HTML:

multimarkdown file.txt


To save the HTML to a file

multimarkdown file.txt > file.html


To convert to a different format:

multimarkdown -t latex file.txt
multimarkdown -t epub file.txt


### Batch Mode

Batch mode allows you to convert one or more files in a single command, saving each file to a separate output file with a file extension based on the output format (e.g. .html or .tex). This will overwrite existing files.

multimarkdown -b file.txt file2.txt


### Transclusion Only

You can output to the mmd format to perform file transclusion and then output the raw MultiMarkdown (MMD) source before converting to another format:

multimarkdown -t mmd file.txt


### Convenience Scripts

There are several convenience scripts to batch convert to a specified format:

mmd file.txt
markdown file.txt		// Compatibility mode
mmd2epub file.txt
mmd2fodt file.txt
mmd2odt file.txt
mmd2opml file.txt
mmd2pdf file.txt		// Convert to LaTeX and process to PDF
mmd2tex file.txt


multimarkdown -f, multimarkdown --full
multimarkdown -s, multimarkdown --snippet


Control whether MultiMarkdown outputs a complete document or just a “snippet”. A snippet includes just the section of text included in the document. A full/complete document includes header information and other structure to form a complete HTML or LaTeX document, for example. Additionally, if metadata is included (with a few exceptions), MultiMarkdown will automatically produce a complete document.

multimarkdown -c, multimarkdown --compatibility


Compatibility mode forces MultiMarkdown to create HTML that matches the output of basic Markdown. In other words, it disables all the new features added in MultiMarkdown.

There are a few exceptions, however. The original Markdown.pl script used recursive regular expressions to perform parsing. This is very flexible (though error-prone), but is extremely slow. MultiMarkdown v6 has a much faster parser, but there is one key limitation – it parses in order and can’t look ahead indefinitely to see what might be coming up. The main situations where this occurs is in handling fenced code blocks (not a problem in compatibility mode, since they don’t exist in Markdown) and in handling raw HTML. For more information on this, see https://github.com/fletcher/MultiMarkdown-6/issues/135.

The other potential difference is that MultiMarkdown v6 has a smarter strong/emphasis parser than Markdown.pl – it better handles edge cases.

Because of these exceptions, there may be a few rare situations where the output generated by MultiMarkdown v6 does not match that by Markdown.pl. If you find what you believe to be a bug that doesn’t fit one of these situations, please let me know and I’ll take a look. The goal is to match the original Markdown output as much as possible, but not to match the many bugs that are contained in Markdown.pl.

multimarkdown --random


Normally MultiMarkdown assigns consecutive numbers to the identifiers used for footnotes, citations, etc. (e.g. 1, 2, 3, etc.) This means that you have a “blog-style” web site that shows multiple articles on the home page, and multiple stories have footnotes, the anchors will collide. The random option generates random anchor numbers to dramatically reduce the offs of a collision.

multimarkdown --unique


The unique option uses a similar random number generator to provide unique anchors (“labels”) for headers that do not have a manually specified label. This prevents every “Introduction” header in a textbook, for example, from having the identical label #introduction. This reduces validation errors in HTML, ePub, and LaTeX, and prevents collisions when using the {{TOC}} function.

multimarkdown --nosmart


Disable smart quotes (e.g. "foo" does not become “foo”).

multimarkdown --nolabels


Disables automatic generation of labels/anchors for headers.

multimarkdown --notransclude


Disables file transclusion that allows inserting the contents of a file inside another file. See the section on [File Transclusion] for more information.

multimarkdown --opml


Allows MultiMarkdown to read an OPML source file. Outline Processor Markup Language is an XML file format commonly used for outliners and mind mapping programs. MultiMarkdown can read/write to this format in addition to using regular plain text files.

multimarkdown --itmz


Similar to OPML, ITMZ is an outlining format specific to the iThoughts mind-mapping program. I added this format because:

1. iThoughts is my preferred mind-mapping tool

2. iThoughts supports OPML, but the support is (unfortunately) limited. I was unable to convince the author of the benefits of better read/write support for OPML.

4. Adding ITMZ support to MultiMarkdown allows me to do some interesting things in MultiMarkdown Composer, as well as in other workflows. (More to come on that.)

Though I reluctantly added support for this format to MultiMarkdown, I will not be adding support for a laundry list of other formats. Plain text and OPML should be enough. If the use of these outline file formats for MultiMarkdown (or regular Markdown) continues to gain traction, then hopefully other developers will include proper OPML support in their programs.

As an aside, the first use of this functionality came when I created an export plug-in for OmniOutliner that created a plain Markdown/MultiMarkdown text file when exporting from an Omnioutliner OPML file.

multimarkdown -t, multimarkdown --to=FORMAT


Specify the output format.

multimarkdown -o, multimarkdown --output=FILE


Specify the output file name.

multimarkdown -a, multimarkdown --accept
multimarkdown -r, multimarkdown --reject


Either accept or reject all proposed CriticMarkup changes contained within the document before processing. It basically allows you to output a “before” and an “after” version of a document containing edits. If neither option is used, MultiMarkdown attempts to show the edits in-line, but this is not always possible for poorly structured edits. See the section on Criticmarkup for more information.

multimarkdown -l, multimarkdown --lang=LANG


Localize language/smart quotes for en, es, de, fr, he, nl, sv. This can also be controlled via metadata.

multimarkdown -m, multimarkdown --metadata-keys


List all metadata keys contained in the document.

multimarkdown -e, multimarkdown --extract=KEY


Extract the value of a specified metadata key. This is useful for custom scripts, for example.