This is my definitive Markdown cheatsheet. It includes all the Markdown syntax you need to know to create beautiful and professional-looking documents.
Styling text 1
| Style | Syntax char|textchar |
Keyboard shortcut | Example | Output | ||||||
|---|---|---|---|---|---|---|---|---|---|---|
| Heading | #|text## |text### |text#### |text##### |text###### |text |
None | # A first-level heading |
|||||||
| Horizontal Rule | --- or *** | None | --- |
Text between Horizontal Rules |
||||||
| Bold | **|text** or __|text__ |
Ctrl+B | **This is bold text** |
This is bold text | ||||||
| Italic | *|text* or _|text_ |
Ctrl+I | _This text is italicized_ |
This text is italicized | ||||||
| Strikethrough | ~~|text~~ |
None | ~~This was mistaken text~~ |
|||||||
| Quote | >|quote |
Ctrl+Shift+. | > Text that is a quote |
Text that is a quote |
||||||
| Inline code quote | `|code` |
Ctrl+E | This has an `inline quote code` text |
This has an inline quote code text |
||||||
| Inline math quote | $ equation $ |
None | $\sqrt{3x-1}+(1+x)^2$ |
3x-1+(1+x)2 | ||||||
| Block code quote | ```|multi-lined-code``` |
Ctrl+E | This has a |
This has a Block |
||||||
| Block math quote | $$|equation$$ or ```math |equation``` |
None | $$ |
f(x)=x2 | ||||||
| Bold and nested italic | **|bold_|italic_|bold** |
None | **This text is _extremely_ important** |
This text is extremely important | ||||||
| All bold and italic | **_|bold-italic_** |
None | **_All this text is important_** |
All this text is important | ||||||
| Subscript | <sub>|text</sub> |
None | This is a <sub>subscript</sub> text |
This is a subscript text | ||||||
| Superscript | <sup>|text</sup> |
None | This is a <sup>superscript</sup> text |
This is a superscript text | ||||||
| Sub+Superscript | <sup><sub>|text</sub></sup> |
None | <sup><sub>This is a very small text</sub></sup> |
This is a very small text | ||||||
| Hidden Comment | <!--|hidden comment--> |
None | <!--This is a hidden comment--> |
|||||||
| Unordered List | - |item* |item+ |item |
Ctrl+Shift+8 | - Unordered List Item |
|
||||||
| Ordered List | 1. |item |
Ctrl+Shift+7 | 1. Ordered List Item |
|
||||||
| Task List | - [ ] |item |
None | - [ ] Task List Item |
Task List Item Task List Item |
||||||
| Nested List | Combine any List syntax | None | 1. First list item |
|
||||||
| Inline Link | [|text](|url "|hover") |
None | [GitHub Pages](https://pages.github.com/ "hover info") |
GitHub Pages | ||||||
| Inline Image Link |  |
None |  |
|||||||
| Reference Link | [ref_tag]: |url "|hover" |
None | [git_page]: https://pages.github.com/ "hover info" |
|||||||
| Inline Link with Ref. | [|text][ref_tag] |
None | [GitHub Pages][git_page] |
GitHub Pages | ||||||
| Inline Image Link with Ref. | ![alt-text][ref_tag] |
None | ![][100x100] |
|||||||
| Table | | Header 1 | Header 2 | | --- | --- | | Cell A1 | Cell A2 | | Cell B1 | Cell B2 | |
None | | Header 1 | Header 2 | |
|
||||||
| Footnote | [^footnote]: |text-and-or-link</kbd |
None | [^footnote]This is a footnote |
This has a footnote. 2 | ||||||
| Collapsible Section | <details> <summary> |summary</summary>|text</details> |
None | <details> |
Click to expandThis is hidden |
||||||
| Text Box | <table> <td> |text</td></table> |
None | <table> |
|
Alerts 3
> [!NOTE]
> Highlights information that users should take into account, even when skimming.
> [!TIP]
> Optional information to help a user be more successful.
> [!IMPORTANT]
> Crucial information necessary for users to succeed.
> [!WARNING]
> Critical content demanding immediate user attention due to potential risks.
> [!CAUTION]
> Negative potential consequences of an action.Note
Highlights information that users should take into account, even when skimming.
Tip
Optional information to help a user be more successful.
Important
Crucial information necessary for users to succeed.
Warning
Critical content demanding immediate user attention due to potential risks.
Caution
Negative potential consequences of an action.
Color Preview 4
Only in issues, pull requests and discussions, you can call out colors within a sentence by using backticks. A supported color model within backticks will display a visualization of the color.
| Color | Syntax | Example | Output |
|---|---|---|---|
| HEX | #RRGGBB | #0969DA |
 |
| RGB | rgb(R,G,B) | rgb(9, 105, 218) |
 |
| HSL | hsl(H,S,L) | hsl(212, 92%, 45%) |
 |
Relative links and image paths help readers navigate your repository. A relative link points to another file relative to the current file's location. For example, a link in your root README to a file in docs/CONTRIBUTING.md would look like:
[Contribution guidelines for this project](docs/CONTRIBUTING.md)
GitHub automatically adjusts relative links and paths based on the current branch, ensuring they always work. Links starting with / are relative to the repository root. You can use relative link operands like ./ and ../.
Examples of relative links:
- In a .md file on the same branch
/assets/images/electrocat.png - In a .md file on another branch
/../main/assets/images/electrocat.png - In issues, pull requests and comments of the repository
../blob/main/assets/images/electrocat.png?raw=true - In a .md file in another repository
/../../../../github/docs/blob/main/assets/images/electrocat.png - In issues, pull requests and comments of another repository
../../../github/docs/blob/main/assets/images/electrocat.png?raw=true
Link a Label 5
You can reference labels in markdown using the following syntax:
https://github.com/account/repo/labels/label-nameSwap out images based on theme settings. 6
Add: #gh-dark-mode-only or #gh-light-mode-only to the end of the image path to specify which theme the image should be displayed in.
You can now specify whether to display images for light or dark themes in Markdown, using the HTML <picture> element in combination with the prefers-color-scheme media feature. 7
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/25423296/163456776-7f95b81a-f1ed-45f7-b7ab-8fa810d529fa.png">
<img alt="Shows an illustrated sun in light color mode and a moon with stars in dark color mode." src="https://user-images.githubusercontent.com/25423296/163456779-a8556205-d0a5-45e2-ac17-42d089e3c3f8.png">
</picture>Footnotes 8
You can add footnotes to your content by using this bracket syntax:
[^one_line]Here is a simple footnote.
A footnote can also have multiple[^multi_line] lines.
Can also reference to a link. [^link]
[^one_line]: My reference.
[^multi_line]:
To add line breaks within a footnote, prefix new lines with 2 spaces.
This is a second line.
[^link]: Example with URL: https://github.com
9Here is a simple footnote.
A footnote can also have multiple10 lines.
Can also reference to a link. 11
Collapsing large blocks of text can make your markdown much easier to digest
<details>
<summary>To make sure markdown is rendered correctly in the collapsed section...</summary>
1. Put an **empty line** after the `<summary>` block.
2. _Insert your markdown syntax_
3. Put an **empty line** before the `</details>` tag
</details>To make sure markdown is rendered correctly in the collapsed section...
- Put an empty line after the
<summary>block. - Insert your markdown syntax
- Put an empty line before the
</details>tag
[python_badge]: https://img.shields.io/badge/Python-informational?logo=python&style=flat&logoColor=79dafa&labelColor=282a36&color=ff6e96
[autohotkey_badge]: https://img.shields.io/badge/Auto_Hotkey-informational?logo=autohotkey&style=flat&logoColor=79dafa&labelColor=282a36&color=ff6e96
[ruby_badge]: https://img.shields.io/badge/Ruby-informational?logo=ruby&style=flat&logoColor=79dafa&labelColor=282a36&color=5e4053
Nice looking file tree 12
Using the graphql syntax in block quotes will nicely highlight file trees like below:
./root/*
├─ assets/* # Fonts, icons, images, etc.
├─ code/* # Where the code lives
│ ├─ main.py # The main file
│ └─ Other files…
└─ utils/* # Utility functionsAdd a box with contents to markdown
<table><td>
This is text in the `box`</td></table>|
This is text in the |
<table><td align="center" width="1000">
This is text in the centered `box`</td></table>|
This is text in the centered |
Advanced Table Tips 13
Use pipes | and hyphens - to create tables. Hyphens define headers, and pipes separate columns. Ensure there's a blank line before the table for correct rendering.
| Header 1 | Header 2 |
| -------- | -------- |
| Cell A1 | Cell A2 |
| Cell B1 | Cell B2 || Header 1 | Header 2 |
|---|---|
| Cell A1 | Cell A2 |
| Cell B1 | Cell B2 |
| Tool | Purpose |
| ------ | -------------------------------- |
| `ls` | Display _directory_ contents |
| `grep` | Search for **specific** patterns || Tool | Purpose |
|---|---|
ls |
Display directory contents |
grep |
Search for specific patterns |
Align text left, center, or right using colons : in the header row.
| Left Align | Center Align | Right Align |
| :--------- | :----------: | ----------: |
| Item A | Item B | Item C |
| Item D | Item E | Item F || Left Align | Center Align | Right Align |
|---|---|---|
| Item A | Item B | Item C |
| Item D | Item E | Item F |
| First Image | Second Image |
| :--------------------------------------------: | :---------------------------------------------: |
|  |  || First Image | Second Image |
|---|---|
Table within a Table 14
| Image | Table Inside Table |
| :----------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
|  | <table> <thead> <tr> <th>Header</th> <th>Example</th> <th>Example</th> </tr> </thead> <tbody> <tr> <td align="center"><img src="https://picsum.photos/150/150" width="150px"></td> <td><img src="https://picsum.photos/100/150" width="100px" align="center"></td> <td><img src="https://picsum.photos/75/75" width="75px"></td> </tr> <tr> <td align="center">Info</td> <td align="center">(?)</td> <td align="center">Info</td> </tr> </tbody> </table> || Image | Table Inside Table | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|
|
Advanced Formatting Tips 15
This is the code you need to align images to the left:
<img align="left" width="100" height="100" src="https://picsum.photos/100/100">This is the code you need to align images to the right:
<img align="right" width="100" height="100" src="https://picsum.photos/100/100">
<p align="center">
<img width="460" height="300" src="https://picsum.photos/460/300" />
</p>via comment
<p>
<img src="https://picsum.photos/100/100" />
<img src="https://picsum.photos/100/100" />
</p>
With hspace property you can set horizontal (left and right) padding for an image
<p>
<img src="https://picsum.photos/100/100" hspace="10" />
<img src="https://picsum.photos/100/100" hspace="10" />
</p>
We also have a property "vspace", which does what it sounds like, add vertical spacing. But it doesn't seem to work on GitHub, unlike VSCode's buit in markdown viewer. So probably just add a <p> tag in between.
<p>
<img src="https://picsum.photos/500/100" />
</p>
<p>
<img src="https://picsum.photos/500/100" />
</p>
<p>
<img src="https://picsum.photos/500/100" />
</p>
Diagrams 16
GitHub now supports the following diagram types:
| content type | supported extensions |
|---|---|
| mermaid | .mermaid, .mmd |
| geoJSON | .geojson, .json |
| topoJSON | .topojson, .json |
| STL | .stl |
Mermaid
Examples
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
sequenceDiagram
Alice->>+John: Hello John, how are you?
Alice->>+John: John, can you hear me?
John-->>-Alice: Hi Alice, I can hear you!
John-->>-Alice: I feel great!
Basics
flowchart LR
id
flowchart LR
id1[This is the text in the box]
flowchart LR
id["This ❤ Unicode"]
%%{init: {"flowchart": {"htmlLabels": false}} }%%
flowchart LR
markdown["`This **is** _Markdown_`"]
newLines["`Line 1
Line 2
Line 3`"]
markdown --> newLines
flowchart LR
id1[This is the text in the box]
Direction
Possible FlowChart orientations are:
TB - Top to bottom
TD - Top-down/ same as top to bottom
BT - Bottom to top
RL - Right to left
LR - Left to right
flowchart TB
Start --> Stop
flowchart TD
Start --> Stop
flowchart BT
Start --> Stop
flowchart RL
Start --> Stop
flowchart LR
Start --> Stop
Node shapes
A node with round edges
flowchart LR
id1(This is the text in the box)
A stadium-shaped node
flowchart LR
id1([This is the text in the box])
A node in a subroutine shape
flowchart LR
id1[[This is the text in the box]]
A node in a cylindrical shape
flowchart LR
id1[(Database)]
A node in the form of a circle
flowchart LR
id1((This is the text in the circle))
A node in an asymmetric shape
flowchart LR
id1>This is the text in the box]
A node (rhombus)
flowchart LR
id1{This is the text in the box}
A hexagon node
flowchart LR
id1{{This is the text in the box}}
Parallelogram
flowchart TD
id1[/This is the text in the box/]
Parallelogram alt
flowchart TD
id1[\This is the text in the box\]
Trapezoid
flowchart TD
A[/Christmas\]
Trapezoid alt
flowchart TD
B[\Go shopping/]
Double circle
flowchart TD
id1(((This is the text in the circle)))
Links between nodes
A link with arrow head
flowchart LR
A-->B
An open link
flowchart LR
A --- B
Text on links
flowchart LR
A-- This is the text! ---B
or
flowchart LR
A---|This is the text|B
A link with arrow head and text
flowchart LR
A-->|text|B
or
flowchart LR
A-- text -->B
Dotted link
flowchart LR
A-.->B;
Dotted link with text
flowchart LR
A-. text .-> B
Thick link
flowchart LR
A ==> B
Thick link with text
flowchart LR
A == text ==> B
An invisible link This can be a useful tool in some instances where you want to alter the default positioning of a node.
flowchart LR
A ~~~ B
Chaining of links
flowchart LR
A -- text --> B -- text2 --> C
It is also possible to declare multiple nodes links in the same line as per below:
flowchart LR
a --> b & c--> d
You can then describe dependencies in a very expressive way. Like the one-liner below:
flowchart TB
A & B--> C & D
If you describe the same diagram using the basic syntax, it will take four lines. A word of warning, one could go overboard with this making the flowchart harder to read in markdown form. The Swedish word lagom comes to mind. It means, not too much and not too little. This goes for expressive syntaxes as well.
flowchart TB
A --> C
A --> D
B --> C
B --> D
Arrow Types
Triangle edge
flowchart LR
A --> B
Circle edge
flowchart LR
A --o B
Cross edge
flowchart LR
A --x B
Multi Directional edges
flowchart LR
A o--o B
B <--> C
C x--x D
Link Lenght
Add more dashes to increase the length of the link
flowchart TD
A[Start] --> B{Is it?}
B -->|Yes| C[OK]
C --> D[Rethink]
D --> B
B ---->|No| E[End]
Here are how you should add dashes to increase the length of the link:
| Length | 1 | 2 | 3 |
|---|---|---|---|
| Normal | --- | ---- | ----- |
| Normal with arrow | --> | ---> | ----> |
| Thick | === | ==== | ===== |
| Thick with arrow | ==> | ===> | ====> |
| Dotted | -.- | -..- | -...- |
| Dotted with arrow | -.-> | -..-> | -...-> |
Subgraphs
subgraph title
graph definition
end
An example below:
flowchart TB
c1-->a2
subgraph one
a1-->a2
end
subgraph two
b1-->b2
end
subgraph three
c1-->c2
end
You can also set an explicit id for the subgraph.
flowchart TB
c1-->a2
subgraph ide1 [one]
a1-->a2
end
With the graphtype flowchart it is also possible to set edges to and from subgraphs as in the flowchart below.
flowchart TB
c1-->a2
subgraph one
a1-->a2
end
subgraph two
b1-->b2
end
subgraph three
c1-->c2
end
one --> two
three --> two
two --> c2
With the graphtype flowcharts you can use the direction statement to set the direction which the subgraph will render like in this example.
- If any of a subgraph's nodes are linked to the outside, subgraph direction will be ignored. Instead the subgraph will inherit the direction of the parent graph
flowchart LR
subgraph TOP
direction TB
subgraph B1
direction RL
i1 -->f1
end
subgraph B2
direction BT
i2 -->f2
end
end
A --> TOP --> B
B1 --> B2
Formatting
Markdown Strings
The "Markdown Strings" feature enhances flowcharts and mind maps by offering a more versatile string type, which supports text formatting options such as bold and italics, and automatically wraps text within labels.
Formatting:
For bold text, use double asterisks (*) before and after the text.
For italics, use single asterisks () before and after the text.
With traditional strings, you needed to add
tags for text to wrap in nodes. However, markdown strings automatically wrap text when it becomes too long and allows you to start a new line by simply using a newline character instead of a
tag.
This feature is applicable to node labels, edge labels, and subgraph labels.
%%{init: {"flowchart": {"htmlLabels": false}} }%%
flowchart LR
subgraph "One"
a("`The **cat**
in the hat`") -- "edge label" --> b{{"`The **dog** in the hog`"}}
end
subgraph "`**Two**`"
c("`The **cat**
in the hat`") -- "`Bold **edge label**`" --> d("The dog in the hog")
end
Interaction
It is possible to bind a click event to a node, the click can lead to either a javascript callback or to a link which will be opened in a new browser tab.
flowchart LR
A-->B
B-->C
C-->D
click A callback "Tooltip for a callback"
click B "https://www.github.com" "This is a tooltip for a link"
click D href "https://www.github.com" "This is a tooltip for a link"
GeoJSON
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"id": 1,
"properties": {
"ID": 0
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
-90,
35
],
[
-90,
30
],
[
-85,
30
],
[
-85,
35
],
[
-90,
35
]
]
]
}
}
]
}
TopoJSON
{
"type": "Topology",
"transform": {
"scale": [
0.0005000500050005,
0.00010001000100010001
],
"translate": [
100,
0
]
},
"objects": {
"example": {
"type": "GeometryCollection",
"geometries": [
{
"type": "Point",
"properties": {
"prop0": "value0"
},
"coordinates": [
4000,
5000
]
},
{
"type": "LineString",
"properties": {
"prop0": "value0",
"prop1": 0
},
"arcs": [
0
]
},
{
"type": "Polygon",
"properties": {
"prop0": "value0",
"prop1": {
"this": "that"
}
},
"arcs": [
[
1
]
]
}
]
}
},
"arcs": [
[
[
4000,
0
],
[
1999,
9999
],
[
2000,
-9999
],
[
2000,
9999
]
],
[
[
0,
0
],
[
0,
9999
],
[
2000,
0
],
[
0,
-9999
],
[
-2000,
0
]
]
]
}
STL
solid cube_corner
facet normal 0.0 -1.0 0.0
outer loop
vertex 0.0 0.0 0.0
vertex 1.0 0.0 0.0
vertex 0.0 0.0 1.0
endloop
endfacet
facet normal 0.0 0.0 -1.0
outer loop
vertex 0.0 0.0 0.0
vertex 0.0 1.0 0.0
vertex 1.0 0.0 0.0
endloop
endfacet
facet normal -1.0 0.0 0.0
outer loop
vertex 0.0 0.0 0.0
vertex 0.0 0.0 1.0
vertex 0.0 1.0 0.0
endloop
endfacet
facet normal 0.577 0.577 0.577
outer loop
vertex 1.0 0.0 0.0
vertex 0.0 1.0 0.0
vertex 0.0 0.0 1.0
endloop
endfacet
endsolid
Footnotes
-
https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/ ↩
-
This is a footnote ↩
-
https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alertsbasic-writing-and-formatting-syntax ↩
-
https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#supported-color-models ↩
-
https://github.blog/changelog/2022-02-03-reference-labels-in-markdown/ ↩
-
https://github.blog/changelog/2021-11-24-specify-theme-context-for-images-in-markdown/ ↩
-
https://github.blog/changelog/2022-05-19-specify-theme-context-for-images-in-markdown-beta/ ↩
-
https://github.blog/changelog/2021-09-30-footnotes-now-supported-in-markdown-fields/ ↩
-
My reference. ↩
-
To add line breaks within a footnote, prefix new lines with 2 spaces.
This is a second line. ↩ -
Example with URL: https://github.com ↩
-
https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-tables ↩
-
https://github.blog/changelog/2022-03-17-mermaid-topojson-geojson-and-ascii-stl-diagrams-are-now-supported-in-markdown-and-as-files/ ↩
Color Preview
Only in issues, pull requests and discussions, you can call out colors within a sentence by using backticks. A supported color model within backticks will display a visualization of the color.
#0969DArgb(9, 105, 218)hsl(212, 92%, 45%)