Markdown is a file type that allows us to easily and quickly format text documents. It is really common on internet and we find it in almost every repositories, specially as a README file.
Here we present some syntaxis used in md files so you can easily start styling your text files:
1. Headings << Back to Summary >>
Headings are used to create titles. The font size is bigger and more strong, and it adds blank space on top and bottom of the title. The main important Heading, equivalent to an H1 in HTML, is formated by used a #. Subtitles are created addind ##s. Normally you will have only one # title (H1) on your document, that's the main title. And all the other topics should be subtitles (from ## to ######);
Below, you can see what you have to type and the results you get. Note that the space after the # is mandatory, or title won't be generated:
Typed text:
# My main title
Results:
Typed text:
## My subtitle
Results:
Typed text:
### My subtitle (3rd level)
Results:
Typed text:
#### My subtitle (4th level)
Results:
Typed text:
##### My small subtitle (5th level)
Results:
Typed text:
###### My very small subtitle (6th level)
Results:
note: as a special case, you could also create a main title (# - H1) or a subtitle (## - H2) using === or --- below the text. But normally you would do it using with # or ## as seen above, it is easier and more common. See the examples:
Typed text:
My main title
===
Results:
Typed text:
My subtitle
---
Results:
2. Font styles << Back to Summary >>
- Italic << Back to Summary >>
Italic is used to highlight a word or sentence. Normally used for words in foreign languages, technical concepts, etc. You can use italic with an underline _ before and another after the word or sentence. There should be no space between the _ and the word.
Typed text:
The Spanish word _ordenador_ is in italic
Results:
The Spanish word ordenador is in italic
Typed text:
_This is a full sentence in italic_
Results:
This is a full sentence in italic
The same results can be achieved using asteristic *:
Typed text:
_Asteristic_ have the same effect as _underline_.
Results:
Asteristic have the same effect as underline.
- Bold << Back to Summary >>
Bold is used to give particular emphasys to a word or sentence. You can use bold with two underlines __ before and another two after the word or sentence. Like with italic, there should be no space between the __ and the word. You can also use two asteristics **.
Typed text:
Front end Developer is a __great__ job.
Results:
Front end Developer is a great job.
Typed text:
The word **help** has emphasys.
Results:
The word help has emphasys.
Typed text:
__This is a full bold sentence__
Results:
This is a full bold sentence
- Bold and Italic << Back to Summary >>
You can use both italic and bold at the same time.
Typed text:
_Italic_ word and __Bold__ word
Results:
Italic word and Bold word
Typed text:
The word ___Love___ has both italic and bold styles. or
The word ***Love*** has both italic and bold styles.
Results:
The word Love has both italic and bold styles.
Typed text:
___This is a full bold and italic sentence___ or
***This is a full bold and italic sentence*** or
Results:
This is a full bold and italic sentence
- Strikethrough << Back to Summary >>
It is used to highlight that some word or sentence has been erased or should not be used. You use double tilde ~~
Typed text:
You mistyped the command. Please change ~~fech~~ to *fetch*.
Results:
You mistyped the command. Please change
fechto fetch.
3. Document formats << Back to Summary >>
- Lists << Back to Summary >>
Lists are created to organize topics. You can have a numbered list, using numbers, or a bullet list, using -, + or *.
Typed text:
My list:
1. Item one
2. Item two
3. Item three
Results:
My list:
- Item one
- Item two
- Item three
Typed text:
My bullet list:
- One item
- Another item
- One more item
Results:
My bullet list:
- One item
- Another item
- One more item
The symbols + and * create an empty space between items. They both work exactly the same way and could be exchanged one for another.
Typed text:
My bullet list:
* One item
+ Another item
+ One more item
Results:
My bullet list:
- One item
- Another item
- One more item
- Task Lists << Back to Summary >>
Tasks list as used to take note of tasks and if they are completed or not. You use the same notation as lists (-, + or *) followed by brackets [ ]. You can add an x to mark task as completed.
Typed text:
My to-do list:
- [x] Wake up
- [ ] Have some coffee
- [ ] Study
Results:
My to-do list:
- Wake up
- Have some coffee
- Study
- Tables << Back to Summary >>
Tables are used to organize information. The table cells are separated by | and you need to separate the table header from the body using a --- separator It is alno needed to leave an empty line before the table, or it won't render correctly on some viewers, like on Github.
Typed text:
My table
``
| Day | Class |
`|---|---|`
`| Monday | yes |`
`| Tuesday | no |`
`| Wednesday | yes |`
`| Thursday | no |`
`| Friday | no |`
Results:
My table
Day Class Monday yes Tuesday no Wednesday yes Thursday no Friday no
- Horizontal Bar << Back to Summary >>
This is a bar that separates sections on your text document. You use a --- on a blank line.
Typed text:
One section
---
Another section
Results:
One section
Another section
note: because of the special case ___ for generating titles, you should put a blank like after the text
Typed text:
One section
---
Another section
Doesn't work as expected. It converts the upper text to a title: Results:
Another section
4. Codes and Quotes << Back to Summary >>
- Code << Back to Summary >>
Code is used when we want to highlight a line, stating that it is a piece of code. This is important to catch the attention and state that the code is not a normal text. You use a backtick ` before and after the code. It is used every time by programmers to display to others pieces of code.
Typed text:
`<p>This is a piece of code.</p>`
Results:
<p>This is a piece of code.</p>
Note that other Markdown or HTML tags won't work inside a code sentence. That's the main advantage of using a code. We can display the tags without aplying the styles. It is very useful for teaching . 😉
Typed text:
`The Spanish word _ordenador_ is in italic`
Results:
The Spanish word _ordenador_ is in italic
Note the difference without the backticks ` :
Typed text:
The Spanish word _ordenador_ is in italic
Results:
The Spanish word ordenador is in italic
note: it only works for a single line code. If you want to display more than one line of code, you need to use a Code block (see below).
Typed text:
`<!doctype html>
<html lang="en">
<head>
<title>My Page</title>
</head>
<body>
<h1>My Page</h1>
</body>
</html>
`
It doesn't work as expected. Results:
`<!doctype html>
<title>My Page</title> `
- Code Block << Back to Summary >>
Code Block is used exactly as the Code, but when we want to display a multiline code. We start a Code Block with triple backtick ``` and finish it the same way ```.
Typed text:
```
<!doctype html>
<html lang="en">
<head>
<title>My Page</title>
</head>
<body>
<h1>My Page</h1>
</body>
</html>
```
Results:
<!doctype html> <html lang="en"> <head> <title>My Page</title> </head> <body> <h1>My Page</h1> </body> </html>
note: inside Code Blocks, you can add spaces and tabs to give your code a correct indentation, so it is clearer to be read and understood. Typed text:
```
<!doctype html>
<html lang="en">
<head>
<title>My Page</title>
</head>
<body>
<h1>My Page</h1>
</body>
</html>
```
Results:
<!doctype html> <html lang="en"> <head> <title>My Page</title> </head> <body> <h1>My Page</h1> </body> </html>
note: Just like with single line Codes, Mardkdown and HTML tags are not converted to styles Typed text:
```
This is a **bold** text.
This is an _italic_ text.
This is a ~~strikethrough~~ text
```
Results:
This is a **bold** text. This is an _italic_ text. This is a ~~strikethrough~~ text
note: you can also use the Code Block triple backtick ``` for single line Code, and it will work exactly like the single backtick ` Code's syntaxis. Typed text:
``` <p>Hello World!</p> ```
Results:
Hello World!
- Quote and Blockquote << Back to Summary >>
Quote is a format we use when we want to hightlight a sentence stating that it is a quote. It creates a distinct block around the sentence. It is created using a greaten than > character before the sentence. In practical terms, it works like Code Block, but Markdown and HTML tags are applied and give styles to text.
Typed text:
>This is a _quote_.
Results:
This is a quote.
note: Quote blocks works exactly the same way, but with multiple lines. We need to put a > before each line ane they get grouped together. Typed text:
>_I always did something I was a little not ready to do. I think that’s how you grow. When there’s that moment of_ "Wow, I’m not really sure I can do this!" _and you push through those moments, that’s when you have a breakthrough._
>
>— Marissa Mayer (CEO of Yahoo)
Results:
I always did something I was a little not ready to do. I think that’s how you grow. When there’s that moment of "Wow, I’m not really sure I can do this!" and you push through those moments, that’s when you have a breakthrough.
— Marissa Mayer (CEO of Yahoo)
5. Images << Back to Summary >>
You can add images to your Mardown documents. You just need to know the exact path of the image and provide an alt text. Alt texts are texts describing your image. It is very helpful for people with special necessities (such as blind people) using screen readers. As they can't see the image, the Alt text describes the image for them. We should always provide an Alt text for images. Normally, the Alt text is not displayed on screen.
Sintaxis: 
Pay attention on the exclamation ! before the brackets. It is necessary to load images.
Typed text:
Results:
**note**: _if your image is not on the same folder as your Mardkdown document, you need to inform the correct folder where the image can be found. In the example below we are acccesing an image that is inside an "images" folder._
Typed text:
Results:
The most common extensions of images on the web are: .jpg .png .gif and .svg. Make sure you write the correctly the file extension as it is really common to mistake it.
note: if your write a wrong extension or a wrong path, or if for any other reason the image can't be loaded, only the Alt text will be displayed. In the example below we've written a wrong file extension:
Typed text:
Results:
note: If we do not inform correctly the folder that contains our image, it will not be able to be loaded, thus only the Alt text will be displayed. Below, we removed the reference to the subfolder "images/" from the path and the Markdown will try to find the image on the same folder of the Markdown document.
Typed text:
Results:
We can provide an internet address (URL) for an image. The advantage is that we don't have to host the image on our own project, but we have to take care not to use images protected by copyrights.
Typed text:
Results:
6. Links << Back to Summary >>
Just like on an HTML page, you can add hyperlinks to your Mardown document. Hyperlinks, or just links, are clickable partes od the document that take you to another document or page. The sintaxis is almost the same as the Image's, but here we don't use the exclamation ! mark.
Sintaxis: [Title](path or URL of link)
Title is the text displayed informing where the link leads to. It is very important for understanding the purpose of the link, as normally the path or URL is not visible.
Typed text:
[Visit my Github page](https://github.com/annabranco)
Results:
Clicking on this link is going to take you to my Github page. if you try it, remember to come back here to keep on learning. 😉
Another useful function of links is to lead the reader to an specific part or section of your document.
For example, you want users to go to Section One Heading when they click on "Section One" summary item.
Summary:
- Section One
(clicking here...) - Section Two
To do it, we just need to create a link to the name of the Heading, using only lowercase letters and changing spaces for dashes - .
In this case, our link would be [Section One](#section-one)
Let's write our code:
Typed text:
Summary:
1. [Section One](#section-1)
2. Section Two
Results:
Summary:
- Section One
- Section Two
Now clicking on Section One link on the above summary would take you directly to the Heading Section One below. Try it! 🙂
Great, isn't it?
- Anchor links << Back to Summary >>
Another way to establish links, when we are not able to use the Heading method described above, is to create an Anchor. To do so, we create an a tag with the ID name we want to call our link reference.
For example, we want a link "TAKE ME TO MADRID FOR REFUGEES LOGO" to take us to the logotype displayed below:
The first step would be to put the a tag before the image sintaxis. Inside the <a> we need to give an ID, that would be how we want to call this Anchor. In our case, let's say "our-logo". So this would be the Anchor tag: <a id="our-logo"></a>
By placing it before our image, the code would be like this:
<a id="our-logo"></a>
Using this sintaxis you can give names and create links for any part of your document.
Now, to create the link itself, we just need to add a path to the name we gave our Anchor.
This would be our code:
Typed text:
[TAKE ME TO MADRID FOR REFUGEES LOGO](#our-logo)
Results:
Now, clicking on the above link will take you to the Logo of Madrid For Refugees. Pretty cool!
The summary on the beginning of this Tutorial uses this exact functionality.
7. HTML tags << Back to Summary >>
Many developers don't like using HTML inside Markdown documents, and it is important to know that it is not fully supported. There are lot of viewers that just don't render HTML styles. One another strong argument against it is that Markdown is another language, used to simplify and make it easier and quicker to write text documents. Thus, putting HTML code on it contradicts the logic of working with Markdown.
Some people like to use HTML tags just to give Markdown special styles that this language doesn't support by itself, like changing colors, font sizes, etc. But it is important to know that in many places, like here on Github, the effects will just not be seen.
If you decide to use it, here are some useful HTML tags:
- Color << Back to Summary >>
To change the color of the text, we can use the HTML tag <font> with the attribute color. We just need to write the name or code of the color. A pink color, for example, would be <font color=pink>.
We wrap the text we want to change colors on the <font></font> tag.
Typed text:
The word <font color=red>red</font> is red and <font color=green>green</font> is green.
Results:
The word red is red and green is green.
If you want to know more about color codes and names, here is a good page: Color codes and names on HTML/CSS.
- Size << Back to Summary >>
To change the color of the text, we can also use the HTML tag <font>, with the attribute size
Typed text:
<font size=6>Huge text</font>
<font size=5>Very big text</font>
<font size=4>Big text</font>
<font size=3>Normal text</font>
<font size=3>Almost normal text</font>
<font size=2>Small text</font>
<font size=1>Very small text</font>
<font size=0>Tiny text</font>
Results:
Huge text
Very big text
Big text
Normal text
Almost normal text
Small text
Very small text
Tiny text
- Mixed styles << Back to Summary >>
Both mentioned styles can be grouped inside <font> tag.
Typed text:
The word <font color=red size=4>red</font> is red and <font color=lightgreen size=1>green</font> is green.
Results:
The word red is red and green is green.
You can even mix up HTML and Markdown sintaxis.
Typed text:
The word <font color=red size=5>**red**</font> is red and bold <font color=lightgreen size=6>_green_</font> is green and italic.
Results:
The word red is red and bold green is green and italic.
It is worth mentioning that even though these sintaxis are part of HTML, it should not be used inside HTML bodies, as the correct practice when writing HTML5 is that it holds just plain containt, and all styles are given through CSS3, that uses almost the same sintaxis.
Document information << Back to Summary >>
Author: Anna Branco Version: 1.1 Updated on: Dicember 1st, 2018 Web page: Markdown Tutorial
Credits for the images:
-
Dove flying holding an olive branch symbolizing peace on earth. Copyright: no. From Wikipedia. Licensed under the Creative Commons Attribution-Share Alike 3.0 Unported license
-
Logotype of Madrid For Refugees. Version improved on Photoshop. Copyrights: Madrid For Refugees.
-
Animated image of an Unicorn running and jumping. Copyrights: Wikia. Distributed under the Eclipse Public License.
This document may be freely distributed and I'd be really happy if it is used for educational purposes.
Please feel free to make any corrections, sugerencies or comments through Pull Requests.
I hope this is useful. Thank you. 😄