This blog used to use the RDiscount gem which wraps the Discount C-language library (now it's Jekyll). Like seemingly every Markdown implementation, Discount provides it's own extensions to the syntax. This is an attempt to document the complete syntax and not just the extensions.

Paragraphs

One or more consecutive lines of text without any blank lines is output as an HTML paragraph. A blank line is a "visibly" blank line. So a line consisting of nothing but tabs or spaces is considered a blank line.

If you actually want a hard break (a <br/> tag) you must end a line with two or more spaces.

Headers

Headers can be specified by typing characters under text or by adding leading hash characters.

Text can be underlined with equals ('=') to specify a first level header (<h1> tag), or text can be underlined with dashes ('-') to specify a second level header (<h2> tag). The number of underlining characters don't have to match the number of characters in the heading. If you specify a header with leading hashes instead of underlines, the number of leading hashes is the header level. There has to be at least one trailing hash character but the number of trailing hashes don't have to match the number of leading hashes.

  This is an H1
  =============
  
  This is an H2
  -------------
  
  # This is an H1 #
  
  ## This is an H2 ##
  
  ### This is an H3 #

Emphasis

Any words or sections of words surrounded by asterisks or underlines are highlighted for emphasis.

Text with a single '*' or '_' preceding and following the text are wrapped with HTML <em> tags. A double '**' or '__' will result in the text being wrapped with <strong> tags. Depending on the stylesheet this means a single '*' or '_' will cause the text to be italicized while a double '**' or '__' which cause it to be bolded.

  *I will be italicized*
  _So will I_
  **I will be bolded**
  __So will I__

This works even in the middle of words. The '*' or '_' will be ignored if it's surrounded with spaces. You can escape the '*' and '_' if you want it output instead of interpreted, e.g., '\*'.

Block quotes

Block quotes are specified "email style". A leading greater than sign ('>') and space is placed at the beginning of each block quoted line.

  > This is a block quoted section of text.  It can wrap,
  > to later lines.
  >
  > Blank lines need to be prefixed too.

A hard-wrapped paragraph only needs a single '>' at the beginning of the paragraph, not one for each line. You can specify multiple levels of block quotes by adding more levels of leading '>' characters.

  > First line of block quote.
  Continuation of first block quote line.
  > > Second level of block quote.

Markdown syntax can be used inside a block quote.

Lists

Both ordered (numbered) and unordered (bulleted) lists are supported. Unordered lists have leading asterisks, pluses or dashes. Ordered lists are numbers followed by periods. The numbers in ordered lists don't have to be correct. You can number every line with '1.' if you like, the browser will take care of numbering them correctly. Even though the numbers don't have to be correct, you should still start numbered lists with a '1.'.

  * Item 1
  * Item 2
  * Item 3
  
  + Item 1
  + Item 2
  + Item 3
  
  - Item 1
  - Item 2
  - Item 3
  
  1. Item 1
  2. Item 2
  3. Item 3

List items separated by blank lines will have each <li> item wrapped in a <p> tag. This means you can have multiple paragraphs in a single list item.

  *   This is a list item with two paragraphs.

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

  *   Another item in the same list.

To include a block quote in a list, indent the block quote. To include a code section in a list, indent it twice.

Code

Code can be specified in a block or inline.

Any text indented by four spaces or one tab is wrapped in a <pre> tag. This is how you write a block of code. You use backtick quotes to write a short section of code. Text between backtick quotes (`) is wrapped with the <code> tag.

An "inline" code definition:

  `a = x(45)`

A "block" of code, each line is indented by a tab or four spaces.

  [tab]a = x(45)
  [tab]b = a + 2
  [tab]c = a * b

The result is that "inline" code is output with a surrounding <code> tag while a block of code is output inside a surrounding <pre> tag.

Regardless of the method used, Markdown syntax is turned off inside code blocks and HTML is escaped.

Links

Links are written in either "inline" (immediate) style or in "reference" style. The link text is written in square quotes, e.g., "[My link text]". For immediate links, you follow the square brackets with the URL in parentheses, e.g., "[My link text](http://link.com)".

Reference links move the URLs out of the line of text. They look like footnotes:

  [My link text]
  [My second link][second-link]
  
  [my link text]: http://link.com "Text to display on hover"
  [second-link]: http://anotherlink.com

You can use either style interchangeably. The reference note for the link is written in lowercase. If you want some text to display when the user hovers over a link, add a space after the URL and then write the hover text in quotes.

There is a shorthand for when you just want URLs to be clickable. Surround the URL with angled brackets:

  <http://clickme.com>

This actually works for more then just URLs. You can surround email addresses with angled brackets and they will be turned into clickable mailto links. Markdown will also attempt to obscure the email address from spammers though its not 100% effective.

There are additional "pseudo-protocols" you can use in place of the link URL:

  • abbr:description - The label will be wrapped with an <abbr> tag.
  • class:name - The label will be wrapped with a <span class="name"> tag
  • id:name - The label will be wrapped with a <a id="name"> tag
  • raw:text - The text will be written verbatim to output and not processed
  [IBM](abbr:International Business Machines)

Images

Images are written just like links. The only difference is that the square brackets are prefixed with an exclamation point. Just like regular links you can use immediate or reference style.

  ![My image link text](http://images.com/image.png)

Discount adds a small extension to provide image dimensions. After the URL, type a space and then an equals and the width and height separated by a 'x':

  ![My image link text](http://images.com/image.png =150x50)

Tables

Simple tables can be written out using dashes and pipes.

   aaa | bbbb
  -----|------
  hello|sailor
  next | line

The example will create a table with header cells containing 'aaa' and 'bbbb'. The first line of the table will contain cells of 'hello' and 'sailor'. The second line of the table will contain cells of 'next' and 'line'.

You can control horizontal alignment of the columns by using a colon. A colon on the left will force left alignment (the default). A colon on the right will force right alignment. A colon on both sides will center the column.

   aaa | bbbb
  :----|:----:
  hello|sailor
  next | line

In the above example the first column will be left aligned and the second will be centered.

Horizontal Rules

Horizontal rules (lines) are created by writing three or more asterisks, dashes or underlines. There can be spaces between them. All of the following examples will result in a horizontal rule.

  * * *
  ----------
  ___

Centering

You can center text by surrounding it with arrows (-> and <-).

  ->this will be centered<-

HTML

You can use regular HTML in Markdown text. Markdown will ignore them and pass them through untouched. Block-level elements (div, table, pre, p) need to have leading and trailing blank lines and shouldn't be indented.

Markdown formatting works inside non block-level elements (span, cite, etc.) but is turned off inside block-level elements. So you can't use Markdown formatting inside a div, pre, p or table tag.

Special Characters

Some "special" characters are escaped automatically. These are conversions to typographic alternatives.

  1. & becomes &amp;. It's ignored when it's part of an HTML character specification.
  2. < becomes &lt;.
  3. ``text’’ becomes “text”</li>
  4. "double quotes" becomes “double quotes”
  5. 'single quotes' becomes ‘single quotes’
  6. don't becomes don’t, and it's becomes it’s. But anything other then 't and 's is ignored.
  7. (tm) becomes
  8. (r) becomes ®
  9. (c) becomes ©
  10. 1/4 becomes ¼. This also works for 1/2 and 3/4. The fraction can have a trailing 'th' as well, e.g., 1/2th.
  11. ... and . . . becomes …
  12. -- becomes
  13. - becomes . Embedded dashes are ignored.
  14. A^B becomes AB.
  15. </ol>

    Escaping

    If you accidentally trigger Markdown syntax you can use a slash ('\') to escape a sequence of characters. So, to avoid having a leading number followed by a period trigger an ordered list, escape the period, e.g., '1986\.'.

    To avoid having embedded asterisks or underlines trigger emphasis, you can escape them the same way.

    If that's not sufficient, use the 'raw:' pseudo-protocol to output text without formatting.


    All of the information on this page and some of the text comes from: