Markdown Markup

This page introduces you to the most important elements of the Markdown syntax. For details on the Python implementation of Markdown see https://python-markdown.github.io/

In addition to being supported by moin2, the Markdown markup language is used by issue trackers such as those found in Bitbucket and Github. So what you learn here can be used there also.

Features currently not working with moin’s Markdown parser are marked with MDTODO.

This page, describing the Markdown syntax, is written in reST. Instances where reST cannot duplicate the same rendering produced by Markdown are flagged with reST NOTE. The reST parser used by Moin and the parser used by Sphinx are different. As noted below there are several instances where one works and the other fails.

Table of Contents

The table of contents is a supported extension that is distributed with Python Markdown.

Markup:

[TOC]

Result:

Headings

Level 1 and 2 headings may be created by underlining with = and - characters, respectively.

Having equal numbers of characters in the heading and the underline looks best in raw text, but having fewer or more = or - characters also works.

Heading levels 3 through 6 must be defined by prefixing the heading with a variable number of # characters indicating the heading level. Heading levels 1 and 2 may be defined in the same manner. It is customary, but not required, to follow the # characters with a single space character. Another option is to append the appropriate number of # characters after the heading text.

Markup:

Level 1
=======

# Level 1

Level 2
-------

## Level 2

### Level 3

#### Level 4

##### Level 5

###### Level 6 ######

Result:

Level 3

Level 4

Level 5

Level 6

NOTE: Levels 1 and 2 are not shown above to avoid adding unwanted entries to the table of contents. See the top of this page for an approximate view of a level 1 heading and next section heading below for level 2.

Preformatted Code

To show a preformatted block of code, indent all the lines by 4 or more spaces.

Markup:

Begin preformatted code

   First line
   Second line
       Third line

End of preformatted code

Result:

Begin preformatted code

First line
Second line
    Third line

End of preformatted code

Simple text editing

Markup:

Paragraphs are separated
by a blank line.

To create a line break, end a line
with 2 spaces.

Use asterisk characters to create text attributes: *italic*, **bold**, ***bold italics***.
Or, do the same with underscores: _Italics_, __bold__, ___bold italics___.
Use backticks to create `monospace`.

Result:

Paragraphs are separated by a blank line.

To create a line break, end a line

with 2 spaces.

Use asterisk characters to create text attributes: italic, bold, bold italics. Or, do the same with underscores: Italics, bold, bold italics. Use backticks to create monospace.

reST Note: The moin reST parser will indent the second paragraph above.

Linking

Markdown supports two style of links: inline and reference.

Inline Links

Inline links use the form:

[link text](url "optional title")

