Yukki Base Formatting: MultiMarkdown

Yukki Base Formatting: MultiMarkdown

Most of the syntax is a format called Markdown. More specifically, it supports MultiMarkdown extended syntax.

Much of this documentation is copied from those places.

Markdown Syntax

Inline HTML

Markdown's syntax is intended for one purpose: to be used as a format for writing for the web.

Markdown is not a replacement for HTML, or even close to it. Its syntax is very small, corresponding only to a very small subset of HTML tags. The idea is not to create a syntax that makes it easier to insert HTML tags. In my opinion, HTML tags are already easy to insert. The idea for Markdown is to make it easy to read, write, and edit prose. HTML is a publishing format; Markdown is a writing format. Thus, Markdown's formatting syntax only addresses issues that can be conveyed in plain text.

For any markup that is not covered by Markdown's syntax, you simply use HTML itself. There's no need to preface it or delimit it to indicate that you're switching from Markdown to HTML; you just use the tags.

The only restrictions are that block-level HTML elements -- e.g. <div>, <table>, <pre>, <p>, etc. -- must be separated from surrounding content by blank lines, and the start and end tags of the block should not be indented with tabs or spaces. Markdown is smart enough not to add extra (unwanted) <p> tags around HTML block-level tags.

For example, to add an HTML table to a Markdown article:

This is a regular paragraph.

<table> 
    <tr> 
        <td>Foo</td> 
    </tr> 
</table> 

This is another regular paragraph.

Note that Markdown formatting syntax is not processed within block-level HTML tags. E.g., you can't use Markdown-style *emphasis* inside an HTML block.

Span-level HTML tags -- e.g. <span>, <cite>, or <del> -- can be used anywhere in a Markdown paragraph, list item, or header. If you want, you can even use HTML tags instead of Markdown formatting; e.g. if you'd prefer to use HTML <a> or <img> tags instead of Markdown's link or image syntax, go right ahead.

Unlike block-level HTML tags, Markdown syntax is processed within span-level tags.

Automatic Escaping for Special Characters

In HTML, there are two characters that demand special treatment: < and &. Left angle brackets are used to start tags; ampersands are used to denote HTML entities. If you want to use them as literal characters, you must escape them as entities, e.g. &lt;, and &amp;.

Ampersands in particular are bedeviling for web writers. If you want to write about 'AT&T', you need to write 'AT&amp;T'. You even need to escape ampersands within URLs. Thus, if you want to link to:

http://images.google.com/images?num=30&q=larry+bird

you need to encode the URL as:

http://images.google.com/images?num=30&amp;q=larry+bird

in your anchor tag href attribute. Needless to say, this is easy to forget, and is probably the single most common source of HTML validation errors in otherwise well-marked-up web sites.

Markdown allows you to use these characters naturally, taking care of all the necessary escaping for you. If you use an ampersand as part of an HTML entity, it remains unchanged; otherwise it will be translated into &amp;.

So, if you want to include a copyright symbol in your article, you can write:

&copy;

and Markdown will leave it alone. But if you write:

AT&T

Markdown will translate it to:

AT&amp;T

Similarly, because Markdown supports inline HTML, if you use angle brackets as delimiters for HTML tags, Markdown will treat them as such. But if you write:

4 < 5

Markdown will translate it to:

4 &lt; 5

However, inside Markdown code spans and blocks, angle brackets and ampersands are always encoded automatically. This makes it easy to use Markdown to write about HTML code. (As opposed to raw HTML, which is a terrible format for writing about HTML syntax, because every single < and & in your example code needs to be escaped.)

Block Elements

Paragraphs and Line Breaks

A paragraph is simply one or more consecutive lines of text, separated by one or more blank lines. (A blank line is any line that looks like a blank line -- a line containing nothing but spaces or tabs is considered blank.) Normal paragraphs should not be indented with spaces or tabs.

