Markdown is a minimalist publishing and text formatting system. It’s more and more widely used and I will to my best to help you learn it fast.
Contents
- What is Mardown ?
- Some history
- Tool box
- Markdown syntax
- Titles
- Paragraphs
- Emphasis
- Quote block
- Unordered list
- Ordered list
- Code block
- Inline code
- Hairline or separator
- Links
- Images
- Tables
- Escaping characters
- Blocks separations
- And after?
What is Mardown ?
Markdown is a publishing and text formatting system; this is at the same time a syntax, a conversion script text → HTML and a file format. It is commonly used for the documentation files of a project or a dataset. In this case, the document is often named readme.md. It is stored in text format and is lighter than its converted version since it does not contains html tags.
The philosophy of the system is that the written text should be readable without special interpreter in text mode. It is light and clean. Syntax elements are punctuation characters that make sense visually, even before conversion. Once converted, the web browser (which then acts as interpreter) helps to improve readability.
The files are usually saved with .md extension (or .markdown) to indicate to your software the nature of the text that it has to read. But it is not mandatory.
As the result will be exported HMTL, you can introduce HTML tags in your text. But it will become less readable and can no longer be edited by someone not proficient in HTML. The markdown formatting will not be applied within these tags.
Some history
This language has been created in 2004 by John Gruber and Aaron Swartz and has not changed since. Although many extensions and “extras” have been added to the original project. The initial project documentation is on daringfireball.
From the begining, Gruber wrote a Perl script to convert markdown text in XHTML. That’s the whole point of the system: edit a simple text file with some additional special characters, then pass it through a script that will add the tags required to display formated text in the browser.
Today there are many implementations in various languages of the base script with some variations to generate richer outputs. You will use at least those of GitHub for project documentation and Stack Overflow, to post your questions and answers.
These implementations are not necessarily compatible with each other and each one introduce a few idioms. Except in cas of very specific need, it is reasonable to stick to the possibilities of the original implementation.
Guide of the implementation of GitHub. Guide of the implementation of Stack Overflow.
Toolbox
To discover markdown and see what it can do, you can try one of the many online editors like markable, the original publisher of Gruber: Dingus"> or the powerful stack edit. You can sync this one with google docs.
There are also many offline editors. This tutorial is written with one of them: Mou for Mac OS (free). Byword is also a good application for Mac Os / iOS (paying app). Note that byword syncs across all your devices. For Windows, there is Write Monkey ; a little austere for my taste, but very functional and free. Windows also have Markdown Pad (free). For Linux, there’s Retext.
It is possible to open and edit markdown files with any text editor (like notepad or textedit that comes with your operating system). But they lack syntax highlighting and real-time preview.
The path to mastery is practice, I strongly advise you to use Mardown Here. An extension for Chrome, Firefox and Safari which converts the typed markdown in html. You will use to format your emails for example.
Markdown syntax
Titles
There are two syntaxes for titles. They produce the same result, so you can use either of them. Just try to be consistent in your documents.
Exported HTML title is hx where x is the title level. The Level 1 titles are the most important, and the importance decreases with the number.
The underline method allow only two levels of titles. You have to underline your text by two or more characters. The = for an h1 and - for an h2.
It is also possible to indicate title by adding the sharps in the begining of the line. There is no limit to how many levels of headings you can produce with this method (but do not go beyond 7). For this reason, I recommend this syntax.
It is also possible to close the securities by one or more sharps, but it is purely cosmetic.
*** Markdown Code ***
*********************
Title 1
==
Title 2
-
### Title 3 #
#### Title 4*** HTML export ***
*******************
<h1>Title 1</h1>
<h2>Title 2</h2>
<h3>Title 3</h3>
<h4>Title 4</h4>Paragraphs
To display a paragraphe, skip one line and type the text. A single line break is a carriage return and does not appear in the export. HTML formatting is as follows:
*** HTML export ***
*******************
<p>a paragraph</p>Emphasis
To format text as part of your focus, surround it with asterisks or underscores. Surrounded by a single sign makes it italic (low emphasis *;) and a double sign makes it bold (strong emphasis **;). It is possible to combine both. Double tilde allow you to overline your text. Personally, I’d rather use the asterisks, but it is a matter of taste. The only important thing is to be consistent in your documents.
*** Markdown Code ***
*********************
Text _with_ some formatted __elements__ **to _be_** *italic*, **bold** or ~~overlined~~*** HTML export ***
*******************
Text <em>with</em> some formatted <strong>elements</strong> <strong> to <em>be</em></strong> <em>italic</em>, <strong>bold</strong> or <del>overlined</del>Quote block
To display a quote block, start the paragraph with a closing chevron (angle bracket). If your block should contain multiple lines, you can make line breaks by hand and all open by a closing angle bracket, but it is not necessary. This block can contain other elements like titles or lists.
*** Markdown Code ***
*********************
> A quote block is opened by a closing chevron*** HTML export ***
*******************
<blockquote>A quote block is opened by a closing chevron</blockquote>Unordered list
To display a list, begin the line with an asterisk * less - or a +. Again, the choice does not matter, but we must be consistent in your document. I tend to use the asterisk since this is is a little closer to the bullet point that will be displayed in the browser.
*** Markdown Code ***
*********************
* item
* item
* item
-
+ item
+ item
+ item
-
- item
- item
- item*** HTML export ***
*******************
<ul>
<li>item</li>
<li>item</li>
<li>item</li>
</ul>Ordered lists
To display an ordered list, start the line with a number followed by a period. To make your markdown source more readable, I recommend you to properly order your list. But this is not mandatory to get aproper HTML output. As you can see in the html export, the only difference with the unordered list is that the tag exported is ol and not ul. This is the browser adds the numbers to the ordered list.
*** Markdown Code ***
*********************
1. Item
1234. Item
3. Item
4. Item*** HTML export ***
*******************
<ol>
<li>item</li>
<li>item</li>
<li>item</li>
</ol>The code block
To display a block of code, skip one lines as for paragraph, then indent with 4 spaces or a tabulation. The block will end as soon as he arrives on a non-indented line.
code*** HTML export ***
*******************
<pre><code>code</code></pre>The inline code
To display inline code, enclose the quotation mark slashes code online : (`).
`code`*** HTML export ***
*******************
<code>code</code>Hairline or separator
To display a separator, you have thre options. Write <hr/>, write at least 3 asterisks * or write at least three less sign -. It has to be in a line surrounded by two empty lines. It is possible to separate the signs by one or more spaces. Do what makes the most sense for you and stay consistent in your documents.
*** Markdown Code ***
*********************
***
---
- - -
* * **** HTML export ***
*******************
<hr/>links
You have two options to display a link. First, you can surrond a link with chevrons. It will generate a clickable link with the same content and href.
*** Markdown Code ***
*********************
<http://www.google.com>*** HTML export ***
*******************
<a href="http://google.com">http://www.google.com</a>You also can add parametters. You write the text you want to display betwen brackets, followed by the link address in parentheses. Then, following the link, you can add a title in quotation marks. The title will be displayed when hovering the link in the browser. It will also be read by text browsers for the visually impaired. This method is more verbose when editing the document, but are more elegant when export. It will therefore be preferred to the first.
*** Markdown Code ***
*********************
[google] (http://www.google.com "link to google")*** HTML export ***
*******************
<a href="http://www.google.com" title="link to google">google</a>Images
To display an image, start by an exclamation point. Then specify the alternative text between brackets (this will be displayed if the image is not loaded and read by the search engines). Finish with image URL between parentheses. This URL can be a link to the web or a local path. After this picture, it is possible to add a title read by text browsers and displayed over the image by others.
*** Markdown Code ***
*********************
*** HTML export ***
*******************
<img src = "https://www.google.fr/images/srpr/logo11w.png" title = "google logo" alt = "Google logo">
tables
The tables do not exist in the original markdown specification, but they are present in almost all recent implementations. And it really has a very high value in some cases.
The idea is to “draw” columns by surrounding them with pipes |. The number of columns defined in the first row and for each row you must have the same number of columns, even if some are empty.
The first line will be your header. The second line separates the header from the body of the table and sets the alignment of text in columns. It contains only the dash - and colon(s) :. Colons are used to define the text alignment. No : or just on at left means that the text will be left-aligned. If the line of - is surrounded by 2 :, the text will be centered and with only one : in the right of a line, the text will be right-aligned.
*** Markdown Code ***
*********************
| Header 1 | 2 header | header 3 |
| ------------- |: -------------: | ---------: |
| 1 Online | 1 | value |
| Line 2 | 2 | value |
| 3 Online | 3 | value |
Result displayed in the browser:| Header 1 | 2 header | header 3 |
|---|---|---|
| 1 Online | 1 | value |
| Line 2 | 2 | value |
| 3 Online | 3 | value |
*** HTML export ***
*******************
<table>
<thead>
<tr>
<th>header 1</th>
<th align="center">header 2</th>
<th align="right">header 3</th>
</tr>
</thead>
<tbody>
<tr>
<td>line 1</td>
<td align="center">1</td>
<td align="right">value</td>
</tr>
<tr>
<td>row 2</td>
<td align="center">2</td>
<td align="right">value</td>
</tr>
<tr>
<td>line 3</td>
<td align="center">3</td>
<td align="right">value</td>
</tr>
</tbody>
</table>You can write a very clean table as in the previous example to ease reading in edit mode. But this is not mandatory.
The | starting and ending the lines are optional. It is possible to embed elements of emphasis or code in the tables. There is need of only one - per column for the separation between the header and the body of the table.
*** Markdown Code ***
*********************
1 header | header 2 | 3 header
- |:-: | -:
line `1` | **1** | **_valeur_**
Line 2 | 2 | *Value*Result displayed in the browser:
| 1 header | header 2 | 3 header |
|---|---|---|
line 1 | 1 | valeur |
| Line 2 | 2 | Value |
As you can see, it still works when exported, but all the readability in the markdown is far worst.
Escaping characters
Special characters with a speacial application in HTML or markdown must be escaped.For ampersands &, angle brackets < and other HTML characters markdown is handle the convertion in HTML entities when exporting. But if you want to use asterisks, brackets, sharps… in your text that could be markdown formatters, you need to escape them by preceding them with a backslash \. Markdown if the mask and apply the appropriate formatting. The following characters are escaped:
\ * `- _ [] () {} + #. !Blocks separations
When writing markdown, you could encounter a little annoying thing about block separation : two consecutive blocks can be merged. For example, two quotes blocks following each other. This will happen regardless of the number of lines you skip. A simple solution is to add html comments between two blocks. Comment syntax is as follows: <!-- comment text -->. The text will be ignored by the browser. Your comment may be empty.
*** Markdown Code ***
*********************
> Quote 1
> Quote 2Result displayed in the browser:
Quote 1
Quote 2
*** Markdown Code ***
*********************
> Quote 1
<!-- -->
> Quote 2Result displayed in the browser:
Quote 1
Quote 2
And after?
Once a markdown published, the most common use is to put it online. In a Git repo for example. But you can also print pdf or save as HTML into a web page. This is very useful for documenting a project or dataset.
There are advanced scripts to export in more advanced formats like LaTeX to build complex PDFs.