• The term 'markdown' in this document refers to GitHub Flavored Markdown.

  • Follow the syntax as specifed here.

Follow strict GFMD syntax to be compatible with GitHub Pages

Minor deviations from the markdown syntax are sometimes forgiven by GitHub markdown rendering but may not be forgiven by GitHub Pages html rendering.

  • Add a blank line at the beginning of a list.

    image

    Here is a list:

* item 1
* item 2

    image

    Here is a list:
* item 1
* item 2

  • Similar to above point, add a blank line at the beginning of a code block.

  • Add space at the start of a heading.

    image

    # Heading

    image

    #Heading

  • Use blockquote symbol in every line of the blockquote.

    image

    > first line
> second line

    image

    > first line
  second line

Use blank lines to separate headings

image

## Heading

Content of the paragraph.

image

## Heading
Content of the paragraph.

Use blockquotes for additional info

Blockquotes are usually used for additional info the reader can skip over.

image

> Some additional info.

Use generic numbering for ordered list

Using 1. for every item in an ordered list can make it easy to insert more items later.

Tip

Generic numbers are converted to the correct numbers by GitHub markdown renderer.

image

1. item 1
1. item 2
1. item 3

image

1. item 1
2. item 2
3. item 3