Markdown Reference

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 (**).

Here is some **bold** text

Italic

To make italic text surround text with a single asterisk on both sides (*).

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 (↲↲).

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 (··↲).

Some text split··  
across two lines

Links

Add links by putting the anchor text within square brackets ([ ]) followed by the URL in parenthesis (( )).

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.

![alt text](https://hjs.dev/favicon.png)

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 (*·).

- 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.·).

1. Item 1
2. Item 2
3. 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.

1. Item 1
1. Item 2
1. Item 3

Nested Lists

To create nested lists, indent each list item with spaces. Add four spaces for each indentation level (····).

- Item 1
  - Item 1.1
    - Item 1.1.1
  - Item 1.2

1. Item 1
   1. Item 1.1
   2. 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 (`).

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.

‍```
code block
‍```

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).

‍```java
void main(String[] args) {
  String str = "some string";
  System.out.println(str);
}
‍```

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.

> This is a **quote**.
>
> -Hector

Other Resources

• Wikipedia
• Markdown Guide
• Mastering Markdown