-
Notifications
You must be signed in to change notification settings - Fork 55
How do I use MultiMarkdown?
There are several ways to use MultiMarkdown, depending on your needs. You can
use the multimarkdown command line tool, you can use MultiMarkdown with
several applications that support it directly, or you can use a drag and drop
approach.
First, verify that you have properly installed MultiMarkdown:
multimarkdown -v
If you don't see a message telling you which version of MultiMarkdown is installed, check out Troubleshooting.
To learn more about the command line options to multimarkdown:
multimarkdown -h
Once you have properly installed MultiMarkdown:
multimarkdown file.txt
will convert the plain text file file.txt into XHTML output. To save the
results to a file:
multimarkdown file.txt > file.html
A shortcut to this is to use MultiMarkdown's batch mode, which will save the
output to the same base filename that is input, with the extension .html (or
.tex for LaTeX output):
multimarkdown -b file.txt
A benefit of batch mode is that you can process multiple files at once:
multimarkdown -b file1.txt file2.txt file3.txt
If you want to create LaTeX output instead of XHTML:
multimarkdown -t latex file.txt
There are also two convenience scripts included with MultiMarkdown:
mmd file.txt
mmd2tex file.txt
These scripts run MultiMarkdown in batch mode to generate XHTML or LaTeX files
respectively. These scripts are included with the Mac or Windows installers,
and are available for *nix in the scripts directory in the source project.
They are intended to be used as shortcuts for the most common command line
options.
There are several options when running MultiMarkdown from the command line.
multimarkdown -c, multimarkdown --compatibility
Compatibility mode causes MultiMarkdown to output XHTML that is compatible with that output from the original Markdown. This allows it to pass the original Markdown test suite. Syntax features that don't exist in regular Markdown will still be output using the regular MultiMarkdown output formatting.
multimarkdown -e "metakey", multimarkdown --extract "metakey"
The extract feature outputs the value of the specified metadata key. This is used in my convenience scripts to help choose the proper LaTeX output mode, and could be used in other circumstances as well.
multimarkdown -t html|latex|memoir|beamer
This options specified the format that MultiMarkdown outputs. The default is
html. If you use the LaTeX Mode metadata, then MultiMarkdown will
automatically choose memoir or beamer as directed without using these
command line options. Using that metadata will also allow the various
convenience scripts to choose the correct output format as well.
multimarkdown --process-html
This option tells MultiMarkdown to process the text included within HTML tags in the source document.
Other options are available by checking out multimarkdown --help-all, but
the ones listed above are the primary options.
MultiMarkdown version 2.0 had to first convert the source file to XHTML, and then applied XSLT files to convert to the final LaTeX format. Since MultiMarkdown 3.0 can create LaTeX directly, this approach is no longer necessary.
The one benefit of that approach, however, was that it became possible to perform a wide range of customizations on exactly how the LaTeX output was created by customizing the XSLT files.
If you install the Support files on Mac or Linux, you can still use the advanced XSLT method to generate LaTeX output. For the time being, this approach doesn't work with Windows, but it would be fairly easy to create a batch script or perl script to implement this feature on Windows.
Keep in mind, however, that because of the more advanced mechanism of handling LaTeX in MultiMarkdown 3.0, you can do a great deal of customization without needing to use an XSLT file.
The mmd2xslt script will convert a plain text file into LaTeX that is
virtually identical with that created by the regular LaTeX approach.
There are a few differences in the two approaches, however:
-
Once a MultiMarkdown file is converted to XHTML, it is impossible to tell whether the resulting HTML was generated by MultiMarkdown, or if it was included as raw XHTML within the source document. So either way, it will be converted to the analagous LaTeX syntax. The
multimarkdownbinary on its own will not convert XHTML into LaTeX. -
The whitespace that is generated will be different under certain circumstances. Typically, this will result in one extra or one fewer blank lines withe the XSLT approach. Generally this will not be an issue, but when used with
<!-- some comment -->it may cause a newline to be lost. -
The default XSLT recognizes
class="noxslt"when applied to XHTML entities, and will discard them from the output. -
An XSLT can only be applied to a complete XHTML document, not a "snippet". Therefore, if you want to use the XSLT method, your file must have metadata that triggers a complete document (i.e. any metadata except "quotes language" or "base header level").
I recommend that you become familiar with the "basic" approach to using MultiMarkdown before trying to experiment with XSLT. The basic approach is faster, and easier, and the results can still be customized quite a bit.
Then you can experiment with modifying XSLT to further customize your output as needed.
If you have XSLT files that you used in MultiMarkdown 2.0, you will likely need to modify them to recognize the XHTML output generated by MultiMarkdown 3.0. You can use the default XSLT files as a guide to what is different.
There are several applications that have built-in support for MultiMarkdown, or that can easily use it with a plug-in.
If you want to run MultiMarkdown from directly within TextMate, you should install my MultiMarkdown bundle. This is a modified version of the original Markdown bundle for TextMate that includes better support for MultiMarkdown.
This bundle will work with MultiMarkdown 2.0, or with MultiMarkdown 3.0 if you install the MultiMarkdown-Support files (available from the downloads page).
Scrivener is a great program for writers using Mac OS X. It includes built
in support for MultiMarkdown. If you want to use MultiMarkdown 3.0 with
Scrivener, you need to install the Support files in ~/Library/Application Support/MultiMarkdown. The MultiMarkdown-Support installer is available from
the downloads page and will install these files for you.
There is a set of applications forthcoming that easily allow you to use drag and drop to process MultiMarkdown files.
You can use the same command line approach with Windows as described previously. While there aren't drag and drop applications per se for the Windows system, there are two shortcuts included in the installer that will allow you to drop text files on them in the same manner.