Markdown is a popular and easy-to-use markup language used to format text consistently with a simple set of rules.
Markdown rules combine text with simple characters (e.g. asterisks, backticks, hash symbols) to represent different structural elements (e.g. lists, code, headers).
Markdown documents (.md) can be easily read on their own. However, converters are often used to convert them to richer documents to make the formatting more visual.
For example, this post was written in a .md file and then converted to an .html page using the Hugo static site generator.
While different converters will render markdown in slightly different ways, they all follow the same general rules.
Why do I like markdown? Two main reasons:
🛒 Portability
Markdown syntax is entirely based on plain text characters. Meaning that markdown files can be opened and read by any text editor on any operating system. Unlike other document formats, the format is not proprietary and you are not forced to use any specific tool to write, read, or edit markdown.
🔎 Readability
There are other popular markup languages for formatting documents (for example, HTML). The advantage of markdown is how simple it is. By using markdown you will format your text in a consistent way, but without cluttering it with lengthy and complex syntax.
Interested in using markdown? This post will show you all the rules you need to get started.
Basic Text Formatting
Bold
To make bold text surround text with two asterisks on both sides (**).
When you write ⬇️
Here is some **bold** text
You get ⬇️
Here is some bold text
Italic
To make italic text surround text with a single asterisk on both sides (*).
When you write ⬇️
Here is some *italic* text
You get ⬇️
Here is some italic text
Line Breaks
Creating line breaks is one of the most confusing parts of markdown for beginners. Single line breaks are ignored by markdown converters. There are two ways around this.
To split text into two paragraphs, use two line breaks (↲↲).
When you write ⬇️
Some text split
across two lines
A new paragraph
You get ⬇️
Some text split across two lines
A new paragraph
To split text without showing extra spacing between the lines of the output, use two spaces at the end of the first line before the line break (··↲).
When you write ⬇️
Some text split··
across two lines
You get ⬇️
Some text split
across two lines
Links
Add links by putting the anchor text within square brackets ([ ]) followed by the URL in parenthesis (( )).
When you write ⬇️
Here is a [link](http://example.com)
Images
To add an image put the alt text for the image in square brackets ([ ]), followed by the URL to the image in parenthesis (( )), and prefix everything with an exclamation point (!).
This is very similar to how markdown links are added. Prefixing the link with an exclamation point tells the markdown converter to render the image.
When you write ⬇️
You get ⬇️
Lists
Unordered Lists
To create an unordered list, prefix each list item with either a dash and a space (-·) or an asterisk and a space (*·).
When you write ⬇️
- Item 1
- Item 2
- Item 3
Ordered Lists
Create ordered lists by prefixing each list item with the item number followed by a period and a space (for example, 1.·).
When you write ⬇️
1. Item 1
2. Item 2
3. Item 3
You get ⬇️
Item 1
Item 2
Item 3
Note that you do not have to number list items sequentially. Most markdown converters will generate the list with sequential numbering even if you prefix every line with 1.·. This makes it much easier to move things around.
When you write ⬇️
1. Item 1
1. Item 2
1. Item 3
You get ⬇️
Item 1
Item 2
Item 3
Nested Lists
To create nested lists, indent each list item with spaces. Add four spaces for each indentation level (····).
When you write ⬇️
- Item 1
- Item 1.1
- Item 1.1.1
- Item 1.2
1. Item 1
1. Item 1.1
2. Item 1.2
You get ⬇️
Item 1
- Item 1.1
- Item 1.2
Code Blocks
You can format text as code in two ways. Either as a block or inline. Inline simply means that the code is part of an existing line and should not be rendered in a separate paragraph.
For inline code, surround the text with backticks (`).
When you write ⬇️
Some `inline` code
You get ⬇️
Some inline code
For a block of code, surround the text with three backticks (```) instead of one.
Code blocks need to be separated from other text. They begin with a line with three backticks, followed by lines of code to render, and a final line with three more backticks.
When you write ⬇️
```
code block
```
Some markdown converters support defining the programming language used in the code block by adding the language right after the first three backticks. When this is supported it allows different languages to be rendered in different ways (e.g. with different colours).
When you write ⬇️
```java
void main(String[] args) {
String str = "some string";
System.out.println(str);
}
```
You get ⬇️
void main(String[] args) {
String str = "some string";
System.out.println(str);
}
Headers
Headers are formatted by prefixing the header text with a hash symbol and a space (#·). The number of # symbols determines what level of header the text becomes (in HTML, they get converted to h1, h2, etc).
# Level 1
## Level 2
### Level 3
#### Level 4
Quotes
You can format text as a quote by prefixing each line of the text with a greater-than symbol (>).
Note that all other markdown rules still apply within a block quote.
When you write ⬇️
> This is a **quote**.
>
> -Hector
You get ⬇️
This is a quote.
-Hector
Other Resources