XBeta Wiki
Markdown

Markdown is a Lightweight markup language, originally created by John Gruber and Aaron Swartz, which aims for maximum readability and “publishability” of both its input and output forms, taking many cues from existing conventions for marking up plain text in email. Markdown converts its marked-up text input to valid, well-formed XHTML and replaces left-pointing angle brackets (<) and ampersands with their corresponding character entity references. Markdown was originally implemented in Perl by Gruber, but has since been re-implemented by others in a variety of programming languages (see below for list). It is distributed under a BSD-style license and is included with, or available as a plugin for, several content management systems.

This wiki uses the Maruku implementation of Markdown and therefore supports some additional extensions such as footnotes as well as Maruku’s metadata syntax. See Formatting rules for details. The Emacs markdown-mode in combination with the Firefox mozex extension for using an external text editor can help in editing pages. There is also a Vim mode.

Contents

Syntax examples

This is not an exhaustive listing of Markdown’s syntax, and in many cases multiple styles of syntax are available to accomplish a particular effect. See the full Markdown syntax for more information. Characters which are ordinarily interpreted by Markdown as formatting commands will instead be interpreted literally if preceded by a backslash; for example, the sequence \* would output an asterisk rather than beginning a span of emphasized text. Markdown also does not transform any text within a “raw” block-level XHTML element; thus it is possible to include sections of XHTML within a Markdown source document by wrapping them in block-level XHTML tags.

Paragraphs:

A paragraph is one or more consecutive lines of text separated by one or more blank lines. Normal paragraphs should not be indented with spaces or tabs:

This is a paragraph. It has two sentences.

This is another paragraph. It also has two sentences.

Emphasized text:

*emphasis* (e.g., italics)

**strong emphasis** (e.g., boldface)

Code:

`code`

Lists:

- An item in a bulleted (unordered) list
- Another item in a bulleted list

1. An item in an enumerated (ordered) list
2. Another item in an enumerated list

Headings:

HTML headings are produced by placing a number of hashes before the header text corresponding to the level of heading desired (HTML offers six levels of headings), like so:

# First-level heading

#### Fourth-level heading

The first two heading levels also have an alternate syntax:

First-level heading
===================

Second-level heading
--------------------

Blockquotes:

> This text will be enclosed in an HTML blockquote element.

Links:

[link text here](link.address.here "link title here")

Images:

![Alt text here](Image URL here "Image title here")

Horizontal rules are created by placing three or more hyphens, asterisks, or underscores on a line by themselves. You may use spaces between the hyphens or asterisks. Each of the following lines will produce a horizontal rule:

* * *
***
*****
- - -
---------------------------------------

Syntax Guides

Implementations

  • Haskell:

    • Pandoc by John MacFarlane (converts Markdown to HTML, LaTeX, ConTeXt, reStructuredText, S5, groff man, DocBook, and RTF, and partially converts HTML, LaTeX, and reStructuredText to Markdown)
    • markdown-peg

Text Editor Support

Wiki Support

Blog Software

Content Management Systems

Converters

The implementations above by default refer to Markdown to XHTML conversion. Converters to and from other formats are also available.

  • Markdown to LaTeX, Markdown+LaTeX to MathML, etc.

  • XHTML to Markdown:

    • html2text.py (in Python)
    • Markdownify (in PHP)
    • Make.text (a bookmarklet which converts any web page into Markdown.)
    • XHTML-to-Markdown XSLT (a stylesheet, works with XHTML only)
    • Pandoc (a Haskell library that can convert between many formats including Markdown, HTML, reStructuredText, LaTeX, MediaWiki and others)
    • html2x (web form and bookmarklet, based on Pandoc)
    • kramdown (Ruby)
  • Other formats to Markdown:

    • Pandoc (a Haskell library that can convert between many formats including Markdown, HTML, reStructuredText, LaTeX, and others)
    • odt2txt (a Python script to convert OpenDocument text files to Markdown)
    • word_markdown_macro (a Microsoft Word macro that converts some of Word’s formatting into Markdown)

Other Software

HOWTOs

Tests


Discussion

A large number of links were recently removed from the Markdown Wikipedia page, citing the link farm policy. Furthermore, since infogami is defunct, the previous semi-official Markdown wiki hosted there cannot be edited by those without a previously created account. I merged the content of the Wikipedia and infogami pages and created this page in order to provide a publicly-editable repository of Markdown-related links.—Jason Blevins, April 19, 2009 19:19 EDT