Markup	Result
[home page](Home)	home page
[home item](Home “my home page”)	home item
[a sub item](Home/subitem)	a sub item
[toc1](markdown#table-of-contents)	toc1
[toc2](#table-of-contents)	toc2
[moinmoin](https://moinmo.in “Go there”)	moinmoin
[](Home “click me”)	png image

reST NOTE: Links with title attributes and images as links are not supported in reST. The internal links above are broken.

Wikilinks

Wikilinks use the form:

[[PageName]]

Markup	Result
[[Page]]	Page
[[Page/Subpage]]	Subpage

This features uses the mdx_wikilink_plus extension.

Reference Links

Reference links have two parts. Somewhere in the document the link label is defined using a unique id; this has no visible output. Then the reference link uses a form with square brackets rather than parens:

[id]: url "optional title"

[link text] [id]

Markup	Result
[apple]: https://www.apple.com/
[MoinMoin]: https://moinmo.in/ “go!”
[see apples][apple]	see apples
[go to MoinMoin][MoinMoin]	go to MoinMoin

reST NOTE: Links with title attributes are not supported in reST.

Lists

Unordered lists may use *, +, or - characters as bullets. The character used as a bullet does not effect the display. The display would be the same if * characters were used everywhere.

Markup:

* apples
* oranges
* pears
    - carrot
    - beet
        + man
        + woman
    - turnip
* cherries

Result:

• apples

• oranges

• pears

  • carrot

  • beet

    • man

    • woman

  • turnip

• cherries

reST NOTE: As shown above and below, the Sphinx rendering of ordered and unordered lists shows excessive spacing between levels.

Ordered lists use numbers and are incremented in regular order. Neither alpha characters nor roman numerals are supported. Although you may use numbers other than 1 with no adverse effect (as shown below), it is a best practice to always start a list with 1.

Markup:

1. apples
1. oranges
7. pears
    1. carrot
    1. beet
        1. man
        1. woman
    1. turnip
1. cherries

Result:

1. apples

2. oranges

3. pears

   1. carrot

   2. beet

      1. man

      2. woman

   3. turnip

4. cherries

Lists composed of long paragraphs are easier to read in raw text if the lines are manually wrapped with optional hanging indents. If multiple paragraphs are required, separate the paragraphs with blank lines and indent.

Markup:

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

Result:

• Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

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

• Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

• Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

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

Horizontal Rules

To create horizontal rules, use 3 or more -, *, or _ on a line. Neither changing the character nor increasing the number of characters will change the width of the rule. Putting spaces between the characters also works.

Markup:

---

text

- - - - - -

more text

******

more text

______

Result:

---

text

---

more text

---

more text

---

Backslash Escapes

Sometimes there is a need to use special characters as literal characters, but Markdown’s syntax gets in the way. Use the backslash character as an escape.

Markup:

*hot*

333. is a float, 333 is an integer.

\*hot\*

333\. is a float, 333 is an integer.

Result:

hot

333. is a float, 333 is an integer.

*hot*

333. is a float, 333 is an integer.

reST NOTE: The Moin reST parser flags the use of 333 as a bullet number.

Nested Blockquotes

Advanced blockquotes with nesting are created by starting a line with a > character.

Markup:

> A standard blockquote is indented
> > A nested blockquote is indented more
> > > You can nest to any depth.

Result:

A standard blockquote is indented

A nested blockquote is indented more

You can nest to any depth.

Images

Images are similar to links with both an inline and a reference style, but they start with an exclamation point. Within Markdown, there is no syntax to change the default sizes or positions of transclusions:

Markup:

To transclude image from local wiki:
![Alt text 1](png "Optional title")

Reference-style, where "logo" is a name defined anywhere within this item:
![Alt text 2][logo]

Image references are defined using syntax identical to link references and
do not appear in the rendered HTML:
[logo]: png  "Optional title attribute"

To transclude image from remote site:
![remote image](http://static.moinmo.in/logos/moinmoin.png)

Result:

To transclude image from local wiki:

Reference-style, where “logo” is a name defined anywhere within this item:

Image references are defined using syntax identical to link references and do not appear in the rendered HTML:

To transclude image from remote site:

reST NOTE: The Moin reST parser renders all three images above. The Sphinx parser renders only the external png image from http://static.moinmo.in/logos/moinmoin.png. reST syntax does not allow the rendering of inline images, nor the use of a title attribute. The logos above are floated right, in Markdown the logos would appear as inline images.

Inline HTML

Note: Use of the style attribute within HTML tags is dependent upon configuration settings. See configuration docs for information on allow_style_attributes.

You may embed a small subset of HTML tags directly into your markdown documents.

<a>              - hyperlink.
<b>              - bold, use as last resort <h1>-<h3>, <em>, and <strong> are preferred.
<blockquote>     - specifies a section that is quoted from another source.
<code>           - defines a piece of computer code.
<del>            - delete, used to indicate modifications.
<dd>             - describes the item in a <dl> description list.
<dl>             - description list.
<dt>             - title of an item in a <dl> description list.
<em>             - emphasized.
<h1>, <h2>, <h3> - headings.
<i>              - italic.
<img>            - specifies an image tag.
<kbd>            - shows keyboard input.
<li>             - list item in an ordered list <ol> or an unordered list <ul>.
<ol>             - ordered list.
<p>              - paragraph.
<pre>            - pre-element displayed in a fixed width font and unchanged line breaks.
<s>              - strikethrough.
<sup>            - superscript text appears 1/2 character above the baseline used for footnotes and other formatting.
<sub>            - subscript appears 1/2 character below the baseline.
<strong>         - defines important text.
<strike>         - strikethrough is deprecated, use <del> instead.
<ul>             - unordered list.
<br>             - line break.
<hr>             - defines a thematic change in the content, usually via a horizontal line.

Markup:

E = MC<sup>2</sup>

This word is <b>bold</b>.

This word is <em>italic</em>.

This word is <strong>bold</strong>.

This word is <strong style="color:red;background-color:yellow">bold</strong>;
colors depend upon configuration settings.

Result:

E = MC²

This word is bold.

This word is italic.

This word is bold.

This word is bold; colors depend upon configuration settings.

reST NOTE: The moin reST parser will flag the above as an error because it does not support the raw directive.

Extensions

In addition to the TOC extension shown near the top of this page, the following features are installed as part of the “extras” extension.

Tables

All tables must have one heading row. By default table headings are centered and table body cells are aligned left. Use a “:” character on the left, right or both sides of the heading-body separator to change the alignment. Changing the alignment changes both the heading and table body cells.

As shown in the second table below, use of outside borders and neat alignment of the cells do not effect the display. Markup within the table cells is supported.

Markup:

| Tables            |Are            |Very  |Cool    |
|-------------------|:-------------:|-----:|:-------|
| col 2 is          |centered       |$12   |Gloves  |
| col 3 is          |right-aligned  |$1600 |Necklace|
| col 4 is          |left-aligned   |$100  |Hat     |

`Tables`            |*Are*            |Very  |Cool
------------|:-------------:|-----:|:-------
`col 2 is`|*centered*|$12|Gloves
`col 3 is`|*right-aligned*|$1600|Necklace
`col 4 is`|*left-aligned*|$100|Hat

Result:

Tables	Are	Very	Cool
col 2 is	centered	$12	Gloves
col 3 is	right-aligned	$1600	Necklace
col 4 is	left-aligned	$100	Hat

Tables	Are	Very	Cool
col 2 is	centered	$12	Gloves
col 3 is	right-aligned	$1600	Necklace
col 4 is	left-aligned	$100	Hat

reST NOTE: reST does not support cell alignment, therefore the last example shown above does not reflect the resulting alignment.

Syntax Highlighting of Preformatted Code

A second way to create a block of preformatted code without indenting every line is to wrap the block in triple backticks.

To highlight code syntax, wrap the code in triple backtick characters and specify the language on the first line. Many languages are supported.

Markup:

``` javascript
var s = "JavaScript syntax highlighting";
alert(s);
```

~~~ {python}
def hello():
   print "Hello World!"
~~~

Result:

var s = "JavaScript syntax highlighting";
alert(s);

def hello():
   print "Hello World!"

reST NOTE: reST supports some generic highlighting of indented blocks. The Moin Markdown highlighting is more colorful and varies per language.

Fenced Code

Another way to display a block of preformatted code is to “fence” the code with lines starting with three ~ characters.

Markup:

~~~
ddd
eee
fff
~~~

Result:

ddd
eee
fff

Smart Strong

The smart strong extension prevents words with embedded double underscores from being converted. e.g. double__underscore__words is wanted, not double`**underscore**`words.

Markup:

Text with double__underscore__words.

__Strong__ still works.

__this__works__too__.

Result:

Text with double__underscore__words.

Strong still works.

this__works__too.

Attribute Lists

Markup:

A class of LawnGreen  (that will create a greenish background per a CSS rule) is
added to this paragraph.
{: class="LawnGreen "}

A `{: #para3 }` id was added to the 3rd paragraph on this page,
so [click to see 3rd paragraph](#para3).

Result:

A class of lawnGreen (that will create a greenish background per a CSS rule) is added to this paragraph.

A {: #para3 } id was added to the 3rd paragraph on this page, so click to see 3rd paragraph.

reST NOTE: The moin reST parser will flag the first example above as an error because it does not support the raw directive.

Definition Lists

Markup:

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

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

Result:

Apple

Pomaceous fruit of plants of the genus Malus in the family Rosaceae.

An american computer company.

Orange

The fruit of an evergreen tree of the genus Citrus.

Footnotes

The syntax for footnotes in Markdown is rather unique.[^unique] Place any unique label after the characters “[^” and close the label with a “]”. The footnote text may be placed after the reference on a new line using the label, followed by a “:”, followed by the footnote text. All footnotes are placed at the bottom of the document under a horizontal rule in the order defined.

[^unique]: Markdown footnotes are unique.

Markup:

Footnotes[^1] have a label[^label] and a definition[^!DEF].

[^1]: This is a footnote
[^label]: A footnote on "label"
[^!DEF]: The footnote for definition

Result:

Footnotes [1] have a label [2] and a definition [3].

[1]

This is a footnote

[2]

A footnote on “label”

[3]

The footnote for definition

Admonition

The Admonition extension adds rST-style admonitions to Markdown.

Syntax:

!!! type "optional explicit title within double quotes"
    Any number of other indented markdown elements.

    This is the second paragraph.

If you don’t want a title, use a blank string “”.

The following types are supported:

• attention

• caution

• danger

• error

• hint

• important

• note

• tip

• warning

Markup:

!!! note
You should note that the title will be automatically capitalized.

Result:

Note

You should note that the title will be automatically capitalized.