Markdown is a lightweight markup language that:

  • is very easy to pick up;
  • can be converted into many file formats such as PDF, DOCX, EPUB, HTML, etc. using Pandoc;
  • can generate diagrams such as UML Sequence Diagrams, Flowcharts, Class and State Diagrams;
  • can be used to create a static site, using the static generator MkDocs.

Markdown Editor GitHub Gist

For those of you without a Markdown editor installed, I recommend the usage of either or GitHub Gist. provides live preview of your Markdown syntax together with the formatted content, allowing one to update the Markdown syntax and view the changes instantly.

As for GitHub Gist, live previews are provided in a separate tab for comments on GitHub. The actual gists do not allow for one to preview the formatting of the Markdown syntax. But it would be familiar to get used to the GitHub interface, as we would use it for the creation of the website later.


What you type What you get
# This is an h1 tag h1
## This is an h2 tag h2
### This is an h3 tag h3
#### This is an h4 tag h4
##### This is an h5 tag h5
###### This is an h6 tag h6

Headers are written in Markdown syntax using the hash or pound sign (#).

They are equivalent to the HTML headings from <h1> to <h6>, and widely used in Markdown documents as sectioning elements.


What you type What you get
*This will be italic* This will be italic
_This will also be italic_ This will also be italic
**This will be bold** This will be bold
__This will also be bold__ This will also be bold
_You **can** combine them_ You can combine them

Bold and italic text can be formatted in Markdown syntax using asterisks (*) or underscores (_).

1 asterisk or underscore for italics, 2 asterisks or underscores for bold text.

Markdown also allows the flexibility of combining bold and italic text together.


Unordered Lists

What you type What you get
ul preview ul actual

For unordered lists, asterisks (*), hyphens (-) and pluses (+) can be used interchangeably as list markers.

To begin an unordered list, use a list marker, followed by a space between the list marker and the list item.

To create a unordered sublist within the unordered list, add 2 spaces followed by the list marker.

Ordered Lists

What you type What you get

Ordered list begin with 1., followed by a space between the ordinal marker and the list item.

To create an ordered sublist with the ordered list, add 2 spaces followed by the ordinal sublist marker in lowercase Roman numerals (i.).

What you type What you get
[GitHub]( GitHub

In Markdown, web URLs are automatically recognized as rendered as hyperlinks.

You can also customise the link text by enclosing it in square brackets [ ] and placing the actual URL in brackets ( ) after the square brackets.


What you type What you get
![SUTD logo]( SUTD logo

Images written in Markdown syntax are similar to links, except that they begin with an exclamation mark (!).

The text in square brackets [ ] is the alternate text of the image and will be displayed when the image is unable to load.


What you type What you get
table preview table

To create tables in Markdown syntax, the cells in each row are separated by a vertical bar or pipe (|).

A table will be generated once the second row of Markdown syntax is input. It consists of three hyphen characters (---) for each cell separated by vertical bars (|) between each cell.

Regular Markdown syntax applies within the table as well.

Inline code

What you type What you get
I think you should use an `<addr>` element here instead. I think you should use an <addr> element here instead.

Inline code snippets can be included by adding back-ticks (`) around the code snippet.

Indenting by 4 spaces will turn an entire paragraph into a code block.

Syntax highlighting

What you type What you get
syntax preview syntax
syntax 2 preview syntax 2

Markdown supports the syntax highlighting of keywords in programming languages.

By enclosing the code block in 3 back-ticks (```) at the beginning and end of the code block and indicating the programming language after the initial 3 back-ticks, the syntax of the code will be highlighted as expected.


What you type What you get
> We're living the future so the present is our past. blockquote

Blockquotes are typically used to reply in email and conversation threads, or otherwise highlight some key phrases.

They can be written in Python by adding a right angle bracket (>) before the quote.

Works with HTML

Markdown insufficient? You can add HTML code into Markdown and it will still work.

But take note NOT to mix Markdown syntax and HTML code together in a single line.

It will not work.