Answers to common questions about MultiMarkdown. Contributions welcome!
NOTE: This section of the documentation is still quite a mess. Please feel free to contribute to fixing it up on the [wiki].
If you get this error:
/bin/bash: line 2: multimarkdown: command not found
then you need to set the path properly in your preferences to include /usr/local/bin as shown in the screenshot:
You must have permissions to access /usr/local/bin and /usr/local/lib to use MMD.
To fix, type: sudo chmod go+rx /usr/local and similarly for the sub folders.
Put in your administrator password and try multimarkdown -v again.
Under Windows XP, go to the location where you would like to place the shortcut, and then:
- right-click
- select "New->Shortcut"
- enter "multimarkdown" as the location of the item
- choose the desired name for the shortcut
- right-click on the new shortcut and select "Properties"
- you can then add any desired command-line options at the end of the "Target" property --- you should definitely include "-b" to enable batch mode. The others are up to you.
You are using an automated tool to create "complete" content. The tool is
adding the format: complete metadata for you, but you don't have any other
metadata in your document.
Start your document with a blank line to indicate that there is no more metadata.
This should only happen with tools designed for MultiMarkdown 2.0
In order to display non-ASCII characters, a "complete" HTML document is necessary --- a "snippet" doesn't work. Simply include some metadata to force complete document generation.
This is true for the QuickLook Generator as well.
LaTeX is a syntax for describing how to convert marked up plain text into high-quality, typeset documents. MultiMarkdown uses LaTeX to generate PDF's from your MMD document.
Of note, MultiMarkdown does not process LaTeX files for you. It generates them, and relies on you to convert the LaTeX into a PDF. The exact commands you need may vary, but I use the following sequence in my helper script to include all the features I use.
latexmk file.tex # This command will do most of the work
makeglossaries file.tex # process glossary entries if they exist
pdflatex file.tex # I found that sometimes an extra run
pdflatex file.tex # or two is needed
latexmk -c file.tex # clean up a bunch of the temp files
Anything placed in an HTML comment will be passed along unaltered - this can include raw LaTeX code. For example:
This is raw LaTeX: <!-- e^{i \cdot \pi} = -1 -->
will generate:
This is raw LaTeX: e^{i \cdot \pi} = -1
See the section on [MultiMarkdown and LaTeX] for more information.
First - the vast majority of the time, this is not really a MMD problem, but rather a LaTeX problem, or (honestly) user error. Very occasionally, there are instances where MMD produces invalid LaTeX output when given unusual input, but these are rare.
Check to make sure you have proper metadata configured to allow your LaTeX to compile. See sample documents from the [MultiMarkdown Gallery] for some examples of what metadata is required for various document types/
If you are having problems with a more "complicated" MMD tool (such as the
TextMate bundle, or the Drag and Drop versions), use the command line approach
when you are really having difficulties. See if your document will compile to
HTML using the multimarkdown command. Once you've got that working, try
moving on to LaTeX, and then a PDF (if that's your goal).
If that doesn't work, you need to track down the source of the error. The best approach is similar to the old program Conflict Catcher. Keep dividing your document into halves, and test each half. One half will likely compile without complaint, and the other won't. Take the problem half, and repeat this process until you are able to find the paragraph, sentence, word that causes the error.
Using a real text editor (e.g. TextMate), examine the trouble section and make sure to view the invisible characters, and look for something odd. If you can't do that, you can also delete the faulty sentence and retype it (don't copy and paste --- you'll simply replicate the problem).
If none of that fixes your problem, post the problem section to the MultiMarkdown Discussion List and you will likely find out what you're doing wrong. Or perhaps you found an error and I will fix it. ;)
MultiMarkdown 2.0 included a command to create a PDF "automagically" from a MultiMarkdown file. This led to a lot of confusion and questions from users who didn't understand what was going (e.g. that MMD creates a LaTeX file, and that pdflatex then creates the PDF).
MultiMarkdown 3.0 does not officially support the creation of a PDF. It supports the creation of a LaTeX file. You are then responsible for creating the PDF.
That said, there is a script mmd2pdf that runs some of those commands for
you. If you have trouble with it, you're on your own. Try running the
appropriate LaTeX commands in the Terminal by hand to create your PDF.
Your MMD source file might have created malformed XML in your FODT file. Try validating the XML (one handy way is to open the FODT file in Firefox). If you get an error, then note the line number, open the FODT file in a text editor to find where in your document the error occurred, and then adjust your MMD source file accordingly.
MultiMarkdown is designed to process a single document at a time, but sometimes it can be useful to split a longer document into multiple parts. For example, this User's Guide is split into multiple pages on a wiki, and then combined for processing with MultiMarkdown.
In the MMD-Support package, there
is a utility script mmd_merge that can stitch multiple text files together.
It reads an input file that describes which files need to be combined, in what
order, and at what "level". This allows you to ensure that header levels are
adjusted appropriately when the document is combined.
For example, the index.txt file used to combine this User's Guide is:
# User's guide #
metadata.txt
Introduction.md
How-do-I-install-MultiMarkdown?.md
How-do-I-use-MultiMarkdown?.md
How-do-I-create-a-MultiMarkdown-document?.md
How-do-I-customize-MultiMarkdown-Output?.md
MultiMarkdown-Output-Formats.md
What's-different-in-MultiMarkdown-3.0?.md
Known-Issues.md
FAQ.md
Acknowledgments.md
As you see above, I use a separate text file for storing metadata. Lines that
begin with # are considered comments.
If you want to indicate that a certain file should have it's header levels
increased, you can insert one or more tab characters before the filename. This
is analogous to changing the Base Header Level metadata for that file.
NOTE: mmd_merge is a Perl script, so it requires that you have Perl
installed in order to use it.
If you want to link to an image included in your document, you should define the image using the reference syntax. It must also be in it's own paragraph. Then create an explicit link to the label (lowercase, no spaces, no special characters):
This is an image
![Alt Text][image label].
[image label]: /path/to/image.png "This is a title"
And now a link the desired [image](#imagelabel).
Without getting too technical, you have to be careful when including multiple hyphens and specifying links or images by reference.
This is an ![image-1].
This is the same image, but looks different --- ![image--1].
This is a different image ![image---1].
[image-1]: file.png "This is used"
[image--1]: file2.png "This is ignored"
[image---1]: file3.png "This is used"
This is because - and -- are both converted to en-dash, whereas --- is
an em-dash.
Please see [How do I install MultiMarkdown?].
The Mac installer for MultiMarkdown installs the following files:
- /usr/local/bin/multimarkdown
- /usr/local/bin/mmd
- /usr/local/bin/mmd2odf
- /usr/local/bin/mmd2opml
- /usr/local/bin/mmd2pdf
- /usr/local/bin/mmd2tex
(BTW, please don't waste your time trying to uninstall MMD if this isn't making any sense to you. The files add up to less than 500k or so, and don't do anything if you're not using them. So it's really not worth more than 30 seconds of your time to try and delete them.)
The Windows installer includes an uninstaller.
For Linux, simply remove the files from wherever you put them.
The syntax of MultiMarkdown can be a challenge for beginners especially when it comes to using Table and Link syntax. The challenge comes in understanding how it looks after the conversion.
The official MultiMarkdown text editor for Mac is MultiMarkdown Composer (http://multimarkdown.com/), distributed by MultiMarkdown Software, LLC on the Mac App Store. MultiMarkdown Composer is a text editor for Mac that is designed from the ground up around the MultiMarkdown syntax. It is designed to make writing in MultiMarkdown even easier than it already is, with automatic syntax highlighting, built in previews, easy export to any format that is supported by MultiMarkdown, and more!
For Mac users, you can download a free program NValt (http://brettterpstra.com/code/) that contains a preview mode. Thus, you can enter your markdown with a dynamic preview window to show how the formatting appears. I've found this useful until I was comfortable with the syntax.
Note also that MultiMarkdown can also be installed to MarsEdit (http://red-sweater.com/marsedit/) which also has a preview mode. This is even more effective for for bloggers as it will handle inline image upload to most popular blog software and display the interpreted output of your MMD syntax.
If you're interested in web based learning, you may want to try http://peg.gd/ which provides a web site for writing in Markdown syntax and display. You can also save the pages for forwarding to other people.
For the reverse requirement, you can visit http://heckyesmarkdown.com/ which will attempt to take a given HTML Page and convert it into Markdown, usually with good accuracy.
There are a number of programs available for use on the iPhone and iPad that support regular Markdown, but not MultiMarkdown (yet!).
Elements is a iPhone / iPad app that also has a markdown preview mode. Second Gear has also made MarkdownMail which is simpler, but also very usable for learning Markdown.
Textastic is a syntax highlighting text editor for the iPad that includes a preview mode for Markdown. It will even preview MathJax equations if you include the proper metadata and a working MathJax installation!
Now that MultiMarkdown is available in C (as of version 3.0), I would like to work on modifying it to work with iOS.
First, check some basics:
- are you using MultiMarkdown 2.0, or 3.0?
- are you using the latest release of your version?
- if you are using an application (Scrivener, TextMate, etc) does MultiMarkdown work from the command line?
- if you're using LaTeX, did you install the proper support files?
- did you read the User's Manual? (Yes --- I hate manuals too, but some aspects of MultiMarkdown can be rather complex, and that's where most questions come up)
- is this a known issue on [github] (https://github.com/fletcher/peg-multimarkdown/issues), or the [discussion list] (http://groups.google.com/group/multimarkdown/)?
If you're still having a problem, you first have to figure out what sort of error you're having:
-
The source document crashes multimarkdown --- this is very rare and can be confirmed by trying to convert text to HTML. Use the "[Divide and Conquer]" approach to find the problem portion of the document and send it to the discussion list.
-
You successfully generate LaTeX, but can't compile it --- see the section on troubleshooting [LaTeX][LaTeX won't compile] above.
-
You successfully generate a document, but it won't open properly (this generally happens with OpenDocument, but could be other formats) --- use the "[Divide and Conquer]" approach to find the problem portion, and send it to the discussion list.
-
The output you get doesn't match what you were expecting --- read the pertinent section of the manual, and compare your results against some of the sample documents. Make sure your syntax usage is correct. If you're still having trouble, send an email to the discussion list.
If you are sending an error report to the discussion list, please be sure to do the following:
- narrow down the problem to the smallest example that replicates the issue
- be sure to include your input, the output you received, and the output you expected to get
- if you're convinced this is an issue with MultiMarkdown, use the issue tracker on github, otherwise the [discussion list] (http://groups.google.com/group/multimarkdown/).
When you have a longer document that MultiMarkdown can't successfully process, it is helpful to narrow down the actual source of the problem. I recommend that you recursively split the document into halves until you reach the source of the issue. I also call this technique "Divide and Conquer".
Basically, divide your document into two halves and try to process each one separately. If one half works, and the other doesn't, the problem is likely in the half that won't compile. Continue recursively dividing the problem piece in half, until you narrow in on the actual problem.
Keep in mind that some parts of the document would potentially need to be included in both halves for proper testing --- the metadata, and the definition of any images or links by reference, for example.
Obviously, if an error requires two pieces of the document to occur, and one piece is in the beginning and the other is at the end, this approach might fail to localize the problem. So, it's not perfect, but is quite useful.
The MultiMarkdown web site describes various ways to get help.
The MultiMarkdown web site describes various ways you support or contribute to the MultiMarkdown project.
Thanks for thinking about it!!
Several users have written with suggestions for additional syntax for tables in order to allow cells to span multiple rows, to allow the MMD source for a single table row to span multiple text rows, etc.
My concern here is that the table should be easily understood in plain text, without too much markup. Ideally, there would be no markup, but it's just too complicated to have MMD figure out what the layout means.
I welcome suggestions, but I plan to be somewhat strict on this one.... And remember, for complex tables you can always enter the raw HTML.
This is less likely to happen, but it seems that adding some sort of basic syntax to manage forms would be pretty easy, and not very intrusive. Something like:
Please check all that apply:
[ ] Option A
[ ] Option B
[ ] Option C
Please choose one of the following:
( ) Option A
( ) Option B
( ) Option C
Please enter your first name:
[_______________________]
The idea would be to allow you to easily enter the necessary fields for a form, but not have to be concerned with the HTML nonsense.... As always, input welcome.
First, my goal with MultiMarkdown is not to continue to add scores of features. More is not always better.
If there is a feature that you can't live without, and you are interested in submitting your idea, think through the following:
-
Can your idea be done with the existing setup --- for example, using XSLT or a quick post-processing script to convert the default output to the output you desire?
-
Does the raw source you are proposing look natural to a human reader? The less markup the better --- the raw MultiMarkdown should look like something written by and for people, not for a computer.
-
How many people need this feature? MultiMarkdown has now been around for quite a while --- why hasn't someone else already requested this feature if it's so important?
If you feel your idea should be included in MultiMarkdown, then send it to the discussion list and I will certainly review it.
A PEG, or [Parsing Expression Grammar] (http://en.wikipedia.org/wiki/Parsing_expression_grammar) is a method of describing a formal grammar to parse an input language. John MacFarlane used a PEG to create his peg-markdown. I then modified his work to create MultiMarkdown 3.0.
First --- RTF is really an inferior document format. A given RTF document will give very different appearances when opened with different applications, or even in the same application on different operating systems. Apple's implementation of RTF is very different from Microsoft's, which is different from that of everyone else. It's hard to take RTF seriously as a document format when it seems to be handled differently everywhere you look.
Ironically, MultiMarkdown never really had RTF support to begin with. The
initial approach to generating RTF output was to convert to HTML, and then use
Apple's textutil command to convert to RTF. This can still be done via the
terminal, or simply use TextEdit to open the HTML and then save as RTF ---
this effectively does the same thing, except that this approach can also
handle images.
A second approach was started, but never completed --- the xhtml2rtf.xslt
file was used to convert HTML to RTF via an XSL stylesheet. This approach was
never finished, but could also be updated to work with MMD 3 generated HTML
output by anyone who is interested
Because of all this, RTF "support" is no longer included with MMD. You can
easily modify a shell script to pipe the HTML command through the textutil -convert rtf -stdout command and save to the desired filename, just like in
MMD 2.0. But an approach that gives better results is to use the Flat
OpenDocument format instead. This can be opened in LibreOffice or OpenOffice,
and then saved to a large variety of document formats.
A better approach might be to stick with the .fodt format, or the more
common version --- .odt. But that's more of a "political" opinion than a
technical one.
Finally, I have offered on numerous occasions to assist if anyone steps forward to implement RTF support. No takers so far.
That said, MultiMarkdown Composer uses Apple's system calls to convert HTML to RTF directly (like textutil above). The results are not always great, but it's easy to use.