Introduction

Introduction

This document is a guide to understanding and using MultiMarkdown. It was created as a wiki, and thus was written by various contributors. Feel free to contribute your own improvements!

What is Markdown?

To understand what MultiMarkdown is, you first should be familiar with Markdown. The best description of what Markdown is comes from John Gruber's Markdown web site:

Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).

Thus, "Markdown" is two things: (1) a plain text formatting syntax; and (2) a software tool, written in Perl, that converts the plain text formatting to HTML. See the Syntax page for details pertaining to Markdown’s formatting syntax. You can try it out, right now, using the online Dingus.

The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. While Markdown’s syntax has been influenced by several existing text-to-HTML filters, the single biggest source of inspiration for Markdown’s syntax is the format of plain text email. --- John Gruber

A note on Plain Text Formatting

The value of Markdown is that it allows the writer to focus completely on the process of writing and not on formatting their text. Many "word processors" are actually programs that provide writing tools, but also text formatting, page layout, image handling, commenting and editing tools. However these tools obscure the original purpose of simply writing something.

Markdown and MultiMarkdown are not for everyone. But if you find yourself being frustrated by the hurdles most word processors create, using MultiMarkdown and plain text may be the solution you're looking for.

What is MultiMarkdown?

Markdown is great, but it lacked a few features that would allow it to work with documents, rather than just pieces of a web page.

I wrote MultiMarkdown in order to leverage Markdown's syntax, but to extend it to work with complete documents that could ultimately be converted from text into other formats, including complete XHTML documents, LaTeX, PDF, RTF, or even (shudder) Microsoft Word documents. These various formats are supported to varying degrees by various versions of MultiMarkdown and work differently on different operating systems. The two core output formats are XHTML and LaTeX (for now at least).

In addition to the ability to work with complete documents and conversion to other formats, the Markdown syntax was lacking a few things. Michel Fortin added a few additional syntax tools when writing PHP Markdown Extra. Some of his ideas were implemented and expanded on in MultiMarkdown, in addition to more features not available in other Markdown implementations. These features include tables, footnotes, citation support, image and link attributes, cross-references, math support, and more.

John Gruber may disagree with me, but I really did try to stick with his proclaimed vision whenever I added a new syntax format to MultiMarkdown. The quality that attracted me to Markdown the most was its clean format. Reading a plain text document written in Markdown is easy. It makes sense, and it looks like it was designed for people, not computers. To the extent possible, I tried to keep this same concept in mind when working on MultiMarkdown.

I may or may not have succeeded in this....

In the vein of Markdown's multiple definitions, you can think of MultiMarkdown as:

1. A program to convert plain text to XHTML (or LaTeX).

2. The syntax used in the plain text to describe how to convert it to XHTML

Where is this Guide Kept?

This User's Guide is designed to be viewed as a single XHTML document, or as a PDF after being processed by LaTeX. When processed by MultiMarkdown and combined as a single document, it will demonstrate many of the features that MultiMarkdown offers, and should be fairly easy to navigate.

The source text documents are actually stored in a wiki on Github so that the document can easily be worked on by anyone with a Github account:

https://github.com/fletcher/peg-multimarkdown/wiki/User's-Manual

Note: Currently, the Github wiki software supports Markdown, but not MultiMarkdown. This means that certain MultiMarkdown specific features will not work on the wiki, but will work when the source is processed by MultiMarkdown separately from the wiki.

You can download a copy of the source files using the instructions contained at the wiki itself. Additionally, the source is linked to from within the source project for MultiMarkdown in the documentation directory. If you download the source, you can can compile a copy of the documentation automatically with:

make docs

(This command requires perl to be installed --- maybe at some point I'll work on an alternative for Windows users without perl).