Markdown

Beginner’s Guide to GitHub-Flavoured Markdown

Try it Here!

1. Introduction

1.1 Why Markdown Rocks ✨

Markdown is plain text with super-powers. It lets you jot notes, write docs, craft blog posts, even format PDFs - all without leaving the comfort of your favourite text editor.

• Human-friendly – readable in raw form, so your future self (and collaborators) can skim it in any terminal.
• Portable – works on GitHub, GitLab, Stack Overflow, Jira, Notion, countless CMSes and static-site generators.
• Speedy – no buttons or WYSIWYG mysteries; just type.
• Version-control bliss – diffs stay clean because it’s plain text.

1.2 Where You’ll Meet Markdown

• README files, issue & PR templates on GitHub.
• Technical blogs (Jekyll, Hugo, Astro, etc.).
• Docs sites (Docsify, MkDocs, Docusaurus).
• Note-taking apps (Obsidian, Logseq, Typora).
• Chat & community tools (Telegram, Discord, Slack, Discourse).

1.3 Little Wonders You Can Do 😍

Markdown’s magic is that every one of those tricks is still perfectly legible in raw text.

Wonder	Tiny snippet	What happens
Task lists	- [x] done - [ ] to-do	Interactive check-boxes in GitHub issues.
Syntax-highlight	```python print("Hi") ```	Colours like an IDE!
Tables	| foo | bar | |----|----|	Nicely aligned grids.
Collapsible blocks	<details><summary>peek</summary>spoiler!</details>	Click to reveal secrets.
Emoji	I ❤️ Markdown :tada:	Turns into 😍 🎉.

2 · Quick Reference (Cheat Sheet)

Tip: Try every sample in a .md file on GitHub and hit Preview.

2.1 Headings

# H1
## H2
### H3

Rendered ⇒

peek

# H1

H2

H3

### 2.2 Emphasis

*italic*   _italic_
**bold**   __bold__
~~strike~~

italic  bold  strike

2.3 Lists

Unordered

- Item A
  - Sub-item
* Asterisks work too

• Item A

  • Sub-item

• Asterisks work too

Ordered

1. First
2. Second

1. First
2. Second

2.4 Links

[visible text](https://example.com)
<https://example.com>   <!-- autolink -->

visible text https://example.com

2.5 Images

![Alt text](https://picsum.photos/200/300)

2.6 Code

Inline

`code` → code

Fenced (with highlight)

```js
function greet() {
  console.log("Hello!");
}
```

2.7 Blockquotes

> One level
>> Nested wisdom

One level

Nested wisdom

2.8 Horizontal Rule (Divider)

---

Rendered ⇒

peek

---

2.9 Tables

| Col A | Col B |
|-------|-------|
|  1    |  2    |
|  3    |  4    |

Col A	Col B
1	2
3	4

2.10 Task Lists

- [ ] Walk dog
- [x] Write guide

• Walk dog
• Write guide

2.11 Emoji

:rocket: :sparkles: :100:

🚀 ✨ 💯

2.12 Strikethrough

~~obsolete~~ now shiny

obsolete now shiny

2.13 Inline HTML (Collapsible)

<details>
<summary>Click me</summary>
Surprise! 🎈
</details>

Click me

Surprise! 🎈

2.14 Escaping Characters

Need a literal *? Use backslash:

\*not italic\*

*not italic*

2.15 Footnotes

Markdown is handy.[^1]

[^1]: And footnotes are too!

Markdown is handy.¹

🎉 That’s a Wrap!

You now wield the essentials of GitHub-flavoured Markdown. Keep this cheat-sheet nearby, and soon you’ll be dashing off beautifully formatted docs at lightspeed. Happy writing!

Explore More🗺️

To truly master Markdown, you should combine it with features from some foundational languages like HTML and CSS, and utilize additional extensions. See Charles' cool demo for some additional features:

1. HTML
2. CSS
3. LaTeX
4. Mermaid
5. JavaScript

Notice those features may not be ubiquitously supported depending on the renderer.

References

• Adam Pritchard's Markdown Cheatsheet.
• Charles Zhang's Markdown is Cool demo.
• The super power markup converter tool Pandoc.