Markdown is a lightweight markup language with plain-text-formatting syntax. Its primary objective is to be as readable as possible. The design of Markdown is to make it easy to write using any basic text editor and equally simple to read in its raw form.
John Gruber created Markdown in 2004 with the help of Aaron Swartz to write in an easy-to-read and easy-to-write format that can be converted to HTML. Since then, Markdown has become one of the most popular markup languages and is widely used for formatting readme files, writing messages in online discussion forums, and to create richly formatted text using a plain text editor.
Markdown works by using simple and intuitive syntax that gets converted (or "rendered") into structurally valid HTML by a Markdown processor. This means you write in Markdown, and then it's transformed into the web pages that people see.
Markdown is used for creating documents, notes, articles, emails and technical documentation. The benefits include its simplicity, ease of use, and its ability to be converted to HTML and many other formats. It is beneficial for quickly creating formatted text that can be easily converted into multiple formats. Its simplicity and compatibility make it an excellent choice for writing documentation or creating content for the web.
Compared to rich text formatting, Markdown offers a more streamlined and distraction-free writing experience with its incredibly straightforward syntax. Additionally, the files are plain text, so they are small in size making it highly compatible with version control systems such as Git.
Markdown is commonly used in various professions, including software development, technical writing, content creation, and academic research. It has become an essential skill for anyone working with web content, documentation, or collaborative writing projects. It's used widely on websites like GitHub, Reddit, and Stack Overflow – anywhere that users are expected to submit their own content but may not know complex HTML or desire a simpler way to format.
Headings are used to denote section breaks in a document, and they range from level 1 to 6, with level 1 being the most significant (often the title of the document) and level 6 the least significant.
Headings are created using a hash symbol # followed by a space. The number of hash symbols determines the level of the heading.
Example:
# H1
## H2
### H3
#### H4
##### H5
###### H6
Will be converted to:
<h1>H1</h1>
<h2>H2</h2>
<h3>H3</h3>
<h4>H4</h4>
<h5>H5</h5>
<h6>H6</h6>
And displayed as:
H1
H2
H3
H4
H5
H6
Unordered lists are used to present a list of items without a specific order. They are typically rendered with bullet points.
Unordered lists are created using a dash - , plus + , or asterisk * followed by a space.
Example:
- Item 1
- Item 2
- Nested Item 2.1
- Nested Item 2.2
- Nested Item 2.2.1
Will be converted to:
<ul>
<li>Item 1</li>
<li>Item 2
<ul>
<li>Nested Item 2.1</li>
<li>Nested Item 2.2
<ul>
<li>Nested Item 2.2.1</li>
</ul>
</li>
</ul>
</li>
</ul>
And displayed as:
- Item 1
- Item 2
- Nested Item 2.1
- Nested Item 2.2
- Nested Item 2.2.1
Ordered lists are similar to unordered lists, but they are used to present a sequence of items in a specific order, numbered by default.
Ordered lists are created using numbers followed by a period . and a space.
Example:
1. First item
2. Second item
1. Nested item 1
2. Nested item 2
1. Nested item 2a
Will be converted to:
<ol>
<li>First item</li>
<li>Second item
<ol>
<li>Nested item 1</li>
<li>Nested item 2
<ol>
<li>Nested item 2a</li>
</ol>
</li>
</ol>
</li>
</ol>
And displayed as:
- First item
- Second item
- Nested item 1
- Nested item 2
- Nested item 2a
Italics are used for emphasis or to denote a title of a work.
There are two ways to create italics, using either an underscore _ or an asterisk * .
Example:
*italicized text*
_italicized text_
Will be converted to:
<em>italicized text</em>
<em>italicized text</em>
And displayed as:
italicized text
Bold text is used for strong emphasis. Like italics, you can create bold text with either double asterisks ** or double underscores __ .
Example:
**bold text**
__bold text__
Will be converted to:
<strong>bold text</strong>
<strong>bold text</strong>
And displayed as:
bold text
Strikethrough text is a way to represent text that is no longer accurate or relevant without removing it. It can be created using double tildes ~~ .
Example:
~~strikethrough~~
Will be converted to:
<del>strikethrough</del>
And displayed as:
Markdown allows you to combine bold, italic, and strikethrough formatting for text as needed.
You can combine them in any order, but it is best practice to place bold on the outside for readibility. You cannot combine two of the same formatting type.
Example:
**_~~bold, italic, and strikethrough~~_**
Will be converted to:
<strong><em><del>bold, italic, and strikethrough</del></em></strong>
And displayed as:
Blockquotes are used to indicate that the enclosed text is, you guessed it, a quote! They are also sometimes used to display other snippets of content that are separate from the main document.
Blockquotes are created using a greater than symbol > followed by a space.
Example:
> This is a blockquote.
Will be converted to:
<blockquote>
This is a blockquote.
</blockquote>
And displayed as:
This is a blockquote.
Blockquotes can be nested to create multi-level blockquotes. Nested blockquotes are created using multiple greater than symbols > followed by a space.
Example:
> This is the first level of quoting.
>
>> This is a nested blockquote.
Will be converted to:
<blockquote>
This is the first level of quoting.
<blockquote>
This is a nested blockquote.
</blockquote>
</blockquote>
And displayed as:
This is the first level of quoting.
This is a nested blockquote.
Links are created to enable navigation to other web pages, files, email addresses, locations, and more.
They are created using square brackets [ ] followed by parentheses ( ) .
The text inside the square brackets [ ] is used as the link's displayed text, and the text inside the parentheses ( ) is used as the link's URL or path.
Example:
[FreeCodeCamp](https://www.freecodecamp.org/)
Will be converted to:
<a href="https://www.freecodecamp.org/">FreeCodeCamp</a>
And displayed as:
Markdown supports embedding images and GIFs using a syntax similar to links.
They are created using an exclamation mark ! followed by square brackets [ ] and parentheses ( ) .
The text inside the square brackets [ ] is used as the image's alt attribute. It's helpful to include a descriptive alt attribute for accessibility, as screenreaders can read it aloud to visually impaired users.
It is also used by search engines to understand what the image is about.
The text inside the parentheses ( ) is used as the image's source src attribute. The src attribute is used to specify the image's source and can be a URL or a path to a local file.
Think 'SAPS' as a good way to remember this:
Square Alt; Parentheses Source.
Example:
Will be converted to:
<img src="URL or /path/to/img.jpg" alt="Alt text">
You can also add links to images by combining the syntax for links and images.
Simply replace the link's text inside the square brackets [ ] with the image syntax.
The image will be clickable and will navigate the user to the URL or path specified in the link.
Example:
[](URL)
Will be converted to:
<a href="URL or /path/to/img.jpg">
<img src="URL" alt="Alt text">
</a>
Anchors allow for linking directly to a section within a document, and are not to be confused with links to external pages. They are also known as jump links, fragment identifiers, or hash links.
Anchors are created using square brackets [ ] followed by parentheses ( ) .
The text inside the square brackets [ ] is used as the anchor's displayed text, and the text inside the parentheses ( ) is used as the anchor's ID which is prefixed with a hash symbol # .
The anchor's ID must be unique within the document. It is linked to the section of the document that has the same ID.
Many Markdown renderers automatically create id attributes for headers based on their text content, which can then be used for anchor links.
Example:
<!-- Write the header: -->
## Section 1
<!-- Create an anchor link pointing to that header: -->
[Go to Section 1](#section-1)
Will be converted to:
<h2 id="section-1">Section 1</h2>
<a href="#section-1">Go to Section 1</a>
And displayed as:
Tables are used to display data in a tabular format. They are created using a combination of pipes | , dashes - , and colons : .
Table Structure:
- The first row is used to create headers.
- The second row is used to specify the alignment of the columns.
- The rest of the rows are used to create the table's body.
Alignment (second row):
- The number of dashes in the second row determines the alignment of the columns.
- If there are dashes on the left, right, or both sides of the column, the column is left-aligned, right-aligned, or centered, respectively.
Using Pipes:
- The pipes are used to separate the columns.
- In the second row they are used to separate the alignment from the header text.
- In the rest of the rows they are used to separate the columns.
- The pipes at the beginning and end of the row are optional.
Example:
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Row 1 | Data | Data |
| Row 2 | Data | Data |
Will be converted to:
<table>
<thead>
<tr>
<th>Column 1</th>
<th>Column 2</th>
<th>Column 3</th>
</tr>
</thead>
<tbody>
<tr>
<td>Row 1</td>
<td>Data</td>
<td>Data</td>
</tr>
<tr>
<td>Row 2</td>
<td>Data</td>
<td>Data</td>
</tr>
</tbody>
</table>
And displayed as:
| Column 1 | Column 2 | Column 3 |
|---|---|---|
| Row 1 | Data | Data |
| Row 2 | Data | Data |
Task lists are used to create a list of items that can be checked off, such as to-do lists.
They are created using square brackets [ ] followed by a space. To check off an item, replace the space with an x x .
Example:
- [x] Completed task
- [ ] Incomplete task
Will be converted to:
<ul>
<li><input type="checkbox" checked disabled> Completed task</li>
<li><input type="checkbox" disabled> Incomplete task</li>
</ul>
And displayed as:
- Completed task
- Incomplete task
Horizontal rules are used to create a horizontal line to separate sections in a document.
They are created using three or more asterisks * , dashes - , or underscores _ on a line by themselves.
Example:
---
- - -
***
Will be converted to:
<hr>
<hr>
<hr>
And displayed as:
Inline code is used to denote a snippet of code within a line of text. It is created using a backtick ` on either side of the code.
Example:
Here is a paragraph with some `html`.
Will be converted to:
<p>Here is a paragraph with some <code>html</code>.</p>
And displayed as:
Here is a paragraph with some html .
Code blocks are used to display blocks of code snippets. They are created using three backticks ``` on a line by themselves, followed by the code block, and ending with three backticks ``` on a line by themselves.
There is also the option (where supported) to include syntax highlighting based on the programming language used. To do this, specify the language name after the first set of backticks: ```python .
Example:
```[optional language name]
def hello_world():
print("Hello, world!")
```
Will be converted to:
<pre><code>
def hello_world():
print("Hello, world!")
</code></pre>
And displayed as:
def hello_world():
print("Hello, world!")
Markdown allows you to escape characters that would otherwise be used to format text in a document. To escape a character, add a backslash \ before the character.
Example:
\*This text is not in italics\*
Will be converted to:
<p>*This text is not in italics*</p>
And displayed as:
*This text is not in italics*
Multi-line text is used to create a block of text that preserves the line breaks and spaces.
Multi-lines are created using two or more spaces at the end of a line, or text separated by one or more blank lines.
Example:
This is the first line.
This is another line with a blank line in between.
Will be converted to:
<p>This is the first line.</p>
<br>
<p>This is another line with a blank line in between.</p>
And displayed as:
This is the first line.
This is another line with a blank line in between.
Comments are used to add notes to a document that are not displayed in the rendered document.
Markdown itself does not support comments, but they can be created using an HTML comment tag <!-- --> .
Example:
<!-- This is a comment in Markdown -->
Will be converted to:
<!-- This is a comment in Markdown -->
Emojis are used to add a touch of personality, visually communicate emotions or ideas, and enhance the reader's engagement with the text in a friendly and informal way. Plus, they're fun! 😋🎉
Emojis can be inserted into Markdown documents using literal emoji characters. If you are using Windows you can access the emoji keyboard with the shortcut
+ Period . For Mac users, it's
Ctrl +
+ Space .
Or, you can copy and paste from a website like
Emojipedia.
On some platforms you can use colon-syntax to insert emojis directly into text. This is achieved using a colon : followed by the emoji name and another colon : . A list of supported emojis can be found
here
Example:
😄 is the same as :smile:
Here are some excellent Markdown resources to add to your bookmarks. Don't forget to star the repos on your GitHub!