Markdown Syntax Guide: From Basic to GitHub-Flavored Markdown

What Is Markdown?

Markdown is a lightweight markup language created by John Gruber in 2004. Its goal is simple: let you write in plain text that reads naturally, then convert it to well-structured HTML automatically.

Today it is the default format for GitHub READMEs, documentation sites (MkDocs, Docusaurus, GitBook), note-taking apps (Obsidian, Notion), and developer blogs. Learning it is one of the highest-leverage 30-minute investments in a developer's career.

Core Syntax Reference

Headings

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Emphasis

Lists

- Item one
- Item two
  - Nested item
  - Another nested
- Item three

1. First step
2. Second step
   1. Sub-step
   2. Another sub
3. Third step

Links and Images

[Link text](https://stackutils.dev)
[Link with title](https://stackutils.dev "StackUtils — Dev Tools")

![Alt text](image.png)
![Alt text](image.png "Optional title")

<!-- Reference-style links -->
[link][ref]
[ref]: https://stackutils.dev

Blockquotes and Horizontal Rules

> This is a blockquote.
> It can span multiple lines.
>
> And multiple paragraphs.

---
***
___

(any of the above creates
a horizontal rule)

Code Blocks

Fenced code blocks use triple backticks. Specify the language for syntax highlighting:

```typescript
function greet(name: string): string {
  return `Hello, ${name}!`;
}
```

```bash
npm install @faker-js/faker
```

```json
{ "name": "Alice", "age": 30 }
```

GitHub-Flavored Markdown (GFM) Extensions

GFM is a superset of standard Markdown used on GitHub, GitLab, and many other platforms. It adds several features not in the original spec:

Tables

| Column 1 | Column 2 | Column 3 |
|----------|:--------:|---------:|
| Left     | Center   |    Right |
| aligned  | aligned  |  aligned |

Colons in the divider row control alignment: left (default), center, right.

Task Lists

- [x] Completed task
- [ ] Pending task
- [ ] Another pending

Footnotes

Here is some text with a footnote.[^1]

[^1]: This is the footnote content.

Alerts (GitHub only)

> [!NOTE]
> Highlights information that users should take into account.

> [!WARNING]
> Critical content demanding immediate user attention.

> [!TIP]
> Optional information to help a user be more successful.

Practical Tips for Great READMEs

1. Start with a one-sentence description — GitHub shows the first paragraph in search results.
2. Add badges early — build status, coverage, npm version, and licence badges signal a healthy project instantly.
3. Include a Quick Start section — the three commands needed to go from clone to running. Put it before anything else.
4. Use fenced code blocks with language tags — enables syntax highlighting on every platform that renders Markdown.
5. Add a table of contents for long files — GitHub generates anchor IDs for every heading automatically.
6. Keep line length under 120 characters — improves readability in plain-text editors and diff views.