Markdown Tutorial

↑

Markdown Guide

Basic syntax: https://www.markdownguide.org/basic-syntax/#horizontal-rules

John Gruber’s Markdown: https://daringfireball.net/projects/markdown/

Extended Markdown (Flavors of Markdown):

Pandoc’s Markdown: https://pandoc.org/MANUAL.html#pandocs-markdown

Quarto Markdown: https://quarto.org/docs/authoring/markdown-basics.html#lists

kramdown: https://kramdown.gettalong.org/syntax.html

Comments

<! --# Comments go here -->

Escape backticks

To include a literal backtick character within a code span, you can use multiple backticks as the opening and closing delimiters:

To escape one backtick, enclose it with 2 backticks and space before and after `` `
To escape three backticks, enclose them with 4 backticks and space before and after. ```

A single backtick in a code span: `` ` ``

A backtick-delimited string in a code span: `` `foo` ``

A triple backticks: ```` ``` ````

The line below is indented by at least 4 spaces.

```python

def function():

print (“Yes”)

```

GFM

GitHub Flavored Markdown

Codeblocks can sometimes break ordered lists (i.e. the list always returns to 1). To prevent this, you can do the following.

add a linebreak between the list item and the code-block, and indent the code-block by 4 spaces, or

1. Number 1
```python
print("Hello World")
```

2. Number 2
```ruby
puts 'Hello World'
```

3. Number 3
```c
printf("Hello World");
```

do not add a linebreak, but have the code-block aligned with the indentation of the line item.

1. Number 1

    ```python
    print("Hello World")
    ```

2. Number 2

    ```ruby
    puts 'Hello World'
    ```

3. Number 3

    ```c
    printf("Hello World");
    ```

Will render into the following:

Number 1
```
print("Hello World")
```
Number 2
```
puts 'Hello World'
```
Number 3
```
printf("Hello World");
```

Equations

Note that for markdown block equations, need to add a blank line before and after $$. Otherwise, the equation will be rendered as inline.

Typora support TeX-style references, i.e., \label{ref1}\tag{1}. Note that you must add a number using \tag{}; otherwise, the equation won’t be numbered and therefore cannot be cross-referenced. This is like you need to number the table or figure in order to cross-reference them.

Here is a labeled equation:

\[x+1\over\sqrt{1-x^2} \label{ref1}\tag{1}\]

This is a reference : $\eqref{ref1}$

Here is a labeled equation:

$$
x+1\over\sqrt{1-x^2} \label{ref1}\tag{1}
$$

This is a reference : $\eqref{ref1}$

Tables

To add a table, use three or more hyphens (---) to create each column’s header, and use pipes (|) to separate each column.

Cell widths can vary, just use different relative length of hyphens.

| Syntax | Description |
| --- | ----------- |
| Header | Title |
| Paragraph | Text |

You can align text in the columns to the left, right, or center by adding a colon (:) to the left, right, or on both side of the hyphens within the header row.

Bullet list

You can make a bulleted list by starting each line with a - or * or + character followed by a space. You can make a numbered list by starting each line with a 1. followed by a space.

Markdown need an Empty line before a list.

This will not work

* Item 1

* one
* two
* three

This will produce a “compact” list. If you want a “loose” list, in which each item is formatted as a paragraph, put spaces between the items:

* one

* two

* three

Identation is essential to bullet lists in markdown as it indicates bullet levels.

You can make a nested section of a list by adding two spaces before the bullet or number character.

four spaces or one tab work before the bullet too.
It is possible to add one blank line between different levels to increase readability.

* unordered list
    + sub-item 1 
    + sub-item 2 
        - sub-sub-item 1

unordered list
- sub-item 1
- sub-item 2
  - sub-sub-item 1
You can still indent a paragraph even if you don’t need a new bullet point. The indentation indicates that this paragraph belongs to the preceeding point.
- You can also nest other elements like blockquotes or code blocks.
```
1. Ingredients
  
    - spaghetti
    - marinara sauce
    - salt
  
2. Cooking
  
   Bring water to boil, add a pinch of salt and spaghetti. Cook until pasta is **tender**.
  
3. Serve
  
   Drain the pasta on a plate. Add heated sauce. 
  
   > No man is lonely eating spaghetti; it requires so much attention.
  
   Bon appetit!
```
1. Ingredients
  - spaghetti
  - marinara sauce
  - salt
2. Cooking
  
  Bring water to boil, add a pinch of salt and spaghetti. Cook until pasta is tender.
3. Serve
  
  Drain the pasta on a plate. Add heated sauce.
  
  No man is lonely eating spaghetti; it requires so much attention.
  
  Bon appetit!
If list items are separated by blank lines, Markdown will wrap the items in <p> tags in the HTML output.
Letter-ordered lists are NOT a part of standard markdown. The letters will only appear when rendering the markdown using an markdown extension or by using CSS.

Horizontal rules

To create a horizontal rule, use three or more asterisks (***), dashes (---), or underscores (___) on a line by themselves.

The rendered output of all three looks identical.

***

---

_________________

For compatibility, put blank lines before and after horizontal rules.

✅ Do this	❌ Don’t do this
Try to put a blank line before … `---` … and after a horizontal rule.	Without blank lines, this would be a heading. `---` Don’t do this!

Backquotes

To create a blockquote, start a line with greater than > followed by an optional space.

To keep the quote in one block, blank lines inside the quote must contain the > character too.

Links