The implication of the "one or more consecutive lines of text" rule is that Markdown supports "hard-wrapped" text paragraphs. This differs significantly from most other text-to-HTML formatters (including Movable Type's "Convert Line Breaks" option) which translate every line break character in a paragraph into a <br /> tag.

When you do want to insert a <br /> break tag using Markdown, you end a line with two or more spaces, then type return.

Yes, this takes a tad more effort to create a <br />, but a simplistic "every line break is a <br />" rule wouldn't work for Markdown. Markdown's email-style blockquoting and multi-paragraph list items work best -- and look better -- when you format them with hard breaks.

Headers

Markdown supports two styles of headers, Setext and atx.

Setext-style headers are "underlined" using equal signs (for first-level headers) and dashes (for second-level headers). For example:

This is an H1
=============

This is an H2
-------------

Any number of underlining ='s or -'s will work.

Atx-style headers use 1-6 hash characters at the start of the line, corresponding to header levels 1-6. For example:

# This is an H1

## This is an H2

###### This is an H6

Optionally, you may "close" atx-style headers. This is purely cosmetic -- you can use this if you think it looks better. The closing hashes don't even need to match the number of hashes used to open the header. (The number of opening hashes determines the header level.) :

# This is an H1 #

## This is an H2 ##

### This is an H3 ######

Blockquotes

Markdown uses email-style > characters for blockquoting. If you're familiar with quoting passages of text in an email message, then you know how to create a blockquote in Markdown. It looks best if you hard wrap the text and put a > before every line:

> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
> 
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
> id sem consectetuer libero luctus adipiscing.

Markdown allows you to be lazy and only put the > before the first line of a hard-wrapped paragraph:

> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
id sem consectetuer libero luctus adipiscing.

Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by adding additional levels of >:

> This is the first level of quoting.
>
> > This is nested blockquote.
>
> Back to the first level.

Blockquotes can contain other Markdown elements, including headers, lists, and code blocks:

> ## This is a header.
> 
> 1.   This is the first list item.
> 2.   This is the second list item.
> 
> Here's some example code:
> 
>     return shell_exec("echo $input | $markdown_script");

Any decent text editor should make email-style quoting easy. For example, with BBEdit, you can make a selection and choose Increase Quote Level from the Text menu.

Lists

Markdown supports ordered (numbered) and unordered (bulleted) lists.

Unordered lists use asterisks, pluses, and hyphens -- interchangably -- as list markers:

*   Red
*   Green
*   Blue

is equivalent to:

+   Red
+   Green
+   Blue

and:

-   Red
-   Green
-   Blue

Ordered lists use numbers followed by periods:

1.  Bird
2.  McHale
3.  Parish

It's important to note that the actual numbers you use to mark the list have no effect on the HTML output Markdown produces. The HTML Markdown produces from the above list is:

<ol> 
<li>Bird</li> 
<li>McHale</li> 
<li>Parish</li> 
</ol>

If you instead wrote the list in Markdown like this:

1.  Bird
1.  McHale
1.  Parish

or even:

3. Bird
1. McHale
8. Parish

you'd get the exact same HTML output. The point is, if you want to, you can use ordinal numbers in your ordered Markdown lists, so that the numbers in your source match the numbers in your published HTML. But if you want to be lazy, you don't have to.

If you do use lazy list numbering, however, you should still start the list with the number 1. At some point in the future, Markdown may support starting ordered lists at an arbitrary number.

List markers typically start at the left margin, but may be indented by up to three spaces. List markers must be followed by one or more spaces or a tab.

To make lists look nice, you can wrap items with hanging indents:

*   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
    Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
    viverra nec, fringilla in, laoreet vitae, risus.
*   Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
    Suspendisse id sem consectetuer libero luctus adipiscing.

But if you want to be lazy, you don't have to:

*   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
viverra nec, fringilla in, laoreet vitae, risus.
*   Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
Suspendisse id sem consectetuer libero luctus adipiscing.

If list items are separated by blank lines, Markdown will wrap the items in <p> tags in the HTML output. For example, this input:

*   Bird
*   Magic

will turn into:

<ul> 
<li>Bird</li> 
<li>Magic</li> 
</ul>

But this:

*   Bird

*   Magic

will turn into:

<ul> 
<li><p>Bird</p></li> 
<li><p>Magic</p></li> 
</ul>

List items may consist of multiple paragraphs. Each subsequent paragraph in a list item must be indented by either 4 spaces or one tab:

1.  This is a list item with two paragraphs. Lorem ipsum dolor
    sit amet, consectetuer adipiscing elit. Aliquam hendrerit
    mi posuere lectus.

    Vestibulum enim wisi, viverra nec, fringilla in, laoreet
    vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
    sit amet velit.

2.  Suspendisse id sem consectetuer libero luctus adipiscing.

It looks nice if you indent every line of the subsequent paragraphs, but here again, Markdown will allow you to be lazy:

*   This is a list item with two paragraphs.

    This is the second paragraph in the list item. You're
only required to indent the first line. Lorem ipsum dolor
sit amet, consectetuer adipiscing elit.

*   Another item in the same list.

To put a blockquote within a list item, the blockquote's > delimiters need to be indented:

*   A list item with a blockquote:

    > This is a blockquote
    > inside a list item.

To put a code block within a list item, the code block needs to be indented twice -- 8 spaces or two tabs:

*   A list item with a code block:

        <code goes here>

It's worth noting that it's possible to trigger an ordered list by accident, by writing something like this:

1986. What a great season.

In other words, a number-period-space sequence at the beginning of a line. To avoid this, you can backslash-escape the period:

1986\. What a great season.

Code Blocks

Pre-formatted code blocks are used for writing about programming or markup source code. Rather than forming normal paragraphs, the lines of a code block are interpreted literally. Markdown wraps a code block in both <pre> and <code> tags.

To produce a code block in Markdown, simply indent every line of the block by at least 4 spaces or 1 tab. For example, given this input:

This is a normal paragraph:

    This is a code block.

Markdown will generate:

<p>This is a normal paragraph:</p> 

<pre><code>This is a code block.
</code></pre>

One level of indentation -- 4 spaces or 1 tab -- is removed from each line of the code block. For example, this:

Here is an example of AppleScript:

    tell application "Foo"
        beep
    end tell

will turn into:

<p>Here is an example of AppleScript:</p> 

<pre><code>tell application "Foo"
    beep
end tell
</code></pre>

A code block continues until it reaches a line that is not indented (or the end of the article).

Within a code block, ampersands (&) and angle brackets (< and >) are automatically converted into HTML entities. This makes it very easy to include example HTML source code using Markdown -- just paste it and indent it, and Markdown will handle the hassle of encoding the ampersands and angle brackets. For example, this:

    <div class="footer"> 
        &copy; 2004 Foo Corporation
    </div>

will turn into:

<pre><code>&lt;div class="footer"&gt;
    &amp;copy; 2004 Foo Corporation
&lt;/div&gt;
</code></pre>

Regular Markdown syntax is not processed within code blocks. E.g., asterisks are just literal asterisks within a code block. This means it's also easy to use Markdown to write about Markdown's own syntax.

Horizontal Rules

You can produce a horizontal rule tag (<hr />) by placing three or more hyphens, asterisks, or underscores on a line by themselves. If you wish, you may use spaces between the hyphens or asterisks. Each of the following lines will produce a horizontal rule:

* * *

***

*****

- - -

---------------------------------------

Span Elements

Links

Markdown supports two style of links: inline and reference.

In both styles, the link text is delimited by [square brackets].

To create an inline link, use a set of regular parentheses immediately after the link text's closing square bracket. Inside the parentheses, put the URL where you want the link to point, along with an optional title for the link, surrounded in quotes. For example:

This is [an example](http://example.com/ "Title") inline link.

[This link](http://example.net/) has no title attribute.

Will produce:

<p>This is <a href="http://example.com/" title="Title"> 
an example</a> inline link.</p> 

<p><a href="http://example.net/">This link</a> has no
title attribute.</p>

If you're referring to a local resource on the same server, you can use relative paths:

See my [About](/about/) page for details.

Reference-style links use a second set of square brackets, inside which you place a label of your choosing to identify the link:

This is [an example][id] reference-style link.

You can optionally use a space to separate the sets of brackets:

This is [an example] [id] reference-style link.

Then, anywhere in the document, you define your link label like this, on a line by itself:

[id]: http://example.com/  "Optional Title Here"

That is:

  • Square brackets containing the link identifier (optionally indented from the left margin using up to three spaces);
  • followed by a colon;
  • followed by one or more spaces (or tabs);
  • followed by the URL for the link;
  • optionally followed by a title attribute for the link, enclosed in double or single quotes, or enclosed in parentheses.

The following three link definitions are equivalent:

[foo]: http://example.com/  "Optional Title Here"
[foo]: http://example.com/  'Optional Title Here'
[foo]: http://example.com/  (Optional Title Here)

Note: There is a known bug in Markdown.pl 1.0.1 which prevents single quotes from being used to delimit link titles.

The link URL may, optionally, be surrounded by angle brackets:

[id]: <http://example.com/>  "Optional Title Here"

You can put the title attribute on the next line and use extra spaces or tabs for padding, which tends to look better with longer URLs:

[id]: http://example.com/longish/path/to/resource/here
    "Optional Title Here"

Link definitions are only used for creating links during Markdown processing, and are stripped from your document in the HTML output.

Link definition names may consist of letters, numbers, spaces, and punctuation -- but they are not case sensitive. E.g. these two links:

[link text][a]
[link text][A]

are equivalent.

The implicit link name shortcut allows you to omit the name of the link, in which case the link text itself is used as the name. Just use an empty set of square brackets -- e.g., to link the word "Google" to the google.com web site, you could simply write:

[Google][]

And then define the link:

[Google]: http://google.com/

Because link names may contain spaces, this shortcut even works for multiple words in the link text:

Visit [Daring Fireball][] for more information.

And then define the link:

[Daring Fireball]: http://daringfireball.net/

Link definitions can be placed anywhere in your Markdown document. I tend to put them immediately after each paragraph in which they're used, but if you want, you can put them all at the end of your document, sort of like footnotes.

Here's an example of reference links in action:

I get 10 times more traffic from [Google] [1] than from
[Yahoo] [2] or [MSN] [3].

  [1]: http://google.com/        "Google"
  [2]: http://search.yahoo.com/  "Yahoo Search"
  [3]: http://search.msn.com/    "MSN Search"

Using the implicit link name shortcut, you could instead write:

I get 10 times more traffic from [Google][] than from
[Yahoo][] or [MSN][].

  [google]: http://google.com/        "Google"
  [yahoo]:  http://search.yahoo.com/  "Yahoo Search"
  [msn]:    http://search.msn.com/    "MSN Search"

Both of the above examples will produce the following HTML output:

<p>I get 10 times more traffic from <a href="http://google.com/"
title="Google">Google</a> than from
<a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a> 
or <a href="http://search.msn.com/" title="MSN Search">MSN</a>.</p>

For comparison, here is the same paragraph written using Markdown's inline link style:

I get 10 times more traffic from [Google](http://google.com/ "Google")
than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
[MSN](http://search.msn.com/ "MSN Search").

The point of reference-style links is not that they're easier to write. The point is that with reference-style links, your document source is vastly more readable. Compare the above examples: using reference-style links, the paragraph itself is only 81 characters long; with inline-style links, it's 176 characters; and as raw HTML, it's 234 characters. In the raw HTML, there's more markup than there is text.

With Markdown's reference-style links, a source document much more closely resembles the final output, as rendered in a browser. By allowing you to move the markup-related metadata out of the paragraph, you can add links without interrupting the narrative flow of your prose.

Emphasis

Markdown treats asterisks (*) and underscores (_) as indicators of emphasis. Text wrapped with one * or _ will be wrapped with an HTML <em> tag; double *'s or _'s will be wrapped with an HTML <strong> tag. E.g., this input:

*single asterisks*

_single underscores_

**double asterisks**

__double underscores__

will produce:

<em>single asterisks</em> 

<em>single underscores</em> 

<strong>double asterisks</strong> 

<strong>double underscores</strong>

You can use whichever style you prefer; the lone restriction is that the same character must be used to open and close an emphasis span.

Emphasis can be used in the middle of a word:

un*frigging*believable

But if you surround an * or _ with spaces, it'll be treated as a literal asterisk or underscore.

To produce a literal asterisk or underscore at a position where it would otherwise be used as an emphasis delimiter, you can backslash escape it:

\*this text is surrounded by literal asterisks\*

Code

To indicate a span of code, wrap it with backtick quotes (`). Unlike a pre-formatted code block, a code span indicates code within a normal paragraph. For example:

Use the `printf()` function.

will produce:

<p>Use the <code>printf()</code> function.</p>

To include a literal backtick character within a code span, you can use multiple backticks as the opening and closing delimiters:

``There is a literal backtick (`) here.``

which will produce this:

<p><code>There is a literal backtick (`) here.</code></p>

The backtick delimiters surrounding a code span may include spaces -- one after the opening, one before the closing. This allows you to place literal backtick characters at the beginning or end of a code span:

A single backtick in a code span: `` ` ``

A backtick-delimited string in a code span: `` `foo` ``

will produce:

<p>A single backtick in a code span: <code>`</code></p> 

<p>A backtick-delimited string in a code span: <code>`foo`</code></p>

With a code span, ampersands and angle brackets are encoded as HTML entities automatically, which makes it easy to include example HTML tags. Markdown will turn this:

Please don't use any `<blink>` tags.

into:

<p>Please don't use any <code>&lt;blink&gt;</code> tags.</p>

You can write this:

`&#8212;` is the decimal-encoded equivalent of `&mdash;`.

to produce:

<p><code>&amp;#8212;</code> is the decimal-encoded
equivalent of <code>&amp;mdash;</code>.</p>

Images

Admittedly, it's fairly difficult to devise a "natural" syntax for placing images into a plain text document format.

Markdown uses an image syntax that is intended to resemble the syntax for links, allowing for two styles: inline and reference.

Inline image syntax looks like this:

![Alt text](/path/to/img.jpg)

![Alt text](/path/to/img.jpg "Optional title")

That is:

  • An exclamation mark: !;
  • followed by a set of square brackets, containing the alt attribute text for the image;
  • followed by a set of parentheses, containing the URL or path to the image, and an optional title attribute enclosed in double or single quotes.

Reference-style image syntax looks like this:

![Alt text][id]

Where "id" is the name of a defined image reference. Image references are defined using syntax identical to link references:

[id]: url/to/image  "Optional title attribute"

As of this writing, Markdown has no syntax for specifying the dimensions of an image; if this is important to you, you can simply use regular HTML <img> tags.

Miscellaneous

Automatic Links

Markdown supports a shortcut style for creating "automatic" links for URLs and email addresses: simply surround the URL or email address with angle brackets. What this means is that if you want to show the actual text of a URL or email address, and also have it be a clickable link, you can do this:

<http://example.com/>

Markdown will turn this into:

<a href="http://example.com/">http://example.com/</a>

Automatic links for email addresses work similarly, except that Markdown will also perform a bit of randomized decimal and hex entity-encoding to help obscure your address from address-harvesting spambots. For example, Markdown will turn this:

<address@example.com>

into something like this:

<a href="&#x6D;&#x61;i&#x6C;&#x74;&#x6F;:&#x61;&#x64;&#x64;&#x72;&#x65;
&#115;&#115;&#64;&#101;&#120;&#x61;&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;
&#109;">&#x61;&#x64;&#x64;&#x72;&#x65;&#115;&#115;&#64;&#101;&#120;&#x61;
&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;&#109;</a>

which will render in a browser as a clickable link to "address@example.com".

(This sort of entity-encoding trick will indeed fool many, if not most, address-harvesting bots, but it definitely won't fool all of them. It's better than nothing, but an address published in this way will probably eventually start receiving spam.)

Backslash Escapes

Markdown allows you to use backslash escapes to generate literal characters which would otherwise have special meaning in Markdown's formatting syntax. For example, if you wanted to surround a word with literal asterisks (instead of an HTML <em> tag), you can use backslashes before the asterisks, like this:

\*literal asterisks\*

Markdown provides backslash escapes for the following characters:

\   backslash
`   backtick
*   asterisk
_   underscore
{}  curly braces
[]  square brackets
()  parentheses
#   hash mark
+   plus sign
-   minus sign (hyphen)
.   dot
!   exclamation mark

MultiMarkdown Syntax Guide

This is a guide to the markup syntax used in the MultiMarkdown system.

Metadata

MultiMarkdown has support for metadata, meaning that you can include information about a document that is not necessarily part of the document contents.

To use metadata, simply add information to the top of a Markdown file:

Title:  A New MultiMarkdown Document  
Author: Fletcher T. Penney  
        John Doe  
Date:   July 25, 2005

The key is the text before the colon, and the data is the text after the colon. In the above example, notice that there are two lines of information for the Author key. If you end a line with "space-space-newline", the newline will be included when converted to other formats.

There must not be any whitespace above the metadata, and the metadata block ends with the first whitespace only line. The metadata is stripped from the document before it is passed on to the syntax parser.

While not required, I recommend including two spaces at the end of each line of metadata. In this way, if you pass your document through a regular version of Markdown, the metadata will be properly formatted as plain text with line breaks, rather than joined into a single run-on paragraph.

I have included information about some of the "standard" metadata keys --- I welcome feedback and suggestions for additional standard keys that would be useful. If you add keys that are not listed, they are included in the XHTML and LaTeX as custom variables that can still be used if you desire.

Remember, XHTML snippets have no means to use metadata. To make use of these features, one must be using Format: complete to create full XHTML documents, which can then be processed using XSLT to create other document types. As an example, I use metadata for information that is used to add title, author, keyword, and copyright metadata to PDF's created by MultiMarkdown.

Note: I make multiple mentions to the use of these keys for LaTeX documents. This is simply because the LaTeX output format currently makes the most use of the metadata information. Any export format could be modified to make use of additional metadata keys.

Address

Use this to include the author's mailing address. You can have more than one line in this field --- use two extra spaces at the end of a line, and a newline character will be used in LaTeX. Also used as return address for letterhead and envelope templates.

Author

Self-explanatory. I strip this out to provide an author string to LaTeX documents. Also used as the sender for letterhead and envelope templates.

Affiliation

Use this to include an organization that the author is affiliated with, e.g. a university, company, or organization. You can include address information here as well, or use the Address, email, web, and phone metadata fields. You can have more than one line in this field --- use two extra spaces at the end of the line, and a newline character will be used in LaTeX.

Base Header Level

Used by my XSLT script tool to change the default header level. For example, if using the memoir class, you might want a first level header to be interpreted as a chapter, rather than as a part. To do this, simply set Base Header Level to 2.

Base URL (Deprecated)

Deprecated - WikiWords and WikiLinks no longer supported.

Bibliography Title

Change the title used for the references section (e.g. "References" or "Bibliography"). The default value is "Bibliography".

Bibliography Style

The name of the BibTeX style you wish to use.

BibTeX

This should be the name of a .bib file (a BibTeX file used to store references). If you use my xhtml2latex.xslt file, this will convert external citations into markup for BibTeX (see [Bibliography Support][] for more information).

You must have bibtex installed and working, and the .bib file must be in your working directory.

Chapterstyle

This is used to designate the chapterstyle in LaTeX memoir documents.

Copyright

This can be used to provide a copyright string.

CSS

Used to specify a CSS stylesheet when creating the complete XHTML output.

Date

Provide a date for the document.

Email

Use this to include the author's email address.

Format

Set to complete to indicate that a fully-formed XHTML document should be produced. Such a document is ready for processing by an XSLT tool, such as the XSLT files to convert XHTML into LaTeX.

Set to snippet to indicate that no <head> or other information should be included. This might be useful for generating (X)HTML output ready for pasting into a weblog, for example.

Note: Some MultiMarkdown tools add this for you (e.g. TextMate using my bundle, and Scrivener.) Duplicating the Format key in these programs should not cause a problem --- let me know if you have trouble.

Keywords

Provide a list of keywords for the document. I use these to add keywords to PDF's that are produced as well. Keywords can be separated by commas, or placed on separate lines.

Language

Currently, the language field is used to specify which version of SmartyPants to use. In the future, it may be used for other purposes as well.

The languages are written using the English word (e.g. "german" not "deutsch").

LaTeX XSLT

Used to designate an XSLT file to convert an XHTML document to a LaTeX document. The LaTeX document can then be converted to PDF by pdflatex. This key used to be called XSLT File.

Pagestyle

This is used to designate the pagestyle in LaTeX memoir documents.

Phone

Use this to include the author's phone number(s). You can have more than one line in this field --- use two extra spaces at the end of the line, and a newline character will be used in LaTeX.

Recipient

Used by letterhead and envelope templates.

Recipient Address

Used by letterhead and envelope templates.

Revision

You can use a string to declare the current version of the document. Displayed on the copyright page when using my memoir XSLT transform.

RTF XSLT

This key is used to provide an XSLT file that can alter the XHTML output prior to conversion to RTF. Useful for further customizing the output of MultiMarkdown specifically for the RTF format. I have no plans to create any such files myself, but others may find it useful.

I strongly encourage you to use another route to convert XHTML to RTF.
I've had the best results with Google Docs. For non-Mac users, that's definitely the way to go.

Subtitle

Used to provide a subtitle. It ends up in the meta tags, but can be extracted by XSLT for other uses.

Title

Used to provide the official title of a document. This is set as the <title> string within the <head> section of an HTML document, and is also used by other export formats.

Use WikiLinks (Deprecated)

Set to true or 1 to enable the use of WikiWords and <a class="not-exists" href="//wiki.qubling.com/page/view/yukki/Free-Links.yukki">Free Links</a>. Requires that you also set Base URL. See [WikiLinks (Deprecated)][] for more information.

Web

Use this to include the author's web URL.

XHTML Header

This is used to include raw XHTML information in the header of a document. You can use this field to add information that will be included in the header of the generated XHTML file. This can be CSS formatting data, or javascript code, or just about anything. I am not responsible for getting that code to work. MultiMarkdown just includes it as is.

Anything included in this field is inserted, unaltered, in the <head> section of the XHTML output. If you do add anything here, the XSLT stylesheet may have to updated to ignore what you added if you want to convert to LaTeX. Let me know what you add, and I can consider updating the XSLT stylesheet to ignore it. Currently it ignores <style> sections.

XHTML XSLT

This is the name of the XSLT file to use to post-process the XHTML file. This can be used to further customize the XHTML output generated by MultiMarkdown. For example, the xhtml-toc.xslt file can add a Table of Contents to the start of XHTML page.

XMP

This is used to provide a file to be included using xmpincl. Basically, this adds the ability to provide Creative Commons Licensing information in a PDF's metadata. It can also be used for other purposes (beyond the scope of this document.)

XSLT File (deprecated)

This metadata key has been deprecated in favor of XHTML XSLT, RTF XSLT, and LaTeX XSLT.

Automatic Cross-References

An oft-requested feature was the ability to have Markdown automatically handle within-document links as easily as it handled external links. To this aim, I added the ability to interpret [Some Text][] as a cross-link, if a header named "Some Text" exists.

As an example, [Metadata][] will take you to the [section describing metadata][Metadata].

Alternatively, you can include an optional label of your choosing to help disambiguate cases where multiple headers have the same title:

### Overview [MultiMarkdownOverview] ##

This allows you to use [MultiMarkdownOverview] to refer to this section specifically, and not another section named Overview. This works with atx- or settext-style headers.

If you have already defined an anchor using the same id that is used by a header, then the defined anchor takes precedence.

In addition to headers within the document, you can provide labels for images and tables which can then be used for cross-references as well.

Image Support

Obviously, images are handled just fine by Markdown (with the exception of attributes as noted above.) However, without some more information, images are not easily translated into other document formats (e.g. PDF).

To handle this, my XSLT files will make use of <img> dimensions (e.g. height and width). If present, the image will be scaled. If only one dimension is specified, the image will be scaled proportionately. If neither height nor width is specified, then the image will be scaled such that it's width is the same as a column of text. This is to prevent high resolution images from overflowing the page. Unfortunately, it has the side effect of "zooming" in on smaller images. So, if you have images that are being scaled in a way that you do not desire, simply specify at least one dimension.

Note: XHTML only allows for units of px and % on <img> tags. LaTeX allows for several others. So, my XSLT file allows for other units to be used, even if they screw up the XHTML version. You have to choose appropriate units for your purpose. Unfortunately, the only way around this is to make sure that all of your images contain actual dimension information, and then remove the \resizebox part from the XSLT.

Anchor and Image Attributes

Adding attributes to links and images has been requested for a long time on the Markdown discussion list. I was fairly opposed to this, as most of the proposals really disrupted the readability of the syntax. I consider myself a "Markdown purist", meaning that I took John's introduction to heart:

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.

Because there was not a syntax proposal that I felt fit this goal, I was generally opposed to the idea.

Then, Choan C. Gálvez proposed a brilliantly simple syntax that stayed out of the way. By simply appending the attributes to the link reference information, which is already removed from the text itself, it doesn't disturb the readability.

For example:

This is a formatted ![image][] and a [link][] with attributes.

[image]: http://path.to/image "Image title" width=40px height=400px
[link]:  http://path.to/link.html "Some Link" class=external
         style="border: solid black 1px;"

This will generate width and height attributes for the image, and a border around the link. And while it can be argued that it does look "like it's been marked up with tags [and] formatting instructions", even I can't argue too strongly against it. The link and the title in quotes already look like some form of markup, and the the additional tags are hardly that intrusive, and they offer a great deal of functionality. They might even be useful in further functions (citations?).

The attributes must continue after the other link/image data, and may contain newlines, but must start at the beginning of the line. The format is attribute=value or attribute="multi word value". Currently, MultiMarkdown does not attempt to interpret or make any use of any of these attributes. Also, you can't have a multiword attribute span a newline.

WikiLinks (Deprecated)

Note: The WikiLinks feature was more trouble than it was worth, and has been removed. One can still use the wiki software to manage these links. For example, my MultiMarkdown Extension for Oddmuse supports Oddmuse styled WikiLinks.

Footnotes

I have added support for footnotes to MultiMarkdown, using the syntax proposed by John Gruber. Note that there is no official support for footnotes yet, so the output format may change, but the input format sounds fairly stable.

To create a footnote, enter something like the following:

Here is some text containing a footnote.[^somesamplefootnote]

[^somesamplefootnote]: Here is the text of the footnote itself.

[somelink]:http://somelink.com

The footnote itself must be at the start of a line, just like links by reference. If you want a footnote to have multiple paragraphs, lists, etc., then the subsequent paragraphs need an extra tab preceding them. You may have to experiment to get this just right, and please let me know of any issues you find.

This is what the final result looks like:

Here is some text containing a footnote.1

Tables

I have implemented a syntax for tables similar to that used by Michael Fortin's PHP Markdown Extra.

Basically, it allows you to turn:

|             |          Grouping           ||
First Header  | Second Header | Third Header |
 ------------ | :-----------: | -----------: |
Content       |          *Long Cell*        ||
Content       |   **Cell**    |         Cell |

New section   |     More      |         Data |
And more      |            And more          |
[Prototype table]

into a [table][Prototype Table].

Prototype table
Grouping
First Header Second Header Third Header
Content Long Cell
Content Cell Cell
New section More Data
And more And more

The requirements are:

  • There must be at least one | per line
  • The second line must contain only |,-,:,., or spaces
  • Cell content must be on one line only
  • Columns are separated by |
  • The first line of the table, and the alignment/divider line, must start at the beginning of the line

Other notes:

  • It is optional whether you have |'s at the beginning and end of lines.

  • To set alignment, you can use a colon to designate left or right alignment, or a colon at each end to designate center alignment, as above. If no colon is present, the default alignment of your system is selected (left in most cases). If you use a period character (.), then char alignment is used - in the future this will allow columns of decimal formatted numbers to be aligned on the decimal character. Browsers do not currently support this feature, so it is somewhat useless at the moment. It could be used in an XSLT stylesheet for other output formats (e.g. LaTeX).

  • To indicate that a cell should span multiple columns, there simply add additional pipes (|) at the end of the cell, as shown in the example. If the cell in question is at the end of the row, then of course that means that pipes are not optional at the end of that row....

  • You can use normal Markdown markup within the table cells.

  • Captions are optional, but if present must be at the beginning of the line immediately preceding or following the table, start with [, and end with ]. If you have a caption before and after the table, only the first match will be used.

  • If you have a caption, you can also have a label, allowing you to create anchors pointing to the table. If there is no label, then the caption acts as the label

  • Cells can be empty.

  • You can create multiple <tbody> tags within a table by having a single empty line between rows of the table. This allows your CSS to place horizontal borders to emphasize different sections of the table.

  • If there is no header for the first column, then cells in that column will be treated as headers, and formatted as such.

Bibliography Support

I have included support for basic bibliography features in this version of MultiMarkdown. Please give me feedback on ways to improve this but keep the following in mind:

  1. Bibliography support in MultiMarkdown is rudimentary. The goal is to offer a basic standalone feature, that can be changed using the tool of your choice to a more robust format (e.g. BibTeX, CiteProc). My XSLT files demonstrate how to make this format compatible with BibTeX, but I am not planning on personally providing compatibility with other tools. Feel free to post your ideas and tools to the wiki.

  2. Those needing more detailed function sets for their bibliographies may need customized tools to provide those services. This is a basic tool that should work for most people. Reference librarians will probably not be satisfied however.

To use citations in MultiMarkdown, you use a syntax much like that for anchors:

This is a statement that should be attributed to
its source[p. 23][#Doe:2006].

And following is the description of the reference to be
used in the bibliography.

[#Doe:2006]: John Doe. *Some Big Fancy Book*.  Vanity Press, 2006.

The XHTML that is generated is as follows:

<p>This is a statement that should be attributed to its source
<span class="markdowncitation"> (<a href="#Doe:2006">1</a>, <span 
class="locator">p. 23</span>)</span>.</p>

<p>And following is the description of the reference to be used
in the bibliography.</p>

<div class="bibliography">
<hr />
<p>Bibliography</p>

<div id="Doe:2006"><p>[1] John Doe. <em>Some Big Fancy Book</em>.
Vanity Press, 2006.</p></div>

</div>

You are not required to use a locator (e.g. p. 23), and there are no special rules on what can be used as a locator if you choose to use one. If you prefer to omit the locator, just use an empty set of square brackets before the citation:

This is a statement that should be attributed to its 
source[#Doe:2006][].

The empty square brackets have to be placed AFTER the reference, not before.

There are no rules on the citation key format that you use (e.g. Doe:2006), but it must be preceded by a #, just like footnotes use ^.

As for the reference description, you can use Markup code within this section, and I recommend leaving a blank line afterwards to prevent concatenation of several references. Note that there is no way to reformat these references in different bibliography styles; for this you need a program designed for that purpose (e.g. BibTeX).

If you want to include a source in your bibliography that was not cited, you may use the following:

[Not cited][#citekey]

The Not cited bit is not case sensitive.

MultiMarkdown References

If you define your references (as in the example above), MultiMarkdown will automatically append a basic bibliography to the end of your document. The citations will of the form:

<span class="markdowncitation"> (<a href="#citekey">#
</a>, <span class="locator">p. 23</span>)</span>

If you don't define a locator, you will get:

<span class="markdowncitation"> (<a href="#citekey">#
</a>)</span>

When you click on the # (which is replaced with the specific reference number), it takes you to the appropriate point in the Bibliography. Unlike footnotes, there is no reverse link.

External References

If you do not define references, then MultiMarkdown will substitute different markup that can be used by XSLT to transform it into markup for an external tool, e.g. BibTeX.

<span class="externalcitation"> (<a id="citekey">citekey</a>, <span 
class="locator">p. 23</span>)</span>

If you don't define a locator, you will get:

<span class="externalcitation"> (<a id="citekey">citekey</a>)</span>

Obviously, the citekey that you use in MultiMarkdown must match that used by your external tool.

Multiple Citations

When you need to combine multiple citations together, simply add them serially:

[p. 3][#Doe:1996][p. 10][#Smith:2005]

giving the output:

(1, p. 3) (2, p. 10)

Notice that empty square brackets have to be placed AFTER the reference if you don't want to use a locator:

[#Doe:1996][][#Smith:2005][]

I recognize that this is not really a standardized format, but again I remind you that the bibliography support in MultiMarkdown is minimal. If you want more control, or adherence to proper style rules, you need a more powerful bibliography tool.

I have written a perl script that will join these serial citations into one, cleancites.pl. It is run by default by the default MultiMarkdown usage scripts.

BibTeX Support

If you are a user of BibTeX, you may use it to control your references. Simply set the Bibtex and Bibliographystyle metadata as described in the section on [Metadata][], and use my xhtml2latex XSLT files as examples.

If you use this, you are not required to define your references within your MultiMarkdown document.

Advanced Citations with natbib

Advanced LaTeX users are probably familiar with the natbib package, which adds additional features for bibliographic citations. It offers two new citation commands, \citet and \citep.

To use the advanced natbib features:

  1. You must have the natbib package installed for LaTeX
  2. You must use an appropriate XSLT file that enables the natbib package (memoir-natbib.xslt is an example - you can make your own)

By default, citations occur using the \citep command.

To use a \citet citation, follow the example below:

In their seminal paper, [Smith and Jones; p 42][#Smith1990] argue
convincingly that....

[#Smith1990]: Smith, R, and Jones, K. *Some Fancy Article* etc...

The text before the semi-colon indicates that we want a textual citation. In the XHTML version, the text you enter becomes the text in the sentence. When converted to LaTeX, your text is actually removed and the natbib package handles it for you. The text after the semi-colon is the usual locator text (if you don't want a locator, just leave it blank after the semi-colon).

If you don't include a semi-colon, then the \citep command is used in the usual fashion.

Math Syntax

Introduction to Math support

Note: Math support within MultiMarkdown is created using MathML. MathML is not fully supported in many browsers, so your mileage may vary (I honestly don't care whether Internet Explorer works --- get a real browser. Support within Firefox is pretty good, but not perfect.) This feature is quite useful, however, when generating a PDF via LaTeX.

To view a file with MathML properly in Firefox, it must have the file ending ".xhtml". I don't know why, and it seems dumb that file extensions are so important in 2007. But for now, that's the way it is.

MultiMarkdown supports ASCIIMathML a syntax for converting mathematical equations from plain text into MathML. MathML can be used within properly formatted XHTML documents to display well typeset mathematical formula.

The conversion used to managed by ASCIIMathPHP, which was a PHP script that had to be run separately from MultiMarkdown itself. As of version 2.0b.b4, however, I am using the Text::ASCIIMathML Perl module for support built into the MultiMarkdown script.

MultiMarkdown Math Syntax

Basically, use use << and >> as delimiters to indicate that you are including math in your document. You can use this to create an inline formula, or you can create independent equations, each in it's own paragraph. These can also then be converted properly into LaTeX math environments.

Additionally, you can include a [label] tag at the end of the equation to allow you to reference it elsewhere in your text with the label. For example:

<< e^(i pi) + 1 = 0 [Euler's identity]>>

<< x_(1,2) = (-b+-sqrt(b^2-4ac))/(2a) [quadratic equation solution]>>

You can also include formulas within a sentence, such as
<<x^2 + y^2 = 1>>.  You can then make a reference to
[Euler's identity].

is converted into:

<< e^(i pi) + 1 = 0 [Euler's identity]>>

<< x_(1,2) = (-b+-sqrt(b^2-4ac))/(2a) [quadratic equation solution]>>

You can also include formulas within a sentence, such as << x^2 + y^2 = 1>>. You can then make a reference to [Euler's identity].

Superscripts

By using the math mode above, you can include superscripts and the like in MultiMarkdown documents that don't necessarily have to be separate formulas. For example:

<<2^pi>>

becomes

<<2^pi>>.

This is, of course, subject to the same limitations as MathML in general.

MathML Difficulties

There are some glitches in this process. First, many browsers don't fully support MathML, and sometimes you have to go through great lengths to get the browser to recognize it properly. Firefox, for instance, requires an .xhtml extension to properly recognize the file as XHTML instead of HTML. This may not be an ideal solution for everybody, but it does allow you to use a plain english syntax to represent mathematical formulas and symbols within Markdown documents, which was my goal. Others may prefer to use custom solutions using raw LaTeX source, but I didn't want to have to learn the LaTeX math syntax.

On the up side, however, this does give wonderful output when combined with my XSLT scripts to generate LaTeX documents and PDF's. I am open to input on this feature, and suspect it will become increasingly useful as browser support for MathML improves.

For more information on supporting MathML in web browsers, I have written a brief introduction to Supporting MathML on my web site.

Definition Lists

MultiMarkdown has support for definition lists using the same syntax used in PHP Markdown Extra. Specifically:

Apple
:   Pomaceous fruit of plants of the genus Malus in 
    the family Rosaceae.
:   An american computer company.

Orange
:   The fruit of an evergreen tree of the genus Citrus.

becomes:

Apple
Pomaceous fruit of plants of the genus Malus in the family Rosaceae.
An american computer company.
Orange
The fruit of an evergreen tree of the genus Citrus.

You can have more than one term per definition by placing each term on a separate line. Each definition starts with a colon, and you can have more than one definition per term. You may optionally have a blank line between the last term and the first definition.

Definitions may contain other block level elements, such as lists, blockquotes, or other definition lists.

Unlike PHP Markdown Extra, all definitions are wrapped in <p> tags. First, I was unable to get Markdown not to create paragraphs. Second, I didn't see where it mattered - the only difference seems to be aesthetic, and I actually prefer the <p> tags in place. Let me know if this is a problem.

See the PHP Markdown Extra page for more information.

Appendices

If you want to designate the final subgroup of chapters as appendices, you can include an h1 or h2 level header (as appropriate based on your document) with the title Appendices. The chapters that follow would be considered appendices when the document is converted to LaTeX using the memoir class. Since XHTML doesn't have a concept of appendices, it has no real meaning, but would at least designate this to the reader.

Glossaries

MultiMarkdown has a feature that allows footnotes to be specified as glossary terms. It doesn't do much for XHTML documents, but the XSLT file that converts the document into LaTeX is designed to convert these special footnotes into glossary entries.

The glossary format for the footnotes is:

[^glossaryfootnote]: glossary: term (optional sort key)
    The actual definition belongs on a new line, and can continue on
    just as other footnotes.

The term is the item that belongs in the glossary. The sort key is optional, and is used to specify that the term should appear somewhere else in the glossary (which is sorted in alphabetical order).

Unfortunately, it takes an extra step to generate the glossary when creating a pdf from a latex file:

  1. You need to have the basic.gst file installed, which comes with the memoir class.

  2. You need to run a special makeindex command to generate the .glo file: makeindex -s `kpsewhich basic.gst` -o "filename.gls" "filename.glo"

  3. Then you run the usual pdflatex command again a few times.

Alternatively, you can use the code below to create an engine file for TeXShop (it belongs in ~/Library/TeXShop/Engines). You can name it something like MemoirGlossary.engine. Then, when processing a file that needs a glossary, you typeset your document once with this engine, and then continue to process it normally with the usual LaTeX engine. Your glossary should be compiled appropriately. If you use TeXShop, this is the way to go.

Note: Getting glossaries to work is a slightly more advanced LaTeX feature, and might take some trial and error the first few times.

#!/bin/ 

set path = ($path /usr/local/teTeX/bin/powerpc-apple-darwin-current 
    /usr/local/bin) # This is actually a continuation of the line above

set basefile = `basename "$1" .tex`

makeindex -s `kpsewhich basic.gst` -o "${basefile}.gls" "${basefile}.glo"

Poetry Mode

By default, when you have a section of text indented with a tab, MultiMarkdown interprets this as a code block. This allows you to more exactly control the spacing and line endings, but it also applies a monospace font in both the XHTML and LaTeX outputs. This is the usual way of demonstrating source code in documents.

Some authors, however, don't write about source code, but would like a way to control line endings (when writing poetry, for example).

To accomplish this, there are several alternate XSLT files included within the MultiMarkdown distribution that are labelled with a poetry filename. These XSLT files handle the code blocks in a slightly different way to make them more suitable for text, rather than code. I encourage you to give this a try.

At the current time, there is no way to use both formats within the same document, except to format them manually. This may change in the future, depending on some decisions John Gruber needs to make about the standard Markdown syntax.

Miscellanea

In addition to what is mentioned elsewhere in this document, MultiMarkdown does a few things slightly differently:

  • &copy; entities are converted to &#xA9; so that they can pass through an XSLT parser

  • * and _ are not interpreted as <strong> or <em> when they occur in the middle of words. This caused too many problems with URL's.

MultiMarkdown supports the conversion of colored spans of text from XHTML to LaTeX using the xcolor package. For example:

<span style="color:#888888">net</span>

becomes:

{\color[HTML]{888888} net}

There is not currently a syntax shortcut for this, you have to manually add the <span> information. This technique is used to support annotations from Scrivener, for example.

  1. Here is the text of the footnote itself. ↩

HEAD: Last updated 13 years ago.