Markdown is the universal language for technical writing. It powers GitHub READMEs, documentation sites, note-taking apps, and countless content platforms. This guide covers everything from basic formatting to advanced features like tables, task lists, and diagrams.
Markdown Basics
Markdown uses simple punctuation to format text. What you write is almost readable as-is, but renders beautifully.
# This is a heading (H1)
## This is H2
### This is H3
Regular paragraph text. Leave a blank line between paragraphs.
This is another paragraph.| Markdown | Result |
|---|---|
| # Heading 1 | Largest heading |
| ## Heading 2 | Second level |
| ### Heading 3 | Third level |
| #### Heading 4 | Fourth level |
| ##### Heading 5 | Fifth level |
| ###### Heading 6 | Smallest heading |
Use only one H1 per document (the title). Structure content with H2 for sections, H3 for subsections. This creates a clear document hierarchy.
2Text Formatting
Emphasis, strong text, and other inline formatting use simple syntax.
*italic* or _italic_
**bold** or __bold__
***bold and italic*** or ___bold and italic___
~~strikethrough~~
`inline code`
> blockquote
> spans multiple lines| Syntax | Result | Use Case |
|---|---|---|
| *text* | italic | Emphasis, titles, foreign words |
| **text** | bold | Strong emphasis, key terms |
| ***text*** | bold italic | Very strong emphasis |
| ~~text~~ | strikethrough | Deleted or outdated info |
| `code` | inline code | Commands, variables, file names |
| > quote | blockquote | Quotations, callouts, notes |
For inline code, use single backticks (`). For code blocks, use triple backticks (```). Escape backticks inside code with double backticks.
3Lists
Markdown supports unordered (bullet), ordered (numbered), and nested lists.
Unordered list:
- Item one
- Item two
- Nested item (2 spaces indent)
- Another nested item
- Item three
Ordered list:
1. First item
2. Second item
1. Nested numbered item
2. Another nested
3. Third item
Task list (GitHub Flavored):
- [x] Completed task
- [ ] Incomplete task
- [ ] Another todoUse -, *, or + for bullets (all render the same). For numbered lists, you can use 1. for all items—Markdown auto-numbers them. Indent 2-4 spaces for nesting.
4Links and Images
Links and images share similar syntax. Images just add an exclamation mark.
Inline link:
[Link text](https://example.com)
[Link with title](https://example.com "Hover title")
Reference-style link (cleaner for repeated URLs):
[Link text][ref-id]
[ref-id]: https://example.com "Optional title"
Image:
Image with link:
[](https://example.com)
Autolinks:
<https://example.com>
<email@example.com>| Element | Syntax |
|---|---|
| Inline link | [text](url) |
| Link with title | [text](url "title") |
| Reference link | [text][id] + [id]: url |
| Image |  |
| Image with link | [](url) |
| Autolink | <url> or <email> |
Always include alt text for images (![alt text]). It improves accessibility, helps SEO, and displays when images fail to load.
Code Blocks
Fenced code blocks with language hints enable syntax highlighting on most platforms.
Inline code: `const x = 42;`
Fenced code block with syntax highlighting:
```javascript
function greet(name) {
console.log(`Hello, ${name}!`);
}
```
Common language identifiers:
- javascript, js, typescript, ts
- python, py
- bash, shell, sh
- json, yaml, xml
- html, css, sql
- markdown, md
- diff (shows +/- changes)Diff highlighting (useful for PRs):
```diff
- const old = "removed line";
+ const new = "added line";
```6Tables
Tables use pipes (|) and hyphens (-). Column alignment is set in the separator row.
Basic table:
| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1 | Cell 2 | Cell 3 |
| Cell 4 | Cell 5 | Cell 6 |
Aligned columns:
| Left | Center | Right |
|:----------|:---------:|----------:|
| Text | Text | Text |
| Aligned | Centered | Right || Alignment | Separator Syntax |
|---|---|
| Left (default) | |-------| |
| Center | |:-----:| |
| Right | |------:| |
Outer pipes are optional. Columns don\
Extended Syntax (GitHub Flavored)
GitHub Flavored Markdown (GFM) adds extra features not in standard Markdown. Many platforms support these.
Task lists:
- [x] Write documentation
- [ ] Review pull request
- [ ] Deploy to production
Footnotes:
Here is a sentence with a footnote.[^1]
[^1]: This is the footnote content.
Emoji shortcodes:
:rocket: :heart: :warning: :+1:
Mentions and references (GitHub):
@username
#issue-number
SHA-hash
Definition lists (some parsers):
Term
: Definition here
Abbreviations (some parsers):
*[HTML]: Hypertext Markup Language
Collapsible sections (GitHub):
<details>
<summary>Click to expand</summary>
Hidden content here.
</details>Support for extended syntax varies by platform. GitHub, GitLab, and Obsidian support most features. Always test on your target platform.
8Markdown Best Practices
Follow these guidelines for clean, readable Markdown that renders correctly everywhere.
- Use consistent heading hierarchy (H1 → H2 → H3, never skip levels)
- Add blank lines before and after headings, lists, and code blocks
- Keep lines under 80-100 characters for readability in source
- Use reference-style links for long URLs or repeated links
- Always add alt text to images for accessibility
- Use fenced code blocks (
- ) over indented code blocks
- Specify language in code blocks for syntax highlighting
# Good: Clear structure with blank lines
## Section Heading
Paragraph text here. Keep it readable.
- List item one
- List item two
## Another Section
More content...
---
# Bad: No spacing, inconsistent formatting
## Section
Paragraph immediately after heading.
- List without blank line before
### Skipped H2 to H3Use a Markdown linter like markdownlint to catch common issues. Many editors have extensions that warn about inconsistencies as you type.
Frequently Asked Questions
What is the difference between Markdown and HTML?
Markdown is a lightweight markup language that converts to HTML. It’s designed to be readable in source form, while HTML is more verbose. Markdown: **bold** → HTML: <strong>bold</strong>. Most Markdown processors also allow inline HTML for complex formatting not supported by Markdown syntax.
How do I create a line break in Markdown?
Two methods: 1) End a line with two or more spaces, then press Enter (soft break). 2) Use <br> HTML tag. For a new paragraph, leave a blank line between text blocks. The two-space method is invisible, so some prefer explicit <br> or blank lines.
What is GitHub Flavored Markdown (GFM)?
GFM is GitHub’s extended Markdown specification. It adds task lists (- [x]), tables, strikethrough (~~text~~), autolinks, code block syntax highlighting, and features like @mentions and #issue references. Many platforms and editors now support GFM extensions.
How do I escape special characters in Markdown?
Use a backslash (\\) before special characters to display them literally: \\* (asterisk), \\# (hash), \\[ (bracket), \\` (backtick), \\| (pipe in tables). Inside code spans and code blocks, characters are automatically escaped.
Can I use HTML inside Markdown?
Yes, most Markdown processors allow inline HTML. This is useful for complex layouts, specific styling, or elements not supported by Markdown (like <details> collapsibles). However, Markdown syntax won’t work inside HTML blocks—use one or the other for a given section.