[text](https://url) create a text linked to the url in parentheses.

To quickly turn a URL or email address into a link, enclose it in angle brackets.

<fake@example.com> will show like fake@example.com

Note that urls in markdown cannot handle special characters, such as space, parenthesis, pipes. It is suggested to use a html tag <a href="">link</a> if your markdown supports html. Otherwise, need to

replace space with %20
replace parenthesis with %28

Reference-style links use a second set of square brackets [text][id], inside which you place a lable of your choosing to identify the link.

Q: Why we use reference-style links?

A: The point of reference-style links is not that they’re easier to write. We aim to keep the text free from long URLs, making it easier to read.

[id] is a label used to point to the link you define somewhere else in your document, usually end of file to keep your text easier to read.

This is an example of referenc link: **[text][id]**.

This is an example of referenc link: text.

Link definition

The link definition can be placed anywhere after a blank line, but is generally near the bottom. You can also put them immediately after each paragraph in which they’re used.

Definition identifiers may consist of letters, numbers, spaces, and punctuation. They are not case sensitive.

Then, anywhere in the document, you define your link label like this, on a line by itself:

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

put your label in square brackets, followed immediately by a colon and at least one space.
write your url for the link, which you can optionally enclose in angle brackets, e.g., <http://example.com/>.
you can specify an optional title, enclosed in double quotes, single quotes, or parentheses. It is a reminder of yourself what the website is about. Also when you hover your cursor above the link, the title will show.

The implicit link name shortcut allows you to omit the name of the link, in which case the link text itself is used as the name. Just use an empty set of square brackets — e.g., to link the word “Google” to the google.com web site, you could simply write:

[Google][]

And then define the link:

[Google]: http://google.com/

Link names may contain spaces.

Phone and email links

Call me [Call Me!](tel:1111111) using markdown or <a href="tel:1111111">Call Me!</a> using html.

example@example.com [example@example.com](mailto:example@example.com) or <a href="mailto:example@example.com">example@example.com</a>

Cross References

Internal Links to sections within the same file

Link to title/heading/section

You can use # to create links towards any headings in your markdown file.
```
# This is a title
  
...
...
...
  
  
A [link](#this-is-a-title) to jump towards target heading
```
Note that:
- # for all heading levels, including level 2, 3 …
- no space between # and anchor name;
  
  delimited by hyphens if multi-word;
- anchor tag names must be lowercase
```
[click on this link](#my-multi-word-header)
  
### My Multi Word Header
```
If sections have special characters, you need to remove those special characters when you add the references.
```
# 1. Python
  
# 2. c++
  
# 3. c++11
  
# 4. asp.net-core
  
You can add a reference by using:
[1. Python](#1-python)
[2. c++](#2-c)
[3. c++11](#3-c11)
[4. asp.net-core](#4-aspnet-core)
```
Note how asp.net-core becomes aspnet-core, 1. python becomes 1-python, etc.
Link to named anchor

The markdown solutions are not universal, may act differently depending on the markdown implementation.

In such cases, if you want a portable solution, you could use HTML.

You define named anchors using raw HTML, for example: <a id="Chapter1"></a>. It can be put before any header, or in the same header line.
- Source: the target text to which you want to link to, place the following tags before the text:
  - <a id="name-of-anchor"></a> or
  - <a name="name-of-anchor"></a>
  If the source is a heading, then use
  - <h2 name="name-of-anchor">Level 2 heading</h2> or
  - wrap the anchor point around the heading
    
    Note that you need to add an empty line between <a> and the heading. Otherwise, the heading won’t be rendered correctly.
    Tags surround heading <a name="level3-heading"> ### Level 3 heading </a> Tags before heading <a name="level2-heading-before"></a> ## Level 2 heading Tags on the same line with heading ## Level 2 heading <a name="level2-heading-same-line"></a>
- Reference:
  - Use html style tags <a href="#name-of-anchor">Link to Anchor</a> to link to the target text. Or,
  - [Link to Anchor](#name-of-anchor) pure markdown
Use command + click to jump to target headings, or open them in Typora, or open in related apps.
```
<a id="anchor"></a> Anchor
  
<a href="#anchor">Link to Anchor</a>
```

Typeface

Format	Quoted by
bold	`text` (text)
italic	`text` or `_text_` (text)
bold and italic	`*text` (text*)
strikethrough	`~~text~~` (~~text~~)
underline	`<u>text</u>` (text)

Start a new line (line break) without starting a new paragrah:

\ + soft Enter (shift + Enter); or,
two empty spaces at the end of a line ␣␣, followed by a soft Enter; or,
html tags <br /> or

Insert vertical space

To create a blank line, use   (followed by a blank line).

This will add a large vertical space. If you feel it is too large, use the following solution.
<div style="height:3px;"><br></div> use whatever px you want use in html

Use html entity code to add special characters in Markdown

|checked|unchecked|crossed|
|---|---|---|
|&check;|_|&cross;|
|&#x2611;|&#x2610;|&#x2612;|

checked	unchecked	crossed
&check;	_	&cross;
☑	☐	☒

Code Blocks

Note that consecutive code blocks that are only separate by blank lines are merged together into one code block:

Here comes some code

This text belongs to the same code block.

If you want to have one code block directly after another one, you need to use an EOB marker to separate the two:

Here comes some code
^
This text belongs to the same code block.

The End-Of-Block (EOB) marker – a ^ as first character on an otherwise empty line – is a block level element that can be used to specify the end of a block-level element even if the block-level element, after which it is used, would continue otherwise.

For example, the following gives you one list with two items:

* list item one

* list item two

By using an EOB marker, you can make two lists with one item each:

* list one
^
* list two