My Markdown Cheat Sheet

Markdown is a lightweight markup language that can be converted to different output formats, including HTML.

The main purpose of this tool is to create rich text that can be interpreted by browsers, text editors, etc.

The markdown text should be readable in both the actual markdown file and the generated ouput file. This document will show how to use markdown and explain the best practices of it.

Headings

To make any text appear as a heading, it needs to have n amount of hashes at the beggining of the line; where n is a number between 1 and 6 representing the header tags available in HTML.

Example

# My main header
  -> will be translated to:
  <h1>My main header</h1>

## My secondary header
  -> will be translated to:
  <h2>My secondary header</h2>

##### My less important header
  -> will be translated to:
  <h5>My less important header</h5>

Note

There is an alternative way to create a main heading (h1) and a secondary heading (h2).

A main header can be created by placing an '=' character below the desired text.

A secondary header can be created by placing a '-' character below the desired text.

Example

My main header
=

My secondary header
-

If desired, any number of '=' or '-' can be used to accomplish a heading.

Example

My main header
==============

My secondary header
--------------

The output will be the same.

However, this method is not recommended because it makes markdown files harder to read, modify, and there is the limitation of only having these special characters to handle h1's and h2's.

Paragraphs

A paragraph is a self-contained unit of text that deals with a particular idea.

Every paragraph must be separated by an empty newline so the generated output knows where the line break begins.

Example

Bad:
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Good:
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Text Decoration

Bolds

To make any text appear in bold, it needs to be wrapped by '**' (double asterisks).

Example

**This text will be bold** this won't.

Italics

To make any text appear in italic, it needs to be wrapped by '_' (single underscore).

Example

_This text will be italic_ this won't.

Note

To convert text into bold or italic the only required thing is to use the appropiate amount of characters, two for bold and one for italic.

Therefore, wrapping text with '__' (double underscores) will make that text appear as bold and wrapping text with '*' (single asterisk) will make that text appear as italic.

Example

__This text will be bold__ this won't.

*This text will be italic* this won't.

It is important to choose and be consistent with which characters to use for each case.

Try to avoid using the same character for all the use cases to improve markdown readability.

Bad:
__This text will be bold__ this won't.

_This text will be italic_ this won't.

Good:
**This text will be bold** this won't.

_This text will be italic_ this won't.

Strikethrough

To make any text appear ~~strikethrough~~, it needs to be wrapped by '~~' (double tildes)

Example

~~This text will be strikethrough~~ this won't.

Line Breaks

To put a line break without creating a different paragraph, a 'br' tag can be placed anywhere.

Example

My paragraph needs a line break<br/>So it does not create a new paragraph.

Becomes

My paragraph needs a line break.
So it does not create a new paragraph.

Horizontal Rules

An Horizontal rule can be created by adding a new line and at least three '-' (dashes), three '*' (asterisks), or three '_' (underscores). Some interpreters can use three '=' (equal signs) as well, this is not recommended as it is not fully supported everywhere.

Example

This is my horizontal rule with dashes

---

This is my horizontal rule with asterisks

***

This is my horizontal rule with underscores

___

Becomes

This is my horizontal rule with dashes

This is my horizontal rule with asterisks

This is my horizontal rule with underscores

Block Quotes

To create a quote, a '>' (right angle bracket) needs to be placed before the quoted text.

Example

> "I only know that I know nothing"
>
> ~ **Socrates**

Becomes

"I only know that I know nothing"

~ Socrates

Lists

Unordered List

To create an unordered list, items need to be placed one per line and a '+' (plus), '*' (asterisk), or '-' (dash) need to be placed at the beggining of each item. Keep consistency by choosing the same character across the lists.

Example

+ Item 1
+ Item 3
+ Item 2

Becomes

Item 1
Item 3
Item 2

Ordered List

To create an ordered list, items need to be placed one per line and a number followed by a '.' (dot) need to be placed at the beggining of each item. Keep consistency by using the same number across the lists.

Example

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

Becomes

Item 1
Item 2
Item 3

To improve maintainability, use the same number to enumerate all the items. It becomes harder to maintain (for example reordering the list) if the enumeration tries to follow the content of the list.

Bad

1. Item 1
2. Item 3 // Is this the item 2 or 3?
3. Item 2

Good

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

Nested Lists

Any list can have nested lists if four spaces (usually a tab) are placed before an item.

Example

1. Item 1
   - My nested item 1
       - My nested item 2

         My nested paragraph 2

     My nested paragraph 1
1. Item 2
1. Item 3

Becomes

Item 1
- My nested item 1
  - My nested item 2
    
    My nested paragraph 2
  My nested paragraph 1
Item 2
Item 3

Links

URLs

To make an url clickable: https://github.com/AlexisGlez, they need to be wrapped by '<>' (angle brackets)

Example

<https://github.com/AlexisGlez>

Text as Links

To make any text become a link it needs to be wrapped by '[]' (square brackets) followed by the desired url between parenthesis: '(url)'

Example

[any text](https://my-url.com)

A title attribute can also be specified between '""' (double quotes) after the url.

Example

[any text](https://my-url.com "My link title attribute")

Links Tokenization

It is pretty common to have repeated urls in a markdown file. To improve readability and maintainability of the markdown tokens can be used to replace plain urls.

A token can be placed after any text wrapped by '[]' (square brackets), putting another pair of '[]' with the token's name inside of them. The token's value needs to be defined somewhere in the markdown file. For better maintainability, they are usually declared at the end of the Markdown file, putting each token name wrapped by '[]' then followed by ':' (colon) and then the value of the token.

Example

[my link][myTokenName]

...
// At the end of the file:
[myTokenName]: https://my-url.com

It is important to mention that link titles cannot be placed within tokens.

Images

Images can be added as if they were any link but with a '!' (exclamation mark) at the beggining of the link's format.

Example

 ![image's alt text](https://my-image-url.com "optional title")

Markdown's Logo

Markdown's Logo (source: Wikipedia)

Links tokenization can also be applied for images.

Clickable Images

An image can become clickable by putting wrapping an image between '[]' (square brackets) and adding a link to it. This can work for preview of large images.

Example

 [![image's alt text](https://my-thumbnail-image-url.com "optional title")](https://my-large-image-url.com)

Markdown's Logo (source: Wikipedia)

Syntax Highlighting

Any text can be highlighted by wrapping it with single '`' (backticks)

Example

My `highlighted` text.

Becomes

My highlighted text.

The code tags can also be used for this purpose: my highlighted text

Code Blocks

Code Blocks can be created by wrapping any text between three ``` (backticks).

Example

` ` `
var i = 0;

const dog = 'rocky';
` ` `

Becomes

var i = 0;

const dog = 'rocky';

The programming language name can also be specified to improve readability.

Example

` ` `python

s = "Python syntax highlighting"

print s

` ` `

Becomes

s = "Python syntax highlighting"

print s

Code Diff

A code diff can be created by placing the word diff after any code block.

A line addition is added by placing '+' (plus) before any line.

A code deletion is added by placing '-' (dash) before any line.

Example

+ var i = 0;

- const dog = 'rocky';

Becomes

+ var i = 0;

- const dog = 'rocky';

Tables

Tables can be creating by wrapping with '|' (pipes) the contents of the table.

A column is defined by adding '|-' (pipe + one or more dashes).

Each column needs to be defined after the titles of each one of them have been declared.

Example

|Student|Age|
|-------|---|
|Alexis|23|
|Carlos|22|

Becomes

Student	Age
Alexis	23
Carlos	22

Each cell text alignment can be changed by adding a ':' colon in the column definition.

A ':' at the beggining will align the text of each cell to the left.

Example

|Student|Age|
|:------|:--|
|Alexis|23|
|Carlos|22|

Becomes

Student	Age
Alexis	23
Carlos	22

A ':' at the end will align the text of each cell to the right.

Example

|Student|Age|
|------:|--:|
|Alexis|23|
|Carlos|22|

Becomes

Student	Age
Alexis	23
Carlos	22

A ':' at both, the beggining and the end, will align the text of each cell to the center.

Example

|Student|Age|
|:-----:|:--:|
|Alexis|23|
|Carlos|22|

Becomes

Student	Age
Alexis	23
Carlos	22

Each column can have different text alignment if needed.

Example

|Student|Age|
|:-----:|---:|
|Alexis|23|
|Carlos|22|

Becomes

Student	Age
Alexis	23
Carlos	22

HTML

HTML can be placed inside a markdown file, but not all Markdown interpreters will support this feature.

All the tags will have their attributes available for styling.

For example, images can be placed with the img tag instead using the previous syntax described.

Example

<img src="https://upload.wikimedia.org/wikipedia/commons/4/48/Markdown-mark.svg" width="50" height="50" />

Markdown's Logo (source: Wikipedia)

Notice how the image is not being displayed with 50px width and 50px of height.

A style tag can also be placed to apply CSS to the HTML.

Example

<style>
  img {
    width: 50px;
  }
</style>

The HTML feature should be used carefully as it is not supported everywhere and it can easily create a harder to read and maintain Markdown file.

My Markdown Cheat Sheet

Table of Contents

Headings

Example

Note

Example

Example

Paragraphs

Example

Text Decoration

Bolds

Example

Italics

Example

Note

Example

Strikethrough

Example

Line Breaks

Example

Horizontal Rules

Example

Block Quotes

Example

Lists

Unordered List

Example

Ordered List

Example

Nested Lists

Example

Links

URLs

Example

Text as Links

Example

Example

Links Tokenization

Example

Images

Example

Clickable Images

Example

Syntax Highlighting

Example

Code Blocks

Example

Example

Code Diff

Example

Tables

Example

Example

Example

Example

Example

HTML

Example

Example