Skip to content

Instantly share code, notes, and snippets.

@benmezger

benmezger/README.rst

Forked from dupuy/README.rst
Created March 16, 2016 14:07
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save benmezger/9a788bb7480bc3a09757 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save benmezger/9a788bb7480bc3a09757 to your computer and use it in GitHub Desktop.
Download ZIP

Revisions

  1. @dupuy dupuy revised this gist May 21, 2013. 1 changed file with 102 additions and 6 deletions.
    108 changes: 102 additions & 6 deletions common-md-rst.md
    View file
    Original file line number Diff line number Diff line change
    @@ -96,11 +96,47 @@ For ``monospaced text``, use two "backquotes" instead.

    -----

    (Technically, Markdown uses just a single backquote for monospaced
    text, however two backquotes work with most or all Markdown processors,
    (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.)


    Escaping Markup
    ---------------
    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.


    Code or Console Example Blocks
    ------------------------------
    If you have example code or console text that you want to appear with
    @@ -545,6 +581,37 @@ one above::
    ----------


    Incompatibilities
    =================
    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.


    (Square) Brackets
    -----------------
    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).


    Solitary Backslash
    ------------------
    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.


    Not-Incompatible Extensions
    ===========================
    Both Markdown and reStructuredText have markup that is not interpreted
    @@ -557,9 +624,12 @@ implementations that do not implement URL recognition.
    Tables
    ------
    Markdown has no support for tables (one of its biggest weaknesses); to
    create them requires embedded HTML (if that is even allowed). However,
    the reStructuredText table format is fairly readable in original source
    form (basic monospaced ASCII layout) so if you indent reStructuredText
    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
    @@ -646,10 +716,36 @@ 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 Markdown is properly aligned.
    that the source ASCII display in reStructuredText or Markdown is
    properly aligned.


    Comments
  2. @dupuy dupuy revised this gist May 21, 2013. 1 changed file with 33 additions and 4 deletions.
    37 changes: 33 additions & 4 deletions README.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -624,9 +624,12 @@ implementations that do not implement URL recognition.
    Tables
    ------
    Markdown has no support for tables (one of its biggest weaknesses); to
    create them requires embedded HTML (if that is even allowed). However,
    the reStructuredText table format is fairly readable in original source
    form (basic monospaced ASCII layout) so if you indent reStructuredText
    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
    @@ -713,10 +716,36 @@ 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 Markdown is properly aligned.
    that the source ASCII display in reStructuredText or Markdown is
    properly aligned.


    Comments
  3. @dupuy dupuy revised this gist May 21, 2013. 1 changed file with 69 additions and 2 deletions.
    71 changes: 69 additions & 2 deletions README.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -96,11 +96,47 @@ For ``monospaced text``, use two "backquotes" instead.

    -----

    (Technically, Markdown uses just a single backquote for monospaced
    text, however two backquotes work with most or all Markdown processors,
    (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.)


    Escaping Markup
    ---------------
    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.


    Code or Console Example Blocks
    ------------------------------
    If you have example code or console text that you want to appear with
    @@ -545,6 +581,37 @@ one above::
    ----------


    Incompatibilities
    =================
    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.


    (Square) Brackets
    -----------------
    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).


    Solitary Backslash
    ------------------
    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.


    Not-Incompatible Extensions
    ===========================
    Both Markdown and reStructuredText have markup that is not interpreted
  4. @dupuy dupuy revised this gist Apr 11, 2013. 2 changed files with 2 additions and 2 deletions.
    2 changes: 1 addition & 1 deletion README.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -665,7 +665,7 @@ 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
    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
    2 changes: 1 addition & 1 deletion common-md-rst.md
    View file
    Original file line number Diff line number Diff line change
    @@ -665,7 +665,7 @@ 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
    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
  5. @dupuy dupuy revised this gist Mar 24, 2012. 2 changed files with 20 additions and 12 deletions.
    16 changes: 10 additions & 6 deletions README.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -201,19 +201,23 @@ 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 angle brackets, this allows up to three
    levels of quotation::
    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 angle brackets, a following block
    >> 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 third level of quotation is the maximum level possible.

    ..
    @@ -222,11 +226,11 @@ levels of quotation::
    the left (and possibly the right) margins, and may have a vertical
    quotation line on the left.

    >> With two spaces and two angle brackets, a following block
    >> 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 third level of quotation is the maximum level possible.

    ------

    16 changes: 10 additions & 6 deletions common-md-rst.md
    View file
    Original file line number Diff line number Diff line change
    @@ -201,19 +201,23 @@ 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 angle brackets, this allows up to three
    levels of quotation::
    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 angle brackets, a following block
    >> 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 third level of quotation is the maximum level possible.

    ..

    @@ -222,11 +226,11 @@ levels of quotation::
    the left (and possibly the right) margins, and may have a vertical
    quotation line on the left.

    >> With two spaces and two angle brackets, a following block
    >> 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 third level of quotation is the maximum level possible.
    ------

  6. @dupuy dupuy revised this gist Mar 24, 2012. 2 changed files with 20 additions and 4 deletions.
    12 changes: 10 additions & 2 deletions README.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -140,8 +140,8 @@ 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
    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.
    @@ -192,6 +192,12 @@ 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
    @@ -209,6 +215,8 @@ levels of quotation::

    >>> A third level of quotation is the maximum level possible.

    ..
    > 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
    12 changes: 10 additions & 2 deletions common-md-rst.md
    View file
    Original file line number Diff line number Diff line change
    @@ -140,8 +140,8 @@ 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
    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.
    @@ -192,6 +192,12 @@ 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
    @@ -209,6 +215,8 @@ levels of quotation::

    >>> A third level of quotation is the maximum level possible.

    ..

    > 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
  7. @dupuy dupuy revised this gist Mar 23, 2012. 1 changed file with 142 additions and 77 deletions.
    219 changes: 142 additions & 77 deletions README.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -1,6 +1,5 @@
    Markdown and reStructuredText
    =============================

    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
    @@ -12,7 +11,7 @@ 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). But as you add more sections and features, you may
    (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.
    @@ -23,6 +22,11 @@ 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
    @@ -36,7 +40,6 @@ installed.)

    The Common Denominator
    ======================

    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
    @@ -58,7 +61,6 @@ you may want to use multiple blank lines at the end of a section.

    Font Faces - Emphasis and Examples
    ----------------------------------

    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
    @@ -101,7 +103,6 @@ and are required for reStructuredText.)

    Code or Console Example Blocks
    ------------------------------

    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
    @@ -134,7 +135,6 @@ as you remember to use the double colon in your source.)

    Line Blocks and Hard Line Breaks
    --------------------------------

    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
    @@ -181,9 +181,55 @@ 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.)
    Block Quotations
    ----------------
    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).

    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 angle brackets, this allows up to three
    levels of quotation::

    > 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 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*
    ``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 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.)


    Titles and Section headers
    --------------------------
    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
    @@ -194,45 +240,43 @@ 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.


    Bulleted and Enumerated Lists
    -----------------------------

    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 symbol (``*``, ``-``, or ``+``) for bulleted
    lists, or a number and a period (``.``) for enumerated lists; in both
    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
    sub-list symbols or numbers. The initial indentation of the symbols or numbers
    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 items need not be the same.
    of different items need not be the same.

    Some Markdown processors (and reStructuredText) support list items
    with multiple paragraphs separated by blank lines and indented at the
    same level as continuation lines, but others (notably the one used by
    GitHub) do not. If unsupported, the separate paragraphs will split
    the list (restarting numbering at 1 for an enumerated list) and, if
    sufficiently indented, will actually appear as a code example block.
    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
    @@ -270,11 +314,11 @@ Markdown processors will combine adjacent bulleted and enumerated lists
    not enough to have a blank line, there must be a non-list paragraph
    between them.

    Because the formatting of lists requires initial indentation, note
    that the approach outlined above in *Code or Console Example Blocks*
    for monospaced paragraphs cannot be used. Although both Markdown and
    reStructuredText can support example blocks in lists, there is no
    common markup that can be used to do this.
    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
    @@ -286,11 +330,11 @@ 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:
    * Mark bulleted lists with one of three symbols followed by a space:

    1. asterisk (``*``)
    2. hyphen (``-``)
    3. plus sign (``+``)
    1. asterisk (``*``)
    2. hyphen (``-``)
    3. plus sign (``+``)

    * Mark enumerated lists with a number, period (``.``) and a space.

    @@ -300,15 +344,24 @@ lists compatible with Markdown and reStructuredText::
    level as the item text on the first line, and will flow and wrap
    normally.

    * Items can have a different source indentation of the item text.
    * 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.

    * Blank lines between list items are optional, avoid them.
    * These indentation requirements are the same for sub-list items
    (but apply to their symbol or number, not their item text).

    + If you *do* use them (for items with sub-lists) put blank
    lines between *all* items at that level.
    * 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 urging the second one into the
    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.
    @@ -319,37 +372,44 @@ lists compatible with Markdown and reStructuredText::

    4. Use sequentially increasing numbers for succeeding list items.

    5. Do not mix numbers and/or different bullet symbols at one level
    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.

    * (but this is okay for different levels or separate sublists).
    1. if enumerated, always start them with 1.

    6. Indent sub-lists by the same amount as the item text;
    + (the same rules apply to sub-sub-lists, etcetera)

    1. if enumerated, always start them with 1.
    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::

    + (the same rules apply to sub-sub-lists, etcetera)
    * item text::

    7. Indent symbols or numbers the same amount for any one list level.
    code block

    - (but the indentation of the item text may vary).
    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

    * (add space after the period to align the item text source).
    * (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. Don't put example (monospaced) blocks within lists.

    12. Always put a blank line after the end of a (top-level) list.
    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:
    * Mark bulleted lists with one of three symbols followed by a space:

    1. asterisk (``*``)
    2. hyphen (``-``)
    3. plus sign (``+``)
    1. asterisk (``*``)
    2. hyphen (``-``)
    3. plus sign (``+``)

    * Mark enumerated lists with a number, period (``.``) and a space.

    @@ -359,19 +419,24 @@ lists compatible with Markdown and reStructuredText::
    level as the item text on the first line, and will flow and wrap
    normally.

    Additional separate (unmarked) paragraphs are also possible, if
    separated by a blank line and indented to the same level as the
    text of the preceding item.
    * 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).

    * Items can have a different source indentation of the item text.
    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.

    * Blank lines between list items are optional, avoid them.
    * These indentation requirements are the same for sub-list items
    (but apply to their symbol or number, not their item text).

    + If you *do* use them (for items with sub-lists) put blank
    lines between *all* items at that level.
    * 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 urging the second one into the
    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.
    @@ -382,36 +447,42 @@ first (and using the first style for both).

    4. Use sequentially increasing numbers for succeeding list items.

    5. Do not mix numbers and/or different bullet symbols at one level
    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.

    * (but this is okay for different levels or separate sublists).
    + (the same rules apply to sub-sub-lists, etcetera)

    6. Indent sub-lists by the same amount as the item text;
    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::

    1. if enumerated, always start them with 1.
    * item text::

    + (the same rules apply to sub-sub-lists, etcetera)
    code block

    7. Indent symbols or numbers the same amount for any one list level.
    7. Indent symbols or numbers the same amount for any one list level.

    - (but the indentation of the item text may vary).
    - (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

    * (add space after the period to align the item text source).
    * (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. Don't put example (monospaced) blocks within lists.

    12. Always put a blank line after the end of a (top-level) list.
    11. Always put a blank line after the end of a (top-level) list.


    Hyperlink URLs
    --------------

    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
    @@ -442,15 +513,14 @@ always copy and paste the URL.)

    Horizontal Rules (Transitions)
    ------------------------------

    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,
    the transition (code blocks or enumerated/bulleted list items are okay,
    but section headers are not).

    -----
    @@ -465,7 +535,6 @@ one above::

    Not-Incompatible Extensions
    ===========================

    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
    @@ -475,7 +544,6 @@ implementations that do not implement URL recognition.

    Tables
    ------

    Markdown has no support for tables (one of its biggest weaknesses); to
    create them requires embedded HTML (if that is even allowed). However,
    the reStructuredText table format is fairly readable in original source
    @@ -574,7 +642,6 @@ that the source ASCII display in Markdown is properly aligned.

    Comments
    --------

    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;
    @@ -689,7 +756,6 @@ used by Pandoc to prevent passing the comment through to the output.

    Markdown Extensions
    ===================

    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
    @@ -753,7 +819,6 @@ complex term

    Fancy list numbers
    ------------------

    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,
  8. @dupuy dupuy revised this gist Mar 23, 2012. 1 changed file with 47 additions and 0 deletions.
    47 changes: 47 additions & 0 deletions common-md-rst.md
    View file
    Original file line number Diff line number Diff line change
    @@ -181,6 +181,53 @@ 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.)


    Block Quotations
    ----------------
    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).

    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 angle brackets, this allows up to three
    levels of quotation::

    > 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 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*
    ``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 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.)


    Titles and Section headers
    --------------------------
    Both Markdown and reStructuredText allow you to structure your document
  9. @dupuy dupuy revised this gist Mar 23, 2012. 1 changed file with 28 additions and 23 deletions.
    51 changes: 28 additions & 23 deletions common-md-rst.md
    View file
    Original file line number Diff line number Diff line change
    @@ -11,7 +11,7 @@ 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). But as you add more sections and features, you may
    (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.
    @@ -22,6 +22,11 @@ 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
    @@ -278,11 +283,11 @@ 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:
    * Mark bulleted lists with one of three symbols followed by a space:

    1. asterisk (``*``)
    2. hyphen (``-``)
    3. plus sign (``+``)
    1. asterisk (``*``)
    2. hyphen (``-``)
    3. plus sign (``+``)

    * Mark enumerated lists with a number, period (``.``) and a space.

    @@ -303,7 +308,7 @@ lists compatible with Markdown and reStructuredText::
    * 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.
    * 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.
    @@ -320,16 +325,16 @@ lists compatible with Markdown and reStructuredText::

    4. Use sequentially increasing numbers for succeeding list items.

    5. Do not mix numbers and/or different bullet symbols at one level
    5. Do not mix numbers and/or different bullet symbols at one level

    * (but this is okay for different levels or separate sublists).
    * (but this is okay for different levels or separate sublists).

    6. Indent sub-lists by the same amount as the item text;
    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.
    1. if enumerated, always start them with 1.

    + (the same rules apply to sub-sub-lists, etcetera)
    + (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
    @@ -339,7 +344,7 @@ lists compatible with Markdown and reStructuredText::

    code block

    7. Indent symbols or numbers the same amount for any one list level.
    7. Indent symbols or numbers the same amount for any one list level.

    - (top-level list items should not have any leading indentation)

    @@ -353,11 +358,11 @@ lists compatible with Markdown and reStructuredText::

    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:
    * Mark bulleted lists with one of three symbols followed by a space:

    1. asterisk (``*``)
    2. hyphen (``-``)
    3. plus sign (``+``)
    1. asterisk (``*``)
    2. hyphen (``-``)
    3. plus sign (``+``)

    * Mark enumerated lists with a number, period (``.``) and a space.

    @@ -378,7 +383,7 @@ lists compatible with Markdown and reStructuredText::
    * 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.
    * 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.
    @@ -395,16 +400,16 @@ first (and using the first style for both).

    4. Use sequentially increasing numbers for succeeding list items.

    5. Do not mix numbers and/or different bullet symbols at one level
    5. Do not mix numbers and/or different bullet symbols at one level

    * (but this is okay for different levels or separate sublists).
    * (but this is okay for different levels or separate sublists).

    6. Indent sub-lists by the same amount as the item text;
    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.
    1. if enumerated, always start them with 1.

    + (the same rules apply to sub-sub-lists, etcetera)
    + (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
    @@ -414,7 +419,7 @@ first (and using the first style for both).

    code block

    7. Indent symbols or numbers the same amount for any one list level.
    7. Indent symbols or numbers the same amount for any one list level.

    - (top-level list items should not have any leading indentation)

  10. @dupuy dupuy revised this gist Mar 23, 2012. 1 changed file with 61 additions and 35 deletions.
    96 changes: 61 additions & 35 deletions common-md-rst.md
    View file
    Original file line number Diff line number Diff line change
    @@ -206,27 +206,25 @@ 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 symbol (``*``, ``-``, or ``+``) for bulleted
    lists, or a number and a period (``.``) for enumerated lists; in both
    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
    sub-list symbols or numbers. The initial indentation of the symbols or numbers
    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 items need not be the same.
    of different items need not be the same.

    Some Markdown processors (and reStructuredText) support list items
    with multiple paragraphs separated by blank lines and indented at the
    same level as continuation lines, but others (notably the one used by
    GitHub) do not. If unsupported, the separate paragraphs will split
    the list (restarting numbering at 1 for an enumerated list) and, if
    sufficiently indented, will actually appear as a code example block.
    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
    @@ -264,11 +262,11 @@ Markdown processors will combine adjacent bulleted and enumerated lists
    not enough to have a blank line, there must be a non-list paragraph
    between them.

    Because the formatting of lists requires initial indentation, note
    that the approach outlined above in *Code or Console Example Blocks*
    for monospaced paragraphs cannot be used. Although both Markdown and
    reStructuredText can support example blocks in lists, there is no
    common markup that can be used to do this.
    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
    @@ -294,12 +292,21 @@ lists compatible with Markdown and reStructuredText::
    level as the item text on the first line, and will flow and wrap
    normally.

    * Items can have a different source indentation of the item text.
    * 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) put blank
    lines between *all* items at that level.
    + 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
    @@ -318,26 +325,33 @@ lists compatible with Markdown and reStructuredText::
    * (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.

    - (but the indentation of the item text may vary).
    - (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

    * (add space after the period to align the item text source).
    * (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. Don't put example (monospaced) blocks within lists.

    12. Always put a blank line after the end of a (top-level) list.
    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:

    @@ -353,16 +367,21 @@ lists compatible with Markdown and reStructuredText::
    level as the item text on the first line, and will flow and wrap
    normally.

    Additional separate (unmarked) paragraphs are also possible, if
    separated by a blank line and indented to the same level as the
    text of the preceding item.
    * 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).

    * Items can have a different source indentation of the item text.
    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) put blank
    lines between *all* items at that level.
    + 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
    @@ -381,26 +400,33 @@ first (and using the first style for both).
    * (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.

    - (but the indentation of the item text may vary).
    - (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

    * (add space after the period to align the item text source).
    * (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. Don't put example (monospaced) blocks within lists.

    12. Always put a blank line after the end of a (top-level) list.
    11. Always put a blank line after the end of a (top-level) list.


    Hyperlink URLs
  11. @dupuy dupuy revised this gist Mar 23, 2012. 1 changed file with 3 additions and 3 deletions.
    6 changes: 3 additions & 3 deletions common-md-rst.md
    View file
    Original file line number Diff line number Diff line change
    @@ -302,7 +302,7 @@ lists compatible with Markdown and reStructuredText::
    lines between *all* items at that level.

    A non-list paragraph is required to separate adjacent enumerated and
    bulleted lists, to keep Markdown from urging the second one into the
    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.
    @@ -365,7 +365,7 @@ lists compatible with Markdown and reStructuredText::
    lines between *all* items at that level.

    A non-list paragraph is required to separate adjacent enumerated and
    bulleted lists, to keep Markdown from urging the second one into the
    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.
    @@ -442,7 +442,7 @@ 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,
    the transition (code blocks or enumerated/bulleted list items are okay,
    but section headers are not).

    -----
  12. @dupuy dupuy revised this gist Mar 23, 2012. 1 changed file with 3 additions and 16 deletions.
    19 changes: 3 additions & 16 deletions common-md-rst.md
    View file
    Original file line number Diff line number Diff line change
    @@ -1,6 +1,5 @@
    Markdown and reStructuredText
    =============================

    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
    @@ -36,7 +35,6 @@ installed.)

    The Common Denominator
    ======================

    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
    @@ -58,7 +56,6 @@ you may want to use multiple blank lines at the end of a section.

    Font Faces - Emphasis and Examples
    ----------------------------------

    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
    @@ -101,7 +98,6 @@ and are required for reStructuredText.)

    Code or Console Example Blocks
    ------------------------------

    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
    @@ -134,7 +130,6 @@ as you remember to use the double colon in your source.)

    Line Blocks and Hard Line Breaks
    --------------------------------

    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
    @@ -183,7 +178,6 @@ usually no visual indication of whether they are there or not.)

    Titles and Section headers
    --------------------------

    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
    @@ -194,20 +188,20 @@ 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.


    Bulleted and Enumerated Lists
    -----------------------------

    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
    @@ -411,7 +405,6 @@ first (and using the first style for both).

    Hyperlink URLs
    --------------

    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
    @@ -442,7 +435,6 @@ always copy and paste the URL.)

    Horizontal Rules (Transitions)
    ------------------------------

    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
    @@ -465,7 +457,6 @@ one above::

    Not-Incompatible Extensions
    ===========================

    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
    @@ -475,7 +466,6 @@ implementations that do not implement URL recognition.

    Tables
    ------

    Markdown has no support for tables (one of its biggest weaknesses); to
    create them requires embedded HTML (if that is even allowed). However,
    the reStructuredText table format is fairly readable in original source
    @@ -574,7 +564,6 @@ that the source ASCII display in Markdown is properly aligned.

    Comments
    --------

    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;
    @@ -689,7 +678,6 @@ used by Pandoc to prevent passing the comment through to the output.

    Markdown Extensions
    ===================

    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
    @@ -753,7 +741,6 @@ complex term

    Fancy list numbers
    ------------------

    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,
  13. @dupuy dupuy revised this gist Feb 27, 2012. 2 changed files with 14 additions and 14 deletions.
    14 changes: 7 additions & 7 deletions README.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -164,14 +164,14 @@ applies to vertical bars between them, which appear in Markdown output::
    | Birds are weeping and the eyes
    | of fish fill with tears.
    |*Yuku haru ya*
    |*tori naki uo no*
    |*me wa namida*
    |-- **Matsuo Bashō**, The Narrow Road to Oku (*Oku no Hosomichi*),
    | *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.
    | Spring is passing by!
    | Birds are weeping and the eyes
    | of fish fill with tears.
    ------
    14 changes: 7 additions & 7 deletions common-md-rst.md
    View file
    Original file line number Diff line number Diff line change
    @@ -164,14 +164,14 @@ applies to vertical bars between them, which appear in Markdown output::
    | Birds are weeping and the eyes
    | of fish fill with tears.

    |*Yuku haru ya*
    |*tori naki uo no*
    |*me wa namida*
    |-- **Matsuo Bashō**, The Narrow Road to Oku (*Oku no Hosomichi*),
    | *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.
    | Spring is passing by!
    | Birds are weeping and the eyes
    | of fish fill with tears.

    ------

  14. @dupuy dupuy revised this gist Feb 27, 2012. 2 changed files with 18 additions and 22 deletions.
    26 changes: 12 additions & 14 deletions README.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -158,22 +158,20 @@ applies to vertical bars between them, which appear in Markdown output::
    | *Yuku haru ya*
    | *tori naki uo no*
    | *me wa namida*
    | Spring is passing by!
    | Birds are weeping and the eyes
    | Of fish fill with tears.
    | -- **Matsuo Bashō**, The Narrow Road to Oku (*Oku no Hosomichi*),
    Tokyo, 1996, p. 23 (Translation: Donald Keene)
    | *Yuku haru ya*
    | *tori naki uo no*
    | *me wa namida*
    | Spring is passing by!
    | Birds are weeping and the eyes
    | Of fish fill with tears.
    | -- **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.
    |*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.
    ------
    14 changes: 6 additions & 8 deletions common-md-rst.md
    View file
    Original file line number Diff line number Diff line change
    @@ -158,22 +158,20 @@ applies to vertical bars between them, which appear in Markdown output::
    | *Yuku haru ya*
    | *tori naki uo no*
    | *me wa namida*

    | Spring is passing by!
    | Birds are weeping and the eyes
    | Of fish fill with tears.
    | -- **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.

    |*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.
    |-- **Matsuo Bashō**, The Narrow Road to Oku (*Oku no Hosomichi*),
    Tokyo, 1996, p. 23 (Translation: Donald Keene)
    |of fish fill with tears.

    ------

  15. @dupuy dupuy revised this gist Feb 27, 2012. 1 changed file with 8 additions and 8 deletions.
    16 changes: 8 additions & 8 deletions common-md-rst.md
    View file
    Original file line number Diff line number Diff line change
    @@ -165,14 +165,14 @@ applies to vertical bars between them, which appear in Markdown output::
    | -- **Matsuo Bashō**, The Narrow Road to Oku (*Oku no Hosomichi*),
    Tokyo, 1996, p. 23 (Translation: Donald Keene)

    | *Yuku haru ya*
    | *tori naki uo no*
    | *me wa namida*

    | Spring is passing by!
    | Birds are weeping and the eyes
    | Of fish fill with tears.
    | -- **Matsuo Bashō**, The Narrow Road to Oku (*Oku no Hosomichi*),
    |*Yuku haru ya*
    |*tori naki uo no*
    |*me wa namida*

    |Spring is passing by!
    |Birds are weeping and the eyes
    |Of fish fill with tears.
    |-- **Matsuo Bashō**, The Narrow Road to Oku (*Oku no Hosomichi*),
    Tokyo, 1996, p. 23 (Translation: Donald Keene)

    ------
  16. @dupuy dupuy revised this gist Feb 27, 2012. 1 changed file with 4 additions and 0 deletions.
    4 changes: 4 additions & 0 deletions README.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -146,6 +146,10 @@ 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
  17. @dupuy dupuy renamed this gist Feb 27, 2012. 1 changed file with 0 additions and 0 deletions.
    0 common-md-rst.rst → README.rst
    View file
    File renamed without changes.
  18. @dupuy dupuy revised this gist Feb 27, 2012. 1 changed file with 4 additions and 0 deletions.
    4 changes: 4 additions & 0 deletions common-md-rst.md
    View file
    Original file line number Diff line number Diff line change
    @@ -146,6 +146,10 @@ 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
  19. @dupuy dupuy revised this gist Feb 27, 2012. 2 changed files with 12 additions and 12 deletions.
    12 changes: 6 additions & 6 deletions common-md-rst.md
    View file
    Original file line number Diff line number Diff line change
    @@ -651,17 +651,17 @@ 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

    .. --->

    .. ..
    @@ -672,10 +672,10 @@ markup that will be ignored by Markdown (except for the periods)::
    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
    .. --->

    -----
    @@ -693,7 +693,7 @@ 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
    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
    12 changes: 6 additions & 6 deletions common-md-rst.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -651,17 +651,17 @@ 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

    .. --->

    .. ..
    @@ -672,10 +672,10 @@ markup that will be ignored by Markdown (except for the periods)::
    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

    .. --->
    -----
    @@ -693,7 +693,7 @@ 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
    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
  20. @dupuy dupuy revised this gist Feb 27, 2012. 2 changed files with 14 additions and 14 deletions.
    14 changes: 7 additions & 7 deletions common-md-rst.md
    View file
    Original file line number Diff line number Diff line change
    @@ -94,7 +94,7 @@ For ``monospaced text``, use two "backquotes" instead.

    -----

    (Technically, Markdown uses just a single backquote for mono-spaced
    (Technically, Markdown uses just a single backquote for monospaced
    text, however two backquotes work with most or all Markdown processors,
    and are required for reStructuredText.)

    @@ -103,23 +103,23 @@ Code or Console Example Blocks
    ------------------------------

    If you have example code or console text that you want to appear with
    all line breaks and relative indentation preserved, in a monospace text
    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
    mono-spaced font without flow or word-wrapping::
    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 mono-spaced text, without flow or wrapping in most (non-print) cases.
    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 mono-spaced text, without flow or wrapping in most (non-print) cases.
    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.
    @@ -477,7 +477,7 @@ Tables
    Markdown has no support for tables (one of its biggest weaknesses); to
    create them requires embedded HTML (if that is even allowed). However,
    the reStructuredText table format is fairly readable in original source
    form (basic monospace ASCII layout) so if you indent reStructuredText
    form (basic monospaced ASCII layout) so 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
    @@ -525,7 +525,7 @@ 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 monospace code block formatting).
    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::
    14 changes: 7 additions & 7 deletions common-md-rst.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -94,7 +94,7 @@ For ``monospaced text``, use two "backquotes" instead.

    -----

    (Technically, Markdown uses just a single backquote for mono-spaced
    (Technically, Markdown uses just a single backquote for monospaced
    text, however two backquotes work with most or all Markdown processors,
    and are required for reStructuredText.)

    @@ -103,23 +103,23 @@ Code or Console Example Blocks
    ------------------------------

    If you have example code or console text that you want to appear with
    all line breaks and relative indentation preserved, in a monospace text
    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
    mono-spaced font without flow or word-wrapping::
    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 mono-spaced text, without flow or wrapping in most (non-print) cases.
    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 mono-spaced text, without flow or wrapping in most (non-print) cases.
    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.
    @@ -477,7 +477,7 @@ Tables
    Markdown has no support for tables (one of its biggest weaknesses); to
    create them requires embedded HTML (if that is even allowed). However,
    the reStructuredText table format is fairly readable in original source
    form (basic monospace ASCII layout) so if you indent reStructuredText
    form (basic monospaced ASCII layout) so 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
    @@ -525,7 +525,7 @@ 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 monospace code block formatting).
    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::
  21. @dupuy dupuy revised this gist Feb 27, 2012. 2 changed files with 94 additions and 0 deletions.
    47 changes: 47 additions & 0 deletions common-md-rst.md
    View file
    Original file line number Diff line number Diff line change
    @@ -132,6 +132,53 @@ 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.)


    Line Blocks and Hard Line Breaks
    --------------------------------

    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.

    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*

    | Spring is passing by!
    | Birds are weeping and the eyes
    | Of fish fill with tears.
    | -- **Matsuo Bashō**, The Narrow Road to Oku (*Oku no Hosomichi*),
    Tokyo, 1996, p. 23 (Translation: Donald Keene)

    | *Yuku haru ya*
    | *tori naki uo no*
    | *me wa namida*

    | Spring is passing by!
    | Birds are weeping and the eyes
    | Of fish fill with tears.
    | -- **Matsuo Bashō**, The Narrow Road to Oku (*Oku no Hosomichi*),
    Tokyo, 1996, p. 23 (Translation: Donald Keene)

    ------

    (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.)


    Titles and Section headers
    --------------------------

    47 changes: 47 additions & 0 deletions common-md-rst.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -132,6 +132,53 @@ 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.)


    Line Blocks and Hard Line Breaks
    --------------------------------

    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.
    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*
    | Spring is passing by!
    | Birds are weeping and the eyes
    | Of fish fill with tears.
    | -- **Matsuo Bashō**, The Narrow Road to Oku (*Oku no Hosomichi*),
    Tokyo, 1996, p. 23 (Translation: Donald Keene)
    | *Yuku haru ya*
    | *tori naki uo no*
    | *me wa namida*
    | Spring is passing by!
    | Birds are weeping and the eyes
    | Of fish fill with tears.
    | -- **Matsuo Bashō**, The Narrow Road to Oku (*Oku no Hosomichi*),
    Tokyo, 1996, p. 23 (Translation: Donald Keene)
    ------
    (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.)
    Titles and Section headers
    --------------------------
  22. @dupuy dupuy revised this gist Feb 27, 2012. 2 changed files with 46 additions and 18 deletions.
    32 changes: 23 additions & 9 deletions common-md-rst.md
    View file
    Original file line number Diff line number Diff line change
    @@ -27,7 +27,7 @@ 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
    <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
    @@ -364,17 +364,31 @@ Hyperlink URLs
    --------------

    Markdown and reStructuredText use different and incompatible syntax for
    hyperlinks; however, a literal URL will be converted into a hyperlink in
    reStructuredText, as well as by some Markdown processors::

    This Gist is at http://gist.github.com/1855764 (or https:).

    This Gist is at http://gist.github.com/1855764 (or https:).
    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]>.

    -----

    (Even with Markdown processors that do not convert the URL into an actual
    hyperlink, a human reader can always copy and paste the URL.)
    (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.)


    Horizontal Rules (Transitions)
    32 changes: 23 additions & 9 deletions common-md-rst.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -27,7 +27,7 @@ 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
    <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
    @@ -364,17 +364,31 @@ Hyperlink URLs
    --------------

    Markdown and reStructuredText use different and incompatible syntax for
    hyperlinks; however, a literal URL will be converted into a hyperlink in
    reStructuredText, as well as by some Markdown processors::

    This Gist is at http://gist.github.com/1855764 (or https:).

    This Gist is at http://gist.github.com/1855764 (or https:).
    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]>.

    -----

    (Even with Markdown processors that do not convert the URL into an actual
    hyperlink, a human reader can always copy and paste the URL.)
    (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.)


    Horizontal Rules (Transitions)
  23. @dupuy dupuy revised this gist Feb 27, 2012. 2 changed files with 150 additions and 75 deletions.
    107 changes: 71 additions & 36 deletions common-md-rst.md
    View file
    Original file line number Diff line number Diff line change
    @@ -513,74 +513,109 @@ Comments
    --------

    There is no comment syntax for Markdown, but HTML comments can be used
    (note that the Markdown standard requires HTML blocks to be preceded and
    followed by blank lines). Comments in reStructuredText have a different
    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 two periods in
    Markdown output (unless raw HTML is disabled)::
    invisible in reStructuredText output, and only appear as periods in
    Markdown output (unless HTML comments are disabled).

    .. &nbsp;

    <!--- Need blank line before this line (and .. &nbsp; line above).
    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 ``&nbsp;`` 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).
    --->

    .. &nbsp;
    .. ..

    <!--- 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.
    <!-- any HTML comment support at all? -->
    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::

    .. &nbsp;

    <!--- Need blank line before this line (and line above). --->
    <p>Raw HTML markup here will be passed through Markdown only.
    All non-blank lines must be indented at least one space.
    End of Markdown-only input must be followed by a blank line and
    .. ..

    <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>

    .. &nbsp;
    .. ..

    <!--- Need blank line before this line (and line above). --->
    <p>Raw HTML markup here will be passed through Markdown only.
    All non-blank lines must be indented at least one space.
    End of Markdown-only input must be followed by a blank line and
    <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 (except for the two periods and non-breaking space)
    ignored by Markdown::
    markup that will be ignored by Markdown (except for the periods)::

    .. &nbsp;
    .. ..

    <!--- Need blank line before this line (and .. &nbsp; line above).
    <!--- 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:: Markdown output should be just two periods and NBSP

    .. end of Markdown comment --->

    .. &nbsp;
    .. ..

    <!--- Need blank line before this line (and .. &nbsp; line above).
    <!--- 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.
    .. note:: Markdown output should be just two periods and NBSP
    .. end of Markdown comment --->
    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
    .. --->

    -----

    @@ -640,7 +675,7 @@ following example::

    term
    : definition

    longer term
    : multi-line definition
    a second line (will be subject to flow and wrapping)
    118 changes: 79 additions & 39 deletions common-md-rst.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -512,71 +512,110 @@ that the source ASCII display in Markdown is properly aligned.
    Comments
    --------

    Markdown does not actually have a comment syntax; but if raw HTML is
    allowed, HTML comments can be used. (Raw HTML in Markdown is disabled
    for security and other reasons on some sites, most notably GitHub and
    BitBucket README display.) Comments in reStructuredText have a different
    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 two periods in
    Markdown output (unless raw HTML is disabled)::
    invisible in reStructuredText output, and only appear as periods in
    Markdown output (unless HTML comments are disabled).

    .. <!--- This line must be preceded by a blank line.
    (HTML comment has 3 dashes so pandoc suppresses it)
    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 ``&nbsp;`` 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 dots followed by another blank line).
    with just two periods followed by another blank line).
    --->

    .. <!--- This line must be preceded by a blank line.
    (HTML comment has 3 dashes so pandoc suppresses it)
    .. ..
    <!--- 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 dots followed by another blank line).
    with just two periods followed by another blank line).
    --->
    -----

    You can often use a variation of the above to include Markdown markup
    You can also use a variation of the above to include Markdown markup
    that will be entirely ignored by reStructuredText::

    .. <!--- This line must be preceded by a blank line. --->
    <p>Raw HTML markup here will be passed through Markdown only.
    All non-blank lines must be indented at least one space.
    End of Markdown-only input must be followed by a blank line and
    .. ..

    <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>

    .. <!--- This line must be preceded by a blank line. --->
    <p>Raw HTML markup here will be passed through Markdown only.
    All non-blank lines must be indented at least one space.
    End of Markdown-only input must be followed by a blank line and
    .. ..
    <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 (except for the two periods) ignored by Markdown::

    .. <!--- start of Markdown comment
    markup that will be ignored by Markdown (except for the periods)::

    .. note:: Markdown output should contain two 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
    .. --->

    .. end of Markdown comment --->
    .. ..
    .. <!--- start of Markdown comment
    <!--- 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:: Markdown output should contain two periods (``..``)

    .. end of Markdown comment --->
    .. --->
    -----

    @@ -590,13 +629,14 @@ Markdown Extensions

    Unlike reStructuredText, which is virtually identical across all its
    implementations, there are a wide variety of semi-compatible Markdown
    extensions; the most popular are MultiMarkdown and Markdown Extra
    extension styles; the most popular are MultiMarkdown and Markdown Extra
    (the latter implemented by PHP Markdown and Maruku, and partially by
    Python Markdown); Pandoc has its own set of Markdown extensions, drawing
    from both Markdown Extra and reStructuredText. In general, the Pandoc
    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 not compatible with reStructuredText in any way.
    extensions are only compatible with reStructuredText when they are also
    identical to parts of Markdown Extra.

    Definition Lists
    ----------------
    @@ -635,7 +675,7 @@ following example::

    term
    : definition

    longer term
    : multi-line definition
    a second line (will be subject to flow and wrapping)
  24. @dupuy dupuy revised this gist Feb 27, 2012. 1 changed file with 1 addition and 9 deletions.
    10 changes: 1 addition & 9 deletions common-md-rst.md
    View file
    Original file line number Diff line number Diff line change
    @@ -533,15 +533,7 @@ Markdown output (unless raw HTML is disabled)::

    .. &nbsp;

    <!--- Need blank line before this line (and .. &nbsp; 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).
    --->
    <!-- any HTML comment support at all? -->

    -----

  25. @dupuy dupuy revised this gist Feb 27, 2012. 1 changed file with 38 additions and 25 deletions.
    63 changes: 38 additions & 25 deletions common-md-rst.md
    View file
    Original file line number Diff line number Diff line change
    @@ -512,49 +512,54 @@ that the source ASCII display in Markdown is properly aligned.
    Comments
    --------

    Markdown does not actually have a comment syntax; but if raw HTML is
    allowed, HTML comments can be used. (Raw HTML in Markdown is disabled
    for security and other reasons on some sites, most notably GitHub and
    BitBucket README display.) Comments in reStructuredText have a different
    There is no comment syntax for Markdown, but HTML comments can be used
    (note that the Markdown standard requires HTML blocks to be preceded and
    followed by blank lines). Comments in reStructuredText have a different
    syntax, but it is possible to create comments that are entirely
    invisible in reStructuredText output, and only appear as two periods in
    Markdown output (unless raw HTML is disabled)::

    .. <!--- This line must be preceded by a blank line.
    .. &nbsp;

    (HTML comment has 3 dashes so pandoc suppresses it)
    <!--- Need blank line before this line (and .. &nbsp; 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 dots followed by another blank line).
    with just two periods followed by another blank line).
    --->

    .. <!--- This line must be preceded by a blank line.

    (HTML comment has 3 dashes so pandoc suppresses it)
    .. &nbsp;

    <!--- Need blank line before this line (and .. &nbsp; 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 dots followed by another blank line).
    with just two periods followed by another blank line).
    --->

    -----

    You can often use a variation of the above to include Markdown markup
    You can also use a variation of the above to include Markdown markup
    that will be entirely ignored by reStructuredText::

    .. <!--- This line must be preceded by a blank line. --->
    .. &nbsp;

    <!--- Need blank line before this line (and line above). --->
    <p>Raw HTML markup here will be passed through Markdown only.
    All non-blank lines must be indented at least one space.
    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>

    .. <!--- This line must be preceded by a blank line. --->
    .. &nbsp;

    <!--- Need blank line before this line (and line above). --->
    <p>Raw HTML markup here will be passed through Markdown only.
    All non-blank lines must be indented at least one space.
    End of Markdown-only input must be followed by a blank line and
    @@ -564,17 +569,24 @@ that will be entirely ignored by reStructuredText::
    -----

    You can use another variation of the above to include reStructuredText
    markup that will be (except for the two periods) ignored by Markdown::
    markup that will be (except for the two periods and non-breaking space)
    ignored by Markdown::

    .. <!--- start of Markdown comment
    .. &nbsp;

    <!--- Need blank line before this line (and .. &nbsp; line above).
    These lines not starting with .. must be indented.

    .. note:: Markdown output should contain two periods (``..``)
    .. note:: Markdown output should be just two periods and NBSP

    .. end of Markdown comment --->

    .. <!--- start of Markdown comment

    .. note:: Markdown output should contain two periods (``..``)
    .. &nbsp;

    <!--- Need blank line before this line (and .. &nbsp; line above).
    These lines not starting with .. must be indented.
    .. note:: Markdown output should be just two periods and NBSP
    .. end of Markdown comment --->

    @@ -590,13 +602,14 @@ Markdown Extensions

    Unlike reStructuredText, which is virtually identical across all its
    implementations, there are a wide variety of semi-compatible Markdown
    extensions; the most popular are MultiMarkdown and Markdown Extra
    extension styles; the most popular are MultiMarkdown and Markdown Extra
    (the latter implemented by PHP Markdown and Maruku, and partially by
    Python Markdown); Pandoc has its own set of Markdown extensions, drawing
    from both Markdown Extra and reStructuredText. In general, the Pandoc
    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 not compatible with reStructuredText in any way.
    extensions are only compatible with reStructuredText when they are also
    identical to parts of Markdown Extra.

    Definition Lists
    ----------------
  26. @dupuy dupuy revised this gist Feb 26, 2012. 2 changed files with 26 additions and 10 deletions.
    18 changes: 13 additions & 5 deletions common-md-rst.md
    View file
    Original file line number Diff line number Diff line change
    @@ -512,10 +512,13 @@ that the source ASCII display in Markdown is properly aligned.
    Comments
    --------

    Markdown and reStructuredText have different and incompatible comment
    Markdown does not actually have a comment syntax; but if raw HTML is
    allowed, HTML comments can be used. (Raw HTML in Markdown is disabled
    for security and other reasons on some sites, most notably GitHub and
    BitBucket README display.) Comments in reStructuredText have a different
    syntax, but it is possible to create comments that are entirely
    invisible in reStructuredText output, and only appear as two periods in
    Markdown output::
    Markdown output (unless raw HTML is disabled)::

    .. <!--- This line must be preceded by a blank line.

    @@ -565,17 +568,22 @@ markup that will be (except for the two periods) ignored by Markdown::

    .. <!--- start of Markdown comment

    .. note:: Markdown output will contain two periods (``..``)
    in a ``<p>``aragraph
    .. note:: Markdown output should contain two periods (``..``)

    .. end of Markdown comment --->

    .. <!--- start of Markdown comment

    .. tip::
    .. note:: Markdown output should contain two periods (``..``)

    .. end of Markdown comment --->

    -----

    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.


    Markdown Extensions
    ===================
    18 changes: 13 additions & 5 deletions common-md-rst.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -512,10 +512,13 @@ that the source ASCII display in Markdown is properly aligned.
    Comments
    --------

    Markdown and reStructuredText have different and incompatible comment
    Markdown does not actually have a comment syntax; but if raw HTML is
    allowed, HTML comments can be used. (Raw HTML in Markdown is disabled
    for security and other reasons on some sites, most notably GitHub and
    BitBucket README display.) Comments in reStructuredText have a different
    syntax, but it is possible to create comments that are entirely
    invisible in reStructuredText output, and only appear as two periods in
    Markdown output::
    Markdown output (unless raw HTML is disabled)::

    .. <!--- This line must be preceded by a blank line.
    @@ -565,17 +568,22 @@ markup that will be (except for the two periods) ignored by Markdown::

    .. <!--- start of Markdown comment

    .. note:: Markdown output will contain two periods (``..``)
    in a ``<p>``aragraph
    .. note:: Markdown output should contain two periods (``..``)

    .. end of Markdown comment --->

    .. <!--- start of Markdown comment
    .. tip::
    .. note:: Markdown output should contain two periods (``..``)

    .. end of Markdown comment --->
    -----

    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.


    Markdown Extensions
    ===================
  27. @dupuy dupuy revised this gist Feb 26, 2012. 2 changed files with 310 additions and 4 deletions.
    157 changes: 155 additions & 2 deletions common-md-rst.md
    View file
    Original file line number Diff line number Diff line change
    @@ -388,8 +388,12 @@ 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::
    but section headers are not).

    -----

    Each of the following lines will produce a horizontal rule like the
    one above::

    ****
    ______
    @@ -456,6 +460,12 @@ Make sure previous paragraph does not end with ``::``.

    -----

    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 monospace code block formatting).

    Simple tables are easier, but cells must be on a single line and cannot
    span rows::

    @@ -497,3 +507,146 @@ 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 Markdown is properly aligned.


    Comments
    --------

    Markdown and reStructuredText have different and incompatible comment
    syntax, but it is possible to create comments that are entirely
    invisible in reStructuredText output, and only appear as two periods in
    Markdown output::

    .. <!--- This line must be preceded by a blank line.

    (HTML comment has 3 dashes so 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 dots followed by another blank line).
    --->

    .. <!--- This line must be preceded by a blank line.

    (HTML comment has 3 dashes so 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 dots followed by another blank line).
    --->

    -----

    You can often use a variation of the above to include Markdown markup
    that will be entirely ignored by reStructuredText::

    .. <!--- This line must be preceded by a blank line. --->
    <p>Raw HTML markup here will be passed through Markdown only.
    All non-blank lines must be indented at least one space.
    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>

    .. <!--- This line must be preceded by a blank line. --->
    <p>Raw HTML markup here will be passed through Markdown only.
    All non-blank lines must be indented at least one space.
    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 (except for the two periods) ignored by Markdown::

    .. <!--- start of Markdown comment

    .. note:: Markdown output will contain two periods (``..``)
    in a ``<p>``aragraph

    .. end of Markdown comment --->

    .. <!--- start of Markdown comment

    .. tip::

    .. end of Markdown comment --->


    Markdown Extensions
    ===================

    Unlike reStructuredText, which is virtually identical across all its
    implementations, there are a wide variety of semi-compatible Markdown
    extensions; the most popular are MultiMarkdown and Markdown Extra
    (the latter implemented by PHP Markdown and Maruku, and partially by
    Python Markdown); Pandoc has its own set of Markdown extensions, drawing
    from both Markdown Extra and reStructuredText. In general, the Pandoc
    Markdown extensions are the most similar to reStructuredText, while the
    Markdown Extra extensions have a smaller overlap, and the MultiMarkdown
    extensions are not compatible with reStructuredText in any way.

    Definition Lists
    ----------------
    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


    Fancy list numbers
    ------------------

    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.
    157 changes: 155 additions & 2 deletions common-md-rst.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -388,8 +388,12 @@ 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::
    but section headers are not).

    -----

    Each of the following lines will produce a horizontal rule like the
    one above::

    ****
    ______
    @@ -456,6 +460,12 @@ Make sure previous paragraph does not end with ``::``.

    -----

    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 monospace code block formatting).

    Simple tables are easier, but cells must be on a single line and cannot
    span rows::

    @@ -497,3 +507,146 @@ 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 Markdown is properly aligned.


    Comments
    --------

    Markdown and reStructuredText have different and incompatible comment
    syntax, but it is possible to create comments that are entirely
    invisible in reStructuredText output, and only appear as two periods in
    Markdown output::

    .. <!--- This line must be preceded by a blank line.
    (HTML comment has 3 dashes so 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 dots followed by another blank line).
    --->

    .. <!--- This line must be preceded by a blank line.
    (HTML comment has 3 dashes so 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 dots followed by another blank line).
    --->
    -----

    You can often use a variation of the above to include Markdown markup
    that will be entirely ignored by reStructuredText::

    .. <!--- This line must be preceded by a blank line. --->
    <p>Raw HTML markup here will be passed through Markdown only.
    All non-blank lines must be indented at least one space.
    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>

    .. <!--- This line must be preceded by a blank line. --->
    <p>Raw HTML markup here will be passed through Markdown only.
    All non-blank lines must be indented at least one space.
    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 (except for the two periods) ignored by Markdown::

    .. <!--- start of Markdown comment

    .. note:: Markdown output will contain two periods (``..``)
    in a ``<p>``aragraph

    .. end of Markdown comment --->

    .. <!--- start of Markdown comment
    .. tip::

    .. end of Markdown comment --->
    Markdown Extensions
    ===================

    Unlike reStructuredText, which is virtually identical across all its
    implementations, there are a wide variety of semi-compatible Markdown
    extensions; the most popular are MultiMarkdown and Markdown Extra
    (the latter implemented by PHP Markdown and Maruku, and partially by
    Python Markdown); Pandoc has its own set of Markdown extensions, drawing
    from both Markdown Extra and reStructuredText. In general, the Pandoc
    Markdown extensions are the most similar to reStructuredText, while the
    Markdown Extra extensions have a smaller overlap, and the MultiMarkdown
    extensions are not compatible with reStructuredText in any way.

    Definition Lists
    ----------------
    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


    Fancy list numbers
    ------------------

    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.
  28. Alexander Dupuy revised this gist Feb 22, 2012. 2 changed files with 4 additions and 4 deletions.
    4 changes: 2 additions & 2 deletions common-md-rst.md
    View file
    Original file line number Diff line number Diff line change
    @@ -274,7 +274,7 @@ lists compatible with Markdown and reStructuredText::

    * (but this is okay for different levels or separate sublists).

    6. Indent sub-lists by at least one more space than the item text;
    6. Indent sub-lists by the same amount as the item text;

    1. if enumerated, always start them with 1.

    @@ -337,7 +337,7 @@ first (and using the first style for both).

    * (but this is okay for different levels or separate sublists).

    6. Indent sub-lists by at least one more space than the item text;
    6. Indent sub-lists by the same amount as the item text;

    1. if enumerated, always start them with 1.

    4 changes: 2 additions & 2 deletions common-md-rst.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -274,7 +274,7 @@ lists compatible with Markdown and reStructuredText::

    * (but this is okay for different levels or separate sublists).

    6. Indent sub-lists by at least one more space than the item text;
    6. Indent sub-lists by the same amount as the item text;

    1. if enumerated, always start them with 1.

    @@ -337,7 +337,7 @@ first (and using the first style for both).

    * (but this is okay for different levels or separate sublists).

    6. Indent sub-lists by at least one more space than the item text;
    6. Indent sub-lists by the same amount as the item text;

    1. if enumerated, always start them with 1.

  29. Alexander Dupuy revised this gist Feb 22, 2012. 2 changed files with 29 additions and 43 deletions.
    44 changes: 14 additions & 30 deletions common-md-rst.md
    View file
    Original file line number Diff line number Diff line change
    @@ -172,29 +172,18 @@ 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 continuation lines or additional paragraphs of item text, or
    for additional item text on continuation lines, or
    sub-list symbols or numbers. The initial indentation of the symbols or numbers
    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 items need not be the same.

    Although reStructuredText and some Markdown processors support list
    items with multiple paragraphs, not all Markdown engines (notably the
    one used by GitHub) do; if unsupported, the text acts like a normal
    paragraph.

    1. this is a test
    2. this is a test
    with continuation
    3. this is a test
    with continuation

    and another paragraph
    4. this is a test
    5. this is a test with extra indentation

    this is not supposed to be an example block
    6. but perhaps it was
    Some Markdown processors (and reStructuredText) support list items
    with multiple paragraphs separated by blank lines and indented at the
    same level as continuation lines, but others (notably the one used by
    GitHub) do not. If unsupported, the separate paragraphs will split
    the list (restarting numbering at 1 for an enumerated list) and, if
    sufficiently indented, will actually appear as a code example block.

    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
    @@ -215,10 +204,9 @@ 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 the list has sub-lists or items with multiple
    paragraphs; in that case use blank lines between *all* the items at
    that level (sub-list items do not require the blank lines unless there
    are sub-sub-lists or sub-list items with multiple paragraphs).
    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
    @@ -263,16 +251,12 @@ lists compatible with Markdown and reStructuredText::
    level as the item text on the first line, and will flow and wrap
    normally.

    Additional separate (unmarked) paragraphs
    separated by a blank line and indented to the same level as the
    text of the preceding item.

    * Items can have a different source indentation of the item text.

    * Blank lines between list items are optional, avoid them.

    + If you *do* use them (for items with sub-lists or multiple
    paragraphs) put blank lines between *all* items at that level.
    + If you *do* use them (for items with sub-lists) 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 urging the second one into the
    @@ -334,8 +318,8 @@ lists compatible with Markdown and reStructuredText::

    * Blank lines between list items are optional, avoid them.

    + If you *do* use them (for items with sub-lists or multiple
    paragraphs) put blank lines between *all* items at that level.
    + If you *do* use them (for items with sub-lists) 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 urging the second one into the
    28 changes: 15 additions & 13 deletions common-md-rst.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -172,12 +172,19 @@ 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 continuation lines or additional paragraphs of item text, or
    for additional item text on continuation lines, or
    sub-list symbols or numbers. The initial indentation of the symbols or numbers
    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 items need not be the same.

    Some Markdown processors (and reStructuredText) support list items
    with multiple paragraphs separated by blank lines and indented at the
    same level as continuation lines, but others (notably the one used by
    GitHub) do not. If unsupported, the separate paragraphs will split
    the list (restarting numbering at 1 for an enumerated list) and, if
    sufficiently indented, will actually appear as a code example block.

    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
    @@ -197,10 +204,9 @@ 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 the list has sub-lists or items with multiple
    paragraphs; in that case use blank lines between *all* the items at
    that level (sub-list items do not require the blank lines unless there
    are sub-sub-lists or sub-list items with multiple paragraphs).
    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
    @@ -245,16 +251,12 @@ lists compatible with Markdown and reStructuredText::
    level as the item text on the first line, and will flow and wrap
    normally.

    Additional separate (unmarked) paragraphs are also possible, if
    separated by a blank line and indented to the same level as the
    text of the preceding item.

    * Items can have a different source indentation of the item text.

    * Blank lines between list items are optional, avoid them.

    + If you *do* use them (for items with sub-lists or multiple
    paragraphs) put blank lines between *all* items at that level.
    + If you *do* use them (for items with sub-lists) 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 urging the second one into the
    @@ -316,8 +318,8 @@ lists compatible with Markdown and reStructuredText::

    * Blank lines between list items are optional, avoid them.

    + If you *do* use them (for items with sub-lists or multiple
    paragraphs) put blank lines between *all* items at that level.
    + If you *do* use them (for items with sub-lists) 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 urging the second one into the
  30. Alexander Dupuy revised this gist Feb 22, 2012. 1 changed file with 19 additions and 1 deletion.
    20 changes: 19 additions & 1 deletion common-md-rst.md
    View file
    Original file line number Diff line number Diff line change
    @@ -178,6 +178,24 @@ 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 items need not be the same.

    Although reStructuredText and some Markdown processors support list
    items with multiple paragraphs, not all Markdown engines (notably the
    one used by GitHub) do; if unsupported, the text acts like a normal
    paragraph.

    1. this is a test
    2. this is a test
    with continuation
    3. this is a test
    with continuation

    and another paragraph
    4. this is a test
    5. this is a test with extra indentation

    this is not supposed to be an example block
    6. but perhaps it was

    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
    @@ -245,7 +263,7 @@ lists compatible with Markdown and reStructuredText::
    level as the item text on the first line, and will flow and wrap
    normally.

    Additional separate (unmarked) paragraphs are also possible, if
    Additional separate (unmarked) paragraphs
    separated by a blank line and indented to the same level as the
    text of the preceding item.