Contents
GitHub supports several lightweight markup languages for documentation; the most popular ones (generally, not just at GitHub) are Markdown and reStructuredText. Markdown is sometimes considered easier to use, and is often preferred when the purpose is simply to generate HTML. On the other hand, reStructuredText is more extensible and powerful, with native support (not just embedded HTML) for tables, as well as things like automatic generation of tables of contents.
Unless you are embedding text into a programming language (especially Python doc comments, for which purpose reStructuredText was originally developed) you will probably choose to use Markdown for a small document (like this Gist once was). But as you add more sections and features, you may decide that you want the power of reStructuredText. To avoid having to convert all of your Markdown formatting when that happens, use this Gist as a guide to the markup syntax common to Markdown and reStructuredText.
By using only the common subset shared by these two lightweight markup languages (largely from Setext, which inspired both of them) for your documents, you can eliminate the need for conversion. Even if you also use features that are specific to one or the other, using the common subset wherever possible allows for painless cut & paste between them.
Another advantage of restricting yourself to the common subset described here is that the resulting source is more likely to be parsed the same way by different Markdown processors, which may handle some details like indentation slightly differently.
If you have already used Markdown-specific syntax, or you just don't want to limit yourself to the (admittedly very limited) intersection of functionality in the subset, you can use Pandoc to convert Markdown into reStructuredText - the online converter at <http://johnmacfarlane.net/pandoc/try> is handy if you don't happen to have Haskell installed. (In fact, you may find the extended Markdown supported by Pandoc adds enough functionality that you don't need to use reStructuredText at all - at least, once you get Haskell and Pandoc installed.)
The basics of text formatting are common to both, a blank line (it may contain spaces or tabs, but nothing else) is used to separate paragraphs and everything within a paragraph "flows" and is wrapped to the display width. Be sure to avoid initial indentation (either of an entire paragraph or just the first line) for normal text, as indentation is significant to both Markdown and reStructuredText, but in different ways.
When writing text, you should try to wrap source lines to 72 characters - but only when initially entering them - avoid re-wrapping text when you edit it later, to limit the number of "insignificant changes" in your version control system (you are using one, right?!). Feel free to use two spaces after the period at the end of a sentence (or not) if that is useful for your text editor - I'm looking at you, Emacs - since multiple spaces are treated the same as a single space. Similarly, multiple blank lines are treated just like one blank line; you may want to use multiple blank lines at the end of a section.
Within paragraphs, inline markup provides basic formatting to add
emphasis to particular words or phrases, most commonly by making them
italic or bold (depending on the font, italics are often rendered
with an oblique face instead). In technical writing, monospaced
text may be used to highlight program or function names, or for very
short snippets of code.
As with many types of formatting, Markdown provides multiple ways of
specifying font faces, one of which is also used by reStructuredText:
italics are marked with one asterisk (*) and bold face with two. There
must be whitespace or other punctuation before the leading asterisks,
and after the trailing ones; furthermore there must be no space between
the asterisks and the text being emphasized. Although Markdown supports
nesting bold and italic, reStructuredText does not (this is one of the
rare cases where Markdown is more powerful, as there is no way to
represent bold italics in reStructuredText).
Monospaced text is marked with two backquotes "``" instead of asterisks; no bold or italic is possible within it (asterisks just represent themselves), although in some contexts, code syntax highlighting may be applied. Note that in monospaced text, multiple spaces are not collapsed, but are preserved; however, flow and wrapping do occur, and any number of spaces may be replaced by a line break. Markdown allows monospaced text within bold or italic sections, but not vice versa - reStructuredText allows neither. In summary, the common inline markup is the following:
Mark *italic text* with one asterisk, **bold text** with two. For ``monospaced text``, use two "backquotes" instead.
Mark italic text with one asterisk, bold text with two.
For monospaced text, use two "backquotes" instead.
(Markdown allows a single backquote to indicate monospaced text, however double backquotes ar better, since they allow for embedded backquotes and are required for reStructuredText.)
Sometimes you may want to use markup characters just as themselves, without any special interpretation. Within double backquotes used to mark monospaced text (or in code blocks as described below), markup characters are not treated specially, but in other contexts, you must precede markup characters with a backslash (\) to escape them (this applies to the backslash character as well):
\*This\* is not *italic* - \\My Pictures\\ is a Windows folder
*This* is not italic - \My Pictures\ is a Windows folder
While reStructuredText will treat a backslash before any non-whitespace character as an escape, Markdown only treats backslash as an escape when it precedes one of the following characters:
- \ backslash
- ` backtick
- * asterisk
- _ underscore
- {} curly braces
- [] square brackets
- () parentheses
- # hash mark
- + plus sign
- - minus sign (hyphen)
- . dot
- ! exclamation mark
For compatibility, only use backslash before one of these characters, and be sure to escape any backslashes that you want to appear in the output.
If you have example code or console text that you want to appear with
all line breaks and relative indentation preserved, in a monospaced text
block, there is no common format for Markdown and reStructuredText, but
you can combine the formatting for both of them by ending one paragraph
with a double colon :: (for reStructuredText) and indenting the next
one by four or more spaces (for Markdown) to make it appear in
monospaced font without flow or word-wrapping:
A normal paragraph ending with ``::`` will flow and be word-wrapped::
If the next paragraph is indented by four or more spaces, it will be monospaced text, without flow (or even wrapping in some non-print cases.)
You can have multiple paragraphs like this, as long as they
are all indented by the same amount.
A normal paragraph ending with :: will flow and be word-wrapped:
If the next paragraph is indented by four or more spaces, it will be monospaced text, without flow (or even wrapping in some non-print cases.) You can have multiple paragraphs like this, as long as they are all indented by the same amount.
(We cheat a little bit here, Markdown does not interpret the double-colon, but displays it as-is, whereas reStructuredText displays just a single colon, but this is not too noticeable or annoying, as long as you remember to use the double colon in your source.)
You may want to preserve line breaks in text blocks but don't want them
in monospaced text; common cases are verse (poetry or lyrics), street
addresses, and unadorned lists without bullets or numbering. Markdown
and reStructuredText use completely different syntax for this, but you
can combine the markup for both reStructuredText line blocks and
Markdown hard line breaks by starting each line with a vertical bar (|)
and a space and ending it with two spaces. For line breaks in the
source you don't want to preserve, omit the two spaces before the line
break and start the next line with one to three spaces instead. Put a
blank line before the start and after the end of every line block.
Line blocks were added to reStructuredText in Docutils version 0.3.5 and there are some reStructuredText formatters that do not support them; notably the GitHub README markup does not display them correctly.
These line blocks can also contain inline markup (which in a code example block might be displayed literally), but keep any markup within each line, since emphasis starting on one line and ending on another applies to vertical bars between them, which appear in Markdown output:
| *Yuku haru ya* | *tori naki uo no* | *me wa namida* | -- **Matsuo Bashō**, The Narrow Road to Oku (*Oku no Hosomichi*), Tokyo, 1996, p. 23 (Translation: Donald Keene) | Spring is passing by! | Birds are weeping and the eyes | of fish fill with tears.
(Again, we cheat a bit, since the Markdown output includes the vertical bars; but at least they make it very clear when you end a line without the required two spaces, something that is quite easy to do as there is usually no visual indication of whether they are there or not.)
When quoting long blocks of text from another writer, it is common
(especially in the context of e-mail) to set it off from the main text
by indenting it, possibly adding a vertical quotation line along the
left margin. Markdown and reStructuredText use different syntax for
this, but you can combine their markup for block quotes by starting the
first line of a quotation with one space and a right angle bracket
(>), indenting all the remaining lines by one space as well (do not
add angle brackets to them).
Note that in reStructuredText, a block quotation cannot directly follow
a code example block - if it does it will be treated as part of the
example. A normal paragraph or an "empty comment" (a line with only two
periods (..) and blank lines before and after it) must separate
them.
Every block quotation must have a blank line before and after it; they can use the same inline markup as ordinary paragraphs. Nested quotations are possible by following a block quotation with another that starts with two spaces and two right angle brackets; this allows up to three levels of quotation (a fourth level is not possible since Markdown treats four leading spaces as a code example). While two right angle brackets can be adjacent, three adjacent right angle brackets are a doctest block (a special kind of code example block) in reStructuredText and must have spaces between them to prevent that interpretation:
> A block quotation will wrap and flow, and can have *inline* ``markup`` just like a regular paragraph. It will be indented on the left (and possibly the right) margins, and may have a vertical quotation line on the left. >> With two spaces and two right angle brackets, a following block quotation will be doubly indented, and will have a second vertical quotation line along the left if quotation lines are generated. > >> A third level of quotation is the maximum level possible.
> A block quotation will wrap and flow, and can have inline
markupjust like a regular paragraph. It will be indented on the left (and possibly the right) margins, and may have a vertical quotation line on the left.>> With two spaces and two right angle brackets, a following block quotation will be doubly indented, and will have a second vertical quotation line along the left if quotation lines are generated.
> >> A third level of quotation is the maximum level possible.
(The cheat here is that the reStructuredText output includes the right angle bracket(s) on the first line in addition to the indentation; this is not ideal, but is generally acceptable when used for a quotation, and not just indented text.)
Both Markdown and reStructuredText allow you to structure your document
by adding header titles for sections and subsections. While they each
support a large number of levels of headers in different ways, the
common subset only has two levels: titles, formed by underlining the
text with ==, and subtitles, formed by underlining with --. The
underlining must be on the very next line, and be at least
as long as the (sub)title:
Section Title ============= The Common Denominator ====================== Subsection Subtitle ------------------- Titles and Section headers --------------------------
Note that a blank line after the underlining is optional, but a blank line before the (sub)title is required.
In addition to (sub)section headers, both Markdown and reStructuredText
support itemized lists; these can be numbered (enumerated) or unnumbered
(bulleted) and the two types of lists can be nested within themselves
and each other. List items are lines starting (possibly after spaces
for indentation) with a bullet symbol (*, -, or +) for bulleted
lists, or a number and a period (1.) for enumerated lists; in both
cases followed by one or more spaces and then the item text. Although
reStructuredText supports other symbols for bulleted lists and
parentheses instead of period for enumerated lists, as well as # in
place of the number for auto-enumeration, Markdown only supports the
subset described above.
The spaces after the symbol or number determine the indentation needed for additional item text on continuation lines or following paragraphs, as well as the symbols or numbers for sub-lists. Symbol or number indentation of all items at any nesting level must be the same (even for long enumerated lists with two-digit numbers) but the indentation of the text of different items need not be the same.
If a list item contains multiple paragraphs (separated by blank lines) or sub-lists, the indentation of the item text must be at least four spaces more than the item symbol or number; this usually requires extra spaces between the number and period (or symbol) and the item text.
A blank line is required before the first item and after the last item in every top-level list, but is optional between items. A blank line is also required by reStructuredText before the first item of a sub-list; omitting it sometimes appears to work, but only because the sub-list is indented more than the item text. This extra indentation may cause the item text to be treated as part of a definition list and displayed in bold; in other cases, it causes the sub-list to be wrapped within a block quote, causing both the left and right margins to move inwards and creating a double-indent effect.
A sub-list without a preceding blank line can also work if there is no item text preceding the sub-list; but this generates odd-looking output that is confusing to human readers, with the first bullet or number of the sub-list on the same line as the bullet or number of the item in the enclosing list.
While Markdown does not require a blank line before a sub-list, a blank line
between items changes the inter-item spacing (typically by creating
<p> paragraph tags). For consistent results, do not use blank lines
between items unless you must (for sub-lists), in which case use blank
lines between all the items at the same level (sub-list items do not
require the blank lines unless there are sub-sub-lists).
Markdown ignores the actual numbers given for enumerated lists and always renumbers them starting with 1, but reStructuredText requires that the numbers be in sequential order; the number of the first item may or may not be preserved. For compatibility, always start enumerated lists with 1 and number them sequentially. You should never mix enumerated and bulleted items (or different bullet symbols) at the same level; reStructuredText will reject it with an error (or, if there is a blank line between them, create a new list). On the other hand, Markdown processors will combine adjacent bulleted and enumerated lists (using the formatting of the first list); to create separate lists it is not enough to have a blank line, there must be a non-list paragraph between them.
Because Markdown formatting requires additional indentation for extra paragraphs of item text in lists, the approach for monospaced paragraphs given above in Code or Console Example Blocks requires additional indentation of at least eight spaces (not just four) for example blocks in lists.
Finally, it is a very good idea to make sure that your document source does not contain any tab characters, especially when working with multiple levels of sub-lists. Configure your text editor to expand all tabs into spaces; this will help to ensure that the initial indentation is consistent and avoid errors if another editor interprets the tabs differently.
The following two lists summarize and provide examples of the rules for lists compatible with Markdown and reStructuredText:
* Mark bulleted lists with one of three symbols followed by a space:
1. asterisk (``*``)
2. hyphen (``-``)
3. plus sign (``+``)
* Mark enumerated lists with a number, period (``.``) and a space.
* The choice of symbol does not affect the output bullet style,
which is solely determined by nesting level.
Items can be continued on following lines indented at the same
level as the item text on the first line, and will flow and wrap
normally.
* The source indentation of item text can vary for different items
(but continuation lines must be indented by the same amount as
the item text that they are continuing).
Additional paragraphs of item text (after a blank line) also
require this indentation, with the extra requirement that it be
four to seven spaces more than the item symbol or number.
* These indentation requirements are the same for sub-list items
(but apply to their symbol or number, not their item text).
* Blank lines between list items are optional, avoid them.
+ If you *do* use them (for items with sub-lists or extra
paragraphs) put blank lines between *all* items at that level.
A non-list paragraph is required to separate adjacent enumerated and
bulleted lists, to keep Markdown from merging the second one into the
first (and using the first style for both).
1. Always put a blank line before the start of a list or sub-list.
2. Use the same bullet symbol for all items in a bulleted list.
3. Always start enumerated lists with 1.
4. Use sequentially increasing numbers for succeeding list items.
5. Do not mix numbers and/or different bullet symbols at one level
* (but this is okay for different levels or separate sublists).
6. Indent sub-lists by the same amount as the item text;
this must be 4-7 spaces more than the symbol or number.
1. if enumerated, always start them with 1.
+ (the same rules apply to sub-sub-lists, etcetera)
Additional non-sub-list paragraphs require the same indentation;
example blocks (after double colon ``::``) must be indented at
least eight spaces more than the symbol or number, like this::
* item text::
code block
7. Indent symbols or numbers the same amount for any one list level.
- (top-level list items should not have any leading indentation)
8. Align two-digit enumerated items by first digit, not the period.
9. Don't put leading zeros on enumerated items to align the periods
* (use spaces after period if you want to align the item text in source).
10. Make sure there are no tab characters in initial indentation.
11. Always put a blank line after the end of a (top-level) list.
Mark bulleted lists with one of three symbols followed by a space:
- asterisk (
*) - hyphen (
-) - plus sign (
+)
- asterisk (
Mark enumerated lists with a number, period (
.) and a space.The choice of symbol does not affect the output bullet style, which is solely determined by nesting level. Items can be continued on following lines indented at the same level as the item text on the first line, and will flow and wrap normally.
The source indentation of item text can vary for different items (but continuation lines must be indented by the same amount as the item text that they are continuing).
Additional paragraphs of item text (after a blank line) also require this indentation, with the extra requirement that it be four to seven spaces more than the item symbol or number.
- These indentation requirements are the same for sub-list items (but apply to their symbol or number, not their item text).
Blank lines between list items are optional, avoid them.
- If you do use them (for items with sub-lists or extra paragraphs) put blank lines between all items at that level.
A non-list paragraph is required to separate adjacent enumerated and bulleted lists, to keep Markdown from merging the second one into the first (and using the first style for both).
Always put a blank line before the start of a list or sub-list.
Use the same bullet symbol for all items in a bulleted list.
Always start enumerated lists with 1.
Use sequentially increasing numbers for succeeding list items.
Do not mix numbers and/or different bullet symbols at one level
- (but this is okay for different levels or separate sublists).
Indent sub-lists by the same amount as the item text; this must be 4-7 spaces more than the symbol or number.
- if enumerated, always start them with 1.
- (the same rules apply to sub-sub-lists, etcetera)
Additional non-sub-list paragraphs require the same indentation; example blocks (after double colon
::) must be indented at least eight spaces more than the symbol or number, like this:* item text:: code block- if enumerated, always start them with 1.
Indent symbols or numbers the same amount for any one list level.
- (top-level list items should not have any leading indentation)
Align two-digit enumerated items by first digit, not the period.
Don't put leading zeros on enumerated items to align the periods
- (use spaces after period if you want to align the item text in source).
Make sure there are no tab characters in initial indentation.
Always put a blank line after the end of a (top-level) list.
Markdown and reStructuredText use different and incompatible syntax for
arbitrary text hyperlinks, but reStructuredText will generate hyperlinks
for e-mail addresses or URLs, and Markdown will do so as well if they
are enclosed in angle brackets (<>). Some Markdown processors do
not require the angle brackets, but there is little reason to omit them,
as they hardly affect readability, and explicitly specify whether or not
punctuation at the end of the URL is really part of the link. Even
relative URLs can be used if the protocol is explicitly specified:
The latest version of this document can be found at <https://gist.github.com/1855764>; if you are viewing it there (via HTTPS), you can download the Markdown/reStructuredText source at <https:/gists/1855764/download>. You can contact the author via e-mail at <[email protected]>.
The latest version of this document can be found at <https://gist.github.com/1855764>; if you are viewing it there (via HTTPS), you can download the Markdown/reStructuredText source at <https:/gists/1855764/download>. You can contact the author via e-mail at <[email protected]>.
(Using the URLs directly for hyperlinks also means that even if a Markdown processor has link generation disabled, a human reader can always copy and paste the URL.)
You can create a horizontal rule (a "transition" in reStructuredText
terminology) by placing four or more hyphens (-), asterisks (*),
or underscores (_) on a line by themselves, with blank lines before
and after and no indentation (trailing spaces are okay, but not leading
spaces). Although Markdown requires only three, and allows spaces
between them, reStructuredText requires four repeated punctuation
characters. Also, reStructuredText requires paragraphs before and after
the transition (code blocks or enumerated/bulleted list items are okay,
but section headers are not).
Each of the following lines will produce a horizontal rule like the one above:
**** ______ ----------
There are a few cases where Markdown or reStructuredText will interpret something as markup, although it is treated as ordinary text by the other, and these differences can cause problems for a document that is intended to be processed by either formatter. In these cases, the solution is usually to add a backslash before the markup character so that it is not treated specially by either markup processor.
While the appearance of square brackets - [] - in text is not treated specially by reStructuredText, some Markdown processors may attempt to format the contents as a hyperlink, even if there is no following parenthetical URL or bracketed reference. To prevent this, put a backslash before the opening square bracket (you can also put it before the closing square bracket, but this is optional).
Although Markdown only treats backslash as an escape character when it precedes certain characters, reStructuredText treats backslash as an escape unless it is followed by whitespace (in which case it removes the backslash and the whitespace). Because of this, a single backslash followed by whitespace, or a "C" escape like \n, that appears in Markdown will be "eaten" by reStructuredText. To prevent this, make sure to always escape any backslashes that you want to appear in the output.
Both Markdown and reStructuredText have markup that is not interpreted by the other (either in the same or in an incompatible way), and which is not too painful to read when rendered as ordinary text. Hyperlink URLs (as noted above) fall into this category for some basic Markdown implementations that do not implement URL recognition.
Markdown has no support for tables (one of its biggest weaknesses); to
create them requires embedded HTML (if that is even allowed). Some
variants have added table support (notably Pandoc Markdown, PHP
Markdown Extra, and GitHub Flavored Markdown [GFM]) but the syntax is
not consistent between all of them. The reStructuredText format has
the additional advantage of being quite readable in original source
form (basic monospaced ASCII layout). If you indent reStructuredText
tables by four or more spaces (and make sure that the previous paragraph
does not end with a double colon ::) you will get a nicely
formatted table in reStructuredText and a readable ASCII table in
Markdown. There are two flavors of table markup in reStructuredText,
grid tables and simple tables. Grid tables are trickier to generate, but
more flexible, and look nicer in source format:
Make sure previous paragraph does not end with ``::``. +-------+----------+------+ | Table Headings | Here | +-------+----------+------+ | Sub | Headings | Too | +=======+==========+======+ | cell | column spanning | + spans +----------+------+ | rows | normal | cell | +-------+----------+------+ | multi | * cells can be | | line | * formatted | | cells | * paragraphs | | too | | +-------+-----------------+
Make sure previous paragraph does not end with ::.
Table Headings Here Sub Headings Too cell spans rows column spanning normal cell multi line cells too
- cells can be
- formatted
- paragraphs
A significant advantage of grid tables is that Pandoc Markdown supports them, which is not the case for simple tables, for which Pandoc uses a somewhat similar but incompatible format. However, for Pandoc to actually process the formatting, the four space indentation of the grid tables must be removed (to prevent monospaced code block formatting).
Simple tables are easier, but cells must be on a single line and cannot span rows:
===== ========= ===== Table Headings Here --------------- ----- Sub Headings Too ===== ========= ===== column spanning no --------------- ----- cell cell row column spanning spans =============== =====
Note that lines between rows are optional and only needed to indicate where cells in the previous line span columns (by omitting the space).
Table Headings Here Sub Headings Too column spanning no cell cell row column spanning spans
Apart from the ability to span rows and do block formatting within cells in a grid table, the actual table formatting is not affected by the use of grid or simple tables, and depends only on the reStructuredText processor and any style sheets it may use; for more visual compatibility you may want to use the table style that most closely resembles the output table.
Conversely, if you have a reason to prefer the "pipe tables" format
defined by PHP Markdown Extra and supported by GitHub Flavored Markdown
and the latest version (1.10) of Pandoc, you can get reasonable results by
making sure that the previous paragraph does end with a double colon
:: which will make the table display as monospaced ASCII in
reStructuredText.
Colons can be used to align columns in pipe tables:
| Tables | Are | Cool | | ------------- |:-------------:| -----:| | col 3 is | right-aligned | $1600 | | col 2 is | centered | $12 | | zebra stripes | are neat | $1 |
Colons can be used to align columns in pipe tables:
| Tables | Are | Cool | | ------------- |:-------------:| -----:| | col 3 is | right-aligned | $1600 | | col 2 is | centered | $12 | | zebra stripes | are neat | $1 |
Also, just as for list indentation, it is a very good idea to make sure that no tab characters are embedded in the tables; configure your text editor to expand all tabs into spaces; this will help to ensure that the source ASCII display in reStructuredText or Markdown is properly aligned.
There is no comment syntax for Markdown, but HTML comments can be used with Markdown processors that allow them (raw HTML is often disabled for security or other reasons, possibly with whitelisted tags allowed; notably, GitHub and BitBucket README markdown disable HTML comments). Standard Markdown (but not most processors) requires blank lines before and after HTML blocks. Comments in reStructuredText use a different syntax, but it is possible to create comments that are entirely invisible in reStructuredText output, and only appear as periods in Markdown output (unless HTML comments are disabled).
In the following comment examples, the reStructuredText comment /
directive marker .. is followed by two more periods so that the
following blank line does not terminate the comment. For most Markdown
processors, you can use an entity instead of the two
additional periods to reduce the visual impact; but some Markdown
processors (notably the Python Markdown used by BitBucket README
processing) do not support entities outside of HTML blocks.
The following block is completely hidden from reStructuredText output, and barely visible in Markdown output if HTML comments are allowed:
.. .. <!--- Need blank line before this line (and the .. line above). HTML comment written with 3 dashes so that Pandoc suppresses it. Blank lines may appear anywhere in the comment. All non-blank lines must be indented at least one space. HTML comment close must be followed by a blank line and a line that is not indented at all (if necessary that can be a line with just two periods followed by another blank line). --->
You can also use a variation of the above to include Markdown markup that will be entirely ignored by reStructuredText:
.. .. <ul><li>Need blank line before this line (and .. line above).</li> <li>Blank lines may appear anywhere in this section.</li> <li>All non-blank lines must be indented at least one space.</li> <li>HTML and text are displayed only in Markdown output.</li></ul> <p>End of Markdown-only input must be followed by a blank line and a line that is not indented at all (if necessary that can be a line with just two dots followed by another blank line).</p>
You can use another variation of the above to include reStructuredText markup that will be ignored by Markdown (except for the periods):
.. .. <!--- Need blank line before this line (and the .. line above). HTML comment written with 3 dashes so that Pandoc suppresses it. These lines not starting with .. must be indented. HTML comment close must be followed by a blank line and a line that is not indented at all (if necessary that can be a line with just two periods followed by another blank line). .. note:: This is a reStructuredText directive - the Markdown output should be just periods .. --->
Note
This is a reStructuredText directive - the Markdown output should be just periods
Note that although HTML comments are usually marked with <!-- -->
you should use three dashes instead of two: <!--- ---> as this is
used by Pandoc to prevent passing the comment through to the output.
Unlike reStructuredText, which is virtually identical across all its implementations, there are a wide variety of semi-compatible Markdown extension styles; the most popular are MultiMarkdown and Markdown Extra (the latter implemented by PHP Markdown and Maruku, and partially by Python Markdown and Redcarpet); Pandoc has its own set of Markdown extensions, based on both Markdown Extra and reStructuredText; these Markdown extensions are the most similar to reStructuredText, while the Markdown Extra extensions have a smaller overlap, and the MultiMarkdown extensions are only compatible with reStructuredText when they are also identical to parts of Markdown Extra.
Markdown Extra, MultiMarkdown, and Pandoc support a syntax that is
fairly compatible with the definition list syntax in reStructuredText;
by using the following format, definitions can be written that are
recognized by all of these processors. In reStructuredText, any line
that is followed immediately by an indented line is a definition term,
with the following lines at the same indentation level forming the
definition. Markdown Extra allows an optional blank line between the
term and definition lines, but requires the definition to begin with a
colon (:) that is not indented by more than three spaces and is
followed by a space and the definition
To be recognized as a definition list item in both reStructuredText and Markdown extensions, only a single term is allowed, and it must be followed immediately (with no blank line) by the definition. The definition must begin with an (indented) colon and a space and it and any continuation lines or additional paragraphs or definitions must all be indented by the same amount (one to three spaces), as shown in the following example:
term : definition longer term : multi-line definition a second line (will be subject to flow and wrapping) a second paragraph in the definition complex term : first definition : second definition
- term
- : definition
- longer term
: multi-line definition a second line (will be subject to flow and wrapping)
a second paragraph in the definition
- complex term
: first definition
: second definition
Although most Markdown processors only support enumerated lists with
arabic numbers followed by periods, Pandoc also supports other list
styles that are compatible with reStructuredText. In particular,
letters (A) as well as roman numerals (IV) and alternate
punctuation with parentheses ( (b) or xiv) ) are recognized, and
sequences starting with numbers other than 1 (or roman numeral I or
letter A) have the actual starting number or letter preserved in output.