Markdown is a powerful text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).
Thus, “Markdown” is two things:
- a plain text formatting syntax
- a software, written in Perl, that converts the plain text formatting to HTML
In other words, wrinting a content with markdown, asks you to start by formating with its syntax and structuring your text deciding what is a header, what is a parageaph, etc, in order to transform it, in an almost direct way, into an html page. The translated document, will be then, as any html page, accompagnied by a stylesheet file, where we will decide how the header or the paragraph will look like, if it's red, big and underline for example. Which means that at this formating level of your document is not the place to decide wether you want your header to be bold and capitalized. For now, you just want to decide which kind of content it is. The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible by human eyes which makes it a very easy synthax to understand and write.
In the following sections, you'll find the Markdown formating syntax in detail and some examples.
The best way to learn the Markdown’s formatting syntax is simply to look at a Markdown-formatted document. Like this one, for example. In passing from to "read mode" to the "write mode", you will be able to get a direct feel for how to use it.
Paragraphs and Line Breaks
A paragraph is simply one or more consecutive lines of text, separated by one or more blank lines. (A blank line is any line that looks like a blank line — a line containing nothing but spaces or tabs is considered blank.) Normal paragraphs should not be indented with spaces or tabs because as for choosing a color, indenting a paragraph is part of the styling of the document, not structuring part of it.
You can specify 6 level of headers. They use 1-6 hash characters at the start of the line, corresponding to header levels 1-6. For example:
This is an H1
#This is an H1
This is an H2
##This is an H2
this is an H6
######This is an H6
There two possible way to emphasize words in italic:
Emphasize in surrounding your words with an asterix
emphasize the same way but with underscores
There is also two possible way to emphasise words in strong:
You can emphasise and format words as bold in surrounding it before and after with two double asterix
with two double underscores
You can write 2 types of lists.
The ordered ones, useful when to give an order and number to a list:
- This is our first step
- This is our second step
But you might also just want to write a list without any specific order:
- this is the begining of my unordered list starting with a "- "
- in other words: a dash followed by least one space
- but you can also use a "* "
- an asterisks followed by least one space
- or a "+ "
- a plus followed by least one space
N.B.: List markers must be followed by one or more spaces or a tab.
For blockquoting you should use the charctere > before each line:
This a blockquote with two paragraphs.
The idea is to add the caracter ">" before each lines. Even the empty ones.
or each paragraph:
This is also a blockquote with two paragraphs.
But here we just added the caracter ">" at the begining of each paragraph.
Blockquotes can be nested (a blockquote in a blocquote) like this:
This is the first lever of quoting.
This is nested blockquote.
Here we come back to the first level of the quote.
Blockquotes can contain other Markdown elements, including headers, lists etc:
Here we have a header in a blockquote
- Then we start an ordered list.
- With 2 elements.
You can produce a horizontal rule tag (
<hr />) by placing three or more hyphens, asterisks, or underscores on a line by themselves. If you wish, you may use spaces between the hyphens or asterisks. Each of the following lines will produce a horizontal rule:
* * *
- - -
To write a link you simply have to (the text you want to appear has to be in between parenthesis) and the [the url it refers to inbetween brakets]:
[Contoure Biennale 8](http://www.contourmechelen.be/)
If you’re referring to a local resource on the same server, you can use relative paths:
Not all the html tags are coverd by Markdown synthax. Mostly because the goal of Markdown is not to replace HTML but more to make it more easy to read in a read/edit mode environement. However for any markup that is not covered by Markdown’s syntax, you simply use HTML itself. There’s no need to preface it or delimit it to indicate that you’re switching from Markdown to HTML; you just use the tags.
The only restrictions are that block-level HTML elements — e.g.
<div>, <table>, <pre>, <p>, etc. — must be separated from surrounding content by blank lines, and the start and end tags of the block should not be indented with tabs or spaces. Markdown is smart enough not to add extra (unwanted)
tags around HTML block-level tags.