Markdown is a markup language designed to be simple enough to let anyone write structured documents without the need of a visual editor
I strongly encourage you to change the source of the various parts to see what happens (the output will change as you type)
With this markup you can obtain simple emhpasis (usually rendered in italic text), strong emphasis (usually rendered in bold text), source code text (usually rendered in monospaced text), or strikethrough text (usually rendered with a line through text).
You may use also this or this notation to emphatize text, and you can use all them together (and you can mix * and _ )
If you look at the source code you may note that even if you break the lines, the text is kept together in a single paragraph
Paragraphs are delimited by blank lines, leading and trailing spaces are removed
You may force a line break with two spaces
or with a \
at the end of the line
To define a list of items, just put a *, a -, or a + at the start of the line of each item of the list followed by at least a space, to end the list, leave a blank line
- red
- green
- blue
- white
- grey
- black
- yellow
- pink
- orange
You can also define numbered list, putting a number followed by a . or a ) and a space at the start of the line (you may use any number, the first one is taken to start counting, then it will increment by one):
- you may leave blank items
- or start
- again
You can insert any block inside a list, you have to respect the indentation of the text of the list item
-
A paragraph of text (spanning multiple lines),
fenced code,indented code (4 spaces + 2 spaces for the list indentation, one blank line above, one below),quotes,
-
another
- list
- (and so on...),
- list
-
There are two ways to define headers:
(I prefer the first one as it's more readable when looking directly at the source code)
The good thing is that many tools that convert Markdown in HTML or PDF are able to generate the index of your document, or links to the headers automatically (like Github does on the source of Markdown files)
You can use horizontal rules to separate paragraphs: you may use three or more *
or three or more _ (you may insert spaces before, after or between the characters, no other charachters are allowed)
or three (or more) -
but you have to be careful as it is similar to the header syntax, so if you write --- immediatly after a single line of text you get an header, either you have to leave a blank line before the ---, or you put it after multiple lines of text
If you have to insert code in your document you have three choices:
- inline code like this:
*Hello* **world!**" - fenced code blocks (you may use
```or~~~as delimiters):
*Hello* **world!**-
indented code blocks
Hello
world!
You need to leave a blank linke after a paragraph and 2 blank lines after a list to start an indented code block (if you want the code to be out of the list), and you may insert the name of the language immediatly after the opening code fence (so some renderers may be able to highlight the syntax of the language)
In this way you define a quoted block of text. You can skip the initial
>in intermediate lines if you are in the same paragraph(you may nest levels)
> but you can't indent with more than 3 spaces
Text between < and > that looks like an HTML tag is parsed as a raw HTML tag and will be rendered in HTML
While it may be useful when writing online content, please note that your tag may be stripped for security reasons and in output other than HTML you may have unexpected results
Look I'm right!
This is the list of allowed html tags (case insensitive):
article, header, aside, hgroup, blockquote, hr, iframe, body, li, map, button, object, canvas, ol,caption, output, col, p, colgroup, pre, dd, progress, div, section, dl,table, td, dt, tbody, embed,textarea, fieldset, tfoot, figcaption, th, figure, thead, footer, tr, form, ul, h1, h2, h3, h4, h5, h6, video, script, style
With the goal of making Markdown as HTML-agnostic as possible, all valid HTML entities are recognized and converted into unicode characters
Named entities consist of & + any of the valid HTML5 entity names + ;
Some examples:
&&©©→→
If you have to write something that would result in a Markdown vaild syntax, you can escape the first character of your expression (you may also escape any other punctuation character) with a \
*not emphasized*
<br/> not a tag
[not a link](/foo)
`not code`
1. not a list
* not a list
# not a header
[foo]: /url "not a reference"
You may also escape the backslash itself \like this
You can read the Wikipedia article, if you want more information about Markdown.
There are several Markdown flavours, this tutorial is based on the Commonmark specification.
You may want to read the full Commonmark specification
The source code for this tutorial is on Github