# Everything You Need to Know About Markdown
## What is Markdown?

> Markdown is a lightweight markup language created by [John Gruber](https://en.wikipedia.org/wiki/John_Gruber) in 2004. It functions as a _text-to-HTML_ conversion tool for web writers. Because it's easy to read and write, it has become the standard for technical documentation, web content, and general text formatting.
## How to Set Up a Markdown Environment?
To set up a Markdown environment, people generally choose between these four options depending on their specific needs:
### 1. VS Code(Visual Studio Code)
VS Code is a well-known code editor that also serves as an excellent tool for writing markup language. If you are looking to write technical documentation, manage large projects, VS Code is the best choice.
Setup:
1. Install VS Code: Download and install it from the [official website](https://code.visualstudio.com/).
2. Install ''Markdown All in One''(Extension by Yu Zhang): This adds keyboard shortcuts and auto-completion, which makes the workflow significantly smoother.
3. Install ''Markdown Preview Enhanced''(Extension by Yiyi Wang): This allows you to see a real-time preview of your document side-by-side while editing.
4. Install ''Markdown PDF''(Extension by yzane): Once finished, this lets you export your Markdown file (`.md`) into various formats such as HTML, PDF, JPG, or PNG.
### 2. Obsidian
Obsidian is the best note taking app that supports markdown language. If you are tired of standard [WYSIWYG](https://en.wikipedia.org/wiki/WYSIWYG) editors and want more flexibility, try Obsidian.
Setup:
1. Install Obsidian: Download and install it from the [official website](https://obsidian.md/).
2. Learn the Basics/Advanced Syntax and more from [Obsidian Help](https://help.obsidian.md/)
### 3. HackMD
HackMD is the "Google Docs for Markdown"—it allows multiple people to edit the same file simultaneously in the browser.
Setup:
1. Go to [HackMD.io](https://hackmd.io/) and sign up with your email, GitHub. No installation is required.
2. Click "New Note" and you are ready to go.
### 4. Typora
Typora is a minimalist, aesthetic markdown editor. Unlike traditional editors that use a dual-column display (source code vs. preview), it uses a seamless [WYSIWYG](https://en.wikipedia.org/wiki/WYSIWYG) interface that renders Markdown instantly as you type, though you can still toggle the source code if needed. It is extremely popular among writers.
Setup:
1. Install Typora: Download it from the [official website](https://typora.io/).
2. As of version 1.0 (released Nov 23, 2021), Typora is paid software ($14.99).
## Basic Syntax
After setting up your environment, you are ready to learn the basic syntax used in Markdown.

| Element | Markdown Syntax | HTML Source | HTML Preview |
| -------------------------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Heading | H1<br>===<br>H2<br>--- | `<h1>H1</h1>`<br>`<h2>H2</h2>`<br> | <h1>H1</h1><br><h2>H2</h2> |
| Heading | # H1 <br>## H2 <br>### H3<br>#### H4<br>##### H5<br>###### H6 | `<h1>H1</h1>`<br>`<h2>H2</h2>`<br>`<h3>H3</h3>`<br>`<h4>H4</h4>`<br>`<h5>H5</h5>`<br>`<h6>H6</h6>` | <h1>H1</h1><br><h2>H2</h2><br><h3>H3</h3><br><h4>H4</h4><br><h5>H5</h5><br><h6>H6</h6> |
| Italics | `_Italics_` | `<em>Italics</em>` | <em>Italics</em> |
| Bold | `**Bold**` | `<strong>Bold</strong>` | <strong>Bold</strong> |
| Blockquote | >This is the first blockquote.<br>><br>>This is the second paragraph in the blockquote. | `<blockquote>`<br>`<p>This is the first blockquote.</p>`<br>`<p>This is the second paragraph in the blockquote.</p>`<br>`</blockquote>` | <blockquote><p>This is the first blockquote.</p><p>This is the second paragraph in the blockquote.</p></blockquote> |
| Nested Blockquote | > This is the first level of quoting. <br>> >This is nested blockquote. <br>> Back to the first level. | `<blockquote>`<br>`<p>This is the first level of quoting.</p>`<br>`<blockquote>`<br>`<p>This is nested blockquote.</p>`<br>`</blockquote>`<br>`<p>Back to the first level.</p>`<br>`</blockquote>` | <blockquote><p>This is the first level of quoting.</p><blockquote><p>This is nested blockquote.</p></blockquote><p>Back to the first level.</p></blockquote> |
| Unordered (Bulleted) Lists | `- First item.`<br>`- Second item.`<br>`- Third item.` | `<ul>`<br>`<li>First item.</li>`<br>`<li>Second item.</li>`<br>`<li>Third item.</li>`<br>`</ul>` | <ul><br><li>First item.</li><li>Second item.</li><li>Third item.</li><br></ul> |
| Unordered (Bulleted) Lists | `+ First item.`<br>`+ Second item.`<br>`+ Third item.` | `<ul>`<br>`<li>First item.</li>`<br>`<li>Second item.</li>`<br>`<li>Third item.</li>`<br>`</ul>` | <ul><br><li>First item.</li><li>Second item.</li><li>Third item.</li><br></ul> |
| Unordered (Bulleted) Lists | `* First item.`<br>`* Second item.`<br>`* Third item.` | `<ul>`<br>`<li>First item.</li>`<br>`<li>Second item.</li>`<br>`<li>Third item.</li>`<br>`</ul>` | <ul><br><li>First item.</li><li>Second item.</li><li>Third item.</li><br></ul> |
| Ordered (Numbered) Lists | `1. First item.`<br>`2. Second item.`<br>`3. Third item.` | `<ol>`<br>`<li>First item.</li>`<br>`<li>Second item.</li>`<br>`<li>Third item.</li>`<br>`</ol>` | <ol><br><li>First item.</li><li>Second item.</li><li>Third item.</li><br></ol> |
| Links | `[example link](http://example.com/ "With a Title")` | `<a href="http://example.com/" title="With a Title">example link</a>` | <a href="http://example.com/" title="With a Title">example link</a> |
| Images | `` | `<img src="https://placehold.co/100" alt="alt text" title="With a Title" />` | <img src="https://placehold.co/100" alt="alt text" title="With a Title" /> |
| Code | \`print()\` | `<code>print()</code>` | <code>print()</code> |
| Fenced Code Blocks | \`\`\`<br>print("This is code inside a fenced code block.")<br>\`\`\` | `<code>print("This is code inside a fenced code block.")</code>` | <code>print("This is code inside a fenced code block.")</code> |

## Advanced Syntax
For those who want to dive deeper into Markdown's capabilities, here are some advanced features.
>**General Principle**: Markdown is a conversion tool for HTML. If a specific formatting feature isn't supported natively in Markdown (such as underlining and text color), you can always fall back to HTML tags to achieve the desired effect.
### HTML Block Elements

Block-level elements (e.g., `<p>`, `<table>`, `<div>`) must be separated from surrounding content by blank lines, and the start and end tags of the block should not be indented with tabs or spaces. Markdown formatting is not processed within block-level tags.

 This is a regular paragraph. 
 
 <table> 
	 <tr> 
		 <td>Foo</td> 
	</tr> 
 </table> 
 
 This is another regular paragraph.

### HTML Inline Elements
Span-level HTML tags (e.g. `<span>`, `<img>`, or `<del>`) — can be used anywhere in a Markdown paragraph, list item, or header. Unlike block-level HTML tags, Markdown syntax _is_ processed within span-level tags.
### Automatic Escaping for Special Characters
In standard HTML, the characters `<` (less than), `>` (greater than), and `&` (ampersand) are reserved syntax characters. Using them literally usually requires manual escaping (e.g., typing `&lt;`, `&gt;`, or `&amp;`).

Markdown eliminates this hassle by using _Smart Escaping_. It detects the context of these characters and escapes them only when necessary.
#### 1. The Ampersand (`&`)
Markdown distinguishes between an ampersand used in text (or URLs) and an ampersand used to start an HTML entity.
- Text & URLs: If you write `AT&T` or a URL like `...&q=larry+bird`, Markdown automatically converts the `&` into `&amp;` for valid HTML.
- HTML Entities: If you write a valid entity like `&copy;`, Markdown leaves it alone.
#### 2. Angle Brackets (`<` and `>`)
Markdown distinguishes between mathematical comparisons, HTML tags, and Markdown syntax.
- Math: If you write `4 < 5` or `10 > 5`, Markdown converts them to `&lt;` and `&gt;`.
- Tags: If you write `<div>`, Markdown recognizes it as an HTML tag and leaves it unchanged.
- Blockquotes: While `>` usually displays literally in mid-sentence, placing `>` at the start of a line triggers a Markdown blockquote.
#### 3. Escaping Inside Code Blocks
Within code syntax, Markdown always escapes `<`, `>`, and `&`.

| Markdown Syntax | HTML Source | HTML Preview |
| --------------- | -------------------------- | ------------ |
| \``<div>`\` | `<code>&lt;div&gt;</code>` | `<div>` |
### Paragraph and Line Breaks

A paragraph consists of one or more consecutive lines of text, separated by one or more blank lines.

Markdown ignores single line breaks (pressing `Enter` once). This allows you to "hard wrap" your text—breaking long lines so they are easier to read in your editor—without affecting the final output.

If you want to force a line break without starting a new paragraph, end the line with two or more spaces or use a `<br />` tag.
### Code Blocks
To create a code block, simply indent every line by at least 4 spaces or 1 tab. Markdown wraps the block in both `<pre>` and `<code>` HTML tags.
Markdown Input:

This is a normal paragraph.

	This is a code block.

Markdown will generate:

 <p>This is a normal paragraph.</p> 
 
 <pre><code>This is a code block.</code></pre>

A code block continues until it reaches a line that is not indented.
### Horizontal Rules
To create a horizontal rule (`<hr />`), place three or more hyphens, asterisks, or underscores on a line by themselves.

* * * 
*** 
***** 
- - - 
---------------------------------------

### Links & Image
Inline Links:

 This is [an example](http://example.com/ "Title") inline link. 
 
 [This link](http://example.net/) has no title attribute.

Reference-style links:

This is [an example][id] reference-style link.

[id]: http://example.com/ "Optional Title Here"

Inline Image:

![Alt text](/path/to/img.jpg) ![Alt text](/path/to/img.jpg "Optional title")

Reference-style Image:

![Alt text][id]

[id]: url/to/image "Optional title attribute"

### Extended Syntax
These features are not supported by the original Markdown. They are extensions developed to allow for richer formatting. However, they are widely supported by most tools like GitHub, HackMD and Obsidian.
#### Footnotes
Input:

Markdown was created by John Gruber[^1] in 2004. 

[^1]: He collaborated with Aaron Swartz on the syntax.

Output:
Markdown was created by John Gruber[^1] in 2004.

[^1]: He collaborated with Aaron Swartz on the syntax.
#### Strike-throughs

| Markdown Syntax | HTML Source | HTML Preview |
| ------------------- | -------------------------- | ----------------- |
| `~~deleted words~~` | `<del>deleted words</del>` | ~~deleted words~~ |
#### Task List
Input:

- [x] Draft the article outline 
- [x] Write the first paragraph 
- [ ] Review and edit 
- [ ] Publish to website

Output:
- [x] Draft the article outline
- [x] Write the first paragraph
- [ ] Review and edit
- [ ] Publish to website
#### Table
Input:

| Header Left | Header Center | Header Right | 
| ---- | ------ | ----| 
| Cell 1 | Cell 2 | Cell 3 |

Output:

| Header Left | Header Center | Header Right |
| ----------- | ------------- | ------------ |
| Cell 1 | Cell 2 | Cell 3 |

### Backslash Escapes
Markdown allows you to use backslash escapes to generate literal characters which would otherwise have special meaning in Markdown’s formatting syntax. For example:
Input:

 \*literal asterisks\*

Output:
\*literal asterisks\*
Markdown provides backslash escapes for the following characters:

\ backslash 
` backtick 
* asterisk 
_ underscore 
{} curly braces 
[] square brackets 
() parentheses 
# hash mark 
+ plus sign 
- minus sign (hyphen) 
. dot 
! exclamation mark

### HTML Coloring and Highlighting
Standard Markdown does not support text coloring or highlighting. However, because Markdown supports inline HTML, you can use specific HTML tags to achieve these effects.
- Text Color: Use the `<font>` tag with the `color` attribute.
- Highlighting: Use the `<mark>` tag.
- Custom Styling: You can combine tags or use the `style` attribute for specific colors.

| Effect | HTML Source | HTML Preview |
| ---------------- | --------------------------------------------------------------- | ------------------------------------------------------------- |
| Red Text | `<font color="red">This text is Red</font>` | <font color="red">This text is Red</font> |
| Highlight | `<mark>Yellow highlight</mark>` | <mark>Yellow highlight</mark> |
| Custom Highlight | `<mark style="background-color: pink;">Pink highlight</mark>` | <mark style="background-color: pink;">Pink highlight</mark> |
| Combined | `<mark><font color="red">Red text with highlight</font></mark>` | <mark><font color="red">Red text with highlight</font></mark> |

## Reference and Additional Resource
1. [John Gruber's Markdown Documentation.](https://daringfireball.net/projects/markdown/) The original guide written by the creator of Markdown.
2. [The Markdown Guide.](https://www.markdownguide.org/) A comprehensive open-source guide.
3. [Markdown Practice for Beginners](https://www.markdowntutorial.com/) Great for beginners.