Markdown Syntax Guide — Everything You Need to Know in 2026

Markdown has quietly become the most important writing format on the internet. It powers GitHub READMEs, documentation sites, blogs, note-taking apps, chat platforms, and even emails. If you write anything technical — or anything at all on the web — you will encounter Markdown. And yet, most people only know about 20% of what it can do.

This guide covers everything. From the absolute basics that every writer needs, through intermediate features that make documentation shine, to advanced GitHub Flavored Markdown extensions that most developers never learn. Every feature includes the raw syntax and what it produces, so you can use this as a living reference.

If you want to practice as you read, open the Markdown Editor and Preview tool on akousa.net in another tab. It renders Markdown in real time, so you can experiment with every example below.

Headings#

Headings are the backbone of any Markdown document. They create structure, enable navigation, and — if you're writing for the web — they matter enormously for SEO. Use the # symbol followed by a space.

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

A few rules that trip people up:

• You must include a space after the # symbols. ##Heading without a space will not render as a heading in most parsers.
• There is no heading level 7. Six levels is the maximum, matching HTML's <h1> through <h6>.
• Most style guides recommend using only one # (H1) per document — it serves as the title. Use ## and ### for sections and subsections.
• Leave a blank line before and after headings. Some parsers require it, and it improves readability in the source.

Alternative Heading Syntax#

For H1 and H2 only, there is an underline syntax:

Heading Level 1
================
 
Heading Level 2
----------------

This is called "Setext-style" headings. It looks elegant in plain text but offers no advantage over the # syntax and only supports two levels. Most writers stick with # exclusively.

Paragraphs and Line Breaks#

Paragraphs are the simplest element in Markdown. Just write text. Separate paragraphs with a blank line.

This is the first paragraph. It can span
multiple lines in the source file and it
will still render as a single paragraph.
 
This is the second paragraph.

To create a line break within a paragraph (a <br> tag) without starting a new paragraph, end a line with two or more spaces, or use a backslash:

This is the first line.
This is the second line (same paragraph).
 
This is the first line.\
This is the second line (same paragraph).

The trailing-spaces method is invisible and error-prone — editors often strip trailing whitespace. The backslash method is cleaner and recommended.

Text Emphasis and Formatting#

Bold and Italic#

*italic text* or _italic text_
 
**bold text** or __bold text__
 
***bold and italic*** or ___bold and italic___

Renders as: italic text, bold text, bold and italic.

Best practice: use asterisks (*) rather than underscores (_). Underscores inside words like some_variable_name can cause unexpected rendering in some parsers. Asterisks never have this problem.

Strikethrough#

~~This text is crossed out.~~

Renders as: This text is crossed out.

Strikethrough is technically a GitHub Flavored Markdown (GFM) extension, not part of the original spec. But it's supported virtually everywhere now.

Combining Emphasis#

You can nest formatting:

This is **bold with *italic* inside**.
 
This is ~~**bold strikethrough**~~.

Blockquotes#

Use the > character to create blockquotes. They're perfect for callouts, citations, or highlighting important information.

> Markdown is intended to be as easy-to-read
> and easy-to-write as is feasible.
>
> — John Gruber

Markdown is intended to be as easy-to-read and easy-to-write as is feasible.

— John Gruber

Nested Blockquotes#

> First level of quoting.
>
> > Nested blockquote.
>
> Back to the first level.

First level of quoting.

Nested blockquote.

Back to the first level.

Blockquotes can contain any other Markdown element — headings, lists, code blocks, and more. They are essentially a container.

Lists#

Unordered Lists#

Use -, *, or + followed by a space:

- First item
- Second item
- Third item

• First item
• Second item
• Third item

Pick one marker and stick with it throughout your document. - is the most common convention.

Ordered Lists#

Use numbers followed by a period and a space:

1. First item
2. Second item
3. Third item

1. First item
2. Second item
3. Third item

A useful quirk: the actual numbers don't matter. Markdown will render them sequentially regardless:

1. First item
1. Second item
1. Third item

This still renders as 1, 2, 3. Many writers use 1. for every item so they don't have to renumber when reordering.

Nested Lists#

Indent with two or four spaces (or one tab) to create sublists:

- Main item
  - Sub-item
  - Another sub-item
    - Third level
- Another main item

• Main item
  • Sub-item
  • Another sub-item
    • Third level
• Another main item

Mixed Lists#

You can combine ordered and unordered:

1. First step
   - Detail about first step
   - Another detail
2. Second step
   - Detail about second step

1. First step
   • Detail about first step
   • Another detail
2. Second step
   • Detail about second step

Task Lists (GFM)#

GitHub Flavored Markdown adds interactive checkboxes:

- [x] Write the introduction
- [x] Add code examples
- [ ] Proofread the article
- [ ] Publish

• Write the introduction
• Add code examples
• Proofread the article
• Publish

Task lists are incredibly useful in GitHub issues and pull request descriptions for tracking progress.

Links#

Inline Links#

[akousa.net](https://akousa.net)
 
[Markdown Editor](https://akousa.net/tools/markdown-editor "Open the Markdown Editor")

The title in quotes is optional — it appears as a tooltip on hover.

Reference Links#

For documents with many links, reference-style keeps the text clean:

Check out [akousa.net][1] for developer tools,
or read the [documentation][docs].
 
[1]: https://akousa.net
[docs]: https://akousa.net/docs "Documentation Hub"

The reference labels are case-insensitive and don't appear in the rendered output.

Autolinks#

Most Markdown parsers automatically convert URLs and email addresses into clickable links:

https://akousa.net
 
<https://akousa.net>
 
<contact@example.com>

Wrapping in angle brackets (< >) is more reliable across parsers. Plain URL autolinks are a GFM feature.

Images#

Images use the same syntax as links, prefixed with !:

![Alt text for the image](https://example.com/image.png)
 
![Alt text](https://example.com/image.png "Optional title")

The alt text is critical for accessibility and SEO. Always write meaningful alt text that describes what the image shows.

Images with Links#

Wrap an image in a link by nesting the syntaxes:

[![Alt text](https://example.com/image.png)](https://example.com)

Reference-Style Images#

Just like reference links:

![Alt text][logo]
 
[logo]: https://example.com/logo.png "Company Logo"

Code#

Inline Code#

Wrap text in single backticks for inline code:

Use the `console.log()` function to debug.

Use the console.log() function to debug.

If your code contains backticks, use double backticks:

``Use `backticks` inside code spans.``

Fenced Code Blocks#

Triple backticks create code blocks. Add a language identifier for syntax highlighting:

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
```

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

Supported languages vary by renderer, but common ones include javascript, python, typescript, html, css, bash, json, yaml, sql, rust, go, java, c, cpp, and dozens more.

Indented Code Blocks#

Indent lines by four spaces or one tab:

    function hello() {
      return "world";
    }

This older syntax has no language highlighting support. Fenced code blocks are superior in every way.

Horizontal Rules#

Three or more hyphens, asterisks, or underscores on a line by themselves:

---
 
***
 
___

All three produce the same result. --- is most common. Use horizontal rules sparingly to separate major sections — headings are usually a better choice for structure.

Tables (GFM)#

Tables are a GitHub Flavored Markdown extension. They use pipes and hyphens:

| Feature    | Markdown | HTML    |
| ---------- | -------- | ------- |
| Bold       | `**text**` | `<strong>` |
| Italic     | `*text*`   | `<em>`     |
| Code       | `` `text` ``  | `<code>`   |

Column Alignment#

Use colons in the separator row:

| Left-aligned | Center-aligned | Right-aligned |
| :----------- | :------------: | ------------: |
| Left         | Center         | Right         |
| Text         | Text           | 123           |
| More         | More           | 456           |

Tips for working with tables:

• The columns don't need to be perfectly aligned in the source — but aligning them makes the source much more readable.
• You can use inline formatting (bold, italic, code, links) inside table cells.
• Tables cannot contain block-level elements like lists, code blocks, or headings.
• For complex tables, consider using HTML directly inside your Markdown.

Footnotes#

Footnotes let you add references without cluttering the main text:

Here is a sentence with a footnote.[^1]
 
[^1]: This is the footnote content.

Here is a sentence with a footnote.¹

Multi-line footnotes use indentation:

[^longnote]: This is a longer footnote with
    multiple paragraphs.
 
    Indent subsequent paragraphs by four spaces.

Footnotes are supported in most modern Markdown parsers, though they are not part of the original specification or GFM. They are part of the PHP Markdown Extra and CommonMark extensions.

Definition Lists#

Some parsers support definition lists:

Markdown
: A lightweight markup language for creating formatted text.
 
HTML
: The standard markup language for documents on the World Wide Web.

Definition lists are not part of GFM. Support varies by platform — they work in PHP Markdown Extra, Pandoc, and several static site generators.

Escaping Special Characters#

If you need to display a character that Markdown would normally interpret as formatting, prefix it with a backslash:

\*This is not italic\*
 
\# This is not a heading
 
\- This is not a list item
 
\`This is not code\`

Characters you can escape: \, `, *, _, { }, [ ], ( ), #, +, -, ., !, |.

HTML in Markdown#

Markdown was designed to coexist with HTML. You can drop raw HTML into any Markdown document:

This is a paragraph with <abbr title="Hypertext Markup Language">HTML</abbr> inside.
 
<div style="padding: 16px; background: #f0f0f0; border-radius: 8px;">
  <p>This is a styled HTML block inside Markdown.</p>
</div>

Important: Markdown formatting is not processed inside block-level HTML elements (<div>, <table>, <pre>, etc.). If you open a <div>, everything inside it is treated as raw HTML until the closing </div>.

Markdown is processed inside inline HTML elements (<span>, <em>, <a>, etc.).

GitHub Flavored Markdown (GFM) Extensions#

GitHub Flavored Markdown builds on the CommonMark spec with several practical extensions. Since GitHub is where most developers encounter Markdown, understanding GFM is essential.

Autolinked References#

GitHub automatically links certain references:

Issue: #123
PR: #456
Commit: a1b2c3d
User: @username

These only work on GitHub itself, not in general Markdown renderers.

Syntax Highlighting in Code Blocks#

GFM supports syntax highlighting for hundreds of languages. This feature alone makes GFM-compatible renderers worth using. Here are examples in several languages:

```python
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n - 1) + fibonacci(n - 2)
```
 
```sql
SELECT users.name, COUNT(orders.id) AS order_count
FROM users
LEFT JOIN orders ON users.id = orders.user_id
GROUP BY users.name
HAVING order_count > 5;
```
 
```yaml
server:
  host: localhost
  port: 3000
  database:
    name: myapp
    pool_size: 10
```

Alerts (Admonitions)#

A more recent GFM addition — alert blocks for callouts:

> [!NOTE]
> Useful information that users should know.
 
> [!TIP]
> Helpful advice for doing things better.
 
> [!IMPORTANT]
> Key information users need to know.
 
> [!WARNING]
> Urgent info that needs immediate user attention.
 
> [!CAUTION]
> Advises about risks or negative outcomes.

These render as styled callout boxes on GitHub. They're incredibly useful for documentation. Not all Markdown renderers support this syntax yet, but adoption is growing.

Collapsed Sections#

Use HTML <details> for collapsible content:

<details>
<summary>Click to expand</summary>
 
This content is hidden by default.
 
- You can use Markdown inside.
- Lists, code blocks, everything works.
 
</details>

This is technically HTML, not Markdown, but it's so commonly used in GitHub issues and READMEs that it's become part of the GFM ecosystem.

Advanced Formatting Patterns#

Nested Blockquotes with Code#

> Here is a quote with code:
>
> ```python
> print("Hello from a blockquote!")
> ```
>
> And the quote continues.

Here is a quote with code:

python

print("Hello from a blockquote!")

And the quote continues.

Complex List Items#

List items can contain multiple paragraphs, code blocks, and other elements. Indent continuation content by the same amount as the list text:

1. First step of the process.
 
   Additional explanation about this step. This paragraph
   is part of the first list item.
 
   ```bash
   npm install my-package

2. Second step with a sub-list:
   • Sub-item one
   • Sub-item two

### Combining Tables and Code

When documenting APIs or CLI tools, tables with inline code are powerful:

```markdown
| Command       | Description            | Example              |
| ------------- | ---------------------- | -------------------- |
| `git init`    | Create a new repo      | `git init my-project`|
| `git clone`   | Clone an existing repo | `git clone <url>`    |
| `git status`  | Check working tree     | `git status -s`      |

Common Mistakes and How to Avoid Them#

Forgetting blank lines. Many Markdown issues come from missing blank lines before and after block elements. Always put a blank line before headings, lists, code blocks, blockquotes, and tables.

Inconsistent list markers. Mixing -, *, and + within the same list can cause unexpected behavior. Pick one and stick with it.

Not escaping special characters. If your text contains characters like *, _, #, or |, and you don't want them interpreted as Markdown, escape them with a backslash.

Broken indentation in nested lists. Nested list items must be indented to the content start position of the parent item, not just by a tab. This is the single most common source of list rendering bugs.

Using tabs vs. spaces inconsistently. Some parsers handle tabs differently. Spaces are safer and more predictable.

Missing language identifiers on code blocks. Always specify the language after the opening triple backticks. Without it, you lose syntax highlighting, which makes code much harder to read.

Markdown Editors and Tools#

Writing Markdown is easy in any text editor, but a good tool makes the experience significantly better. Here's what's available in 2026:

Browser-based editors are the fastest way to start. The Markdown Editor on akousa.net gives you a live split-pane preview as you type, supports GFM extensions, and requires no installation. It's particularly useful when you need to quickly draft a README or check how your Markdown will render.

Desktop editors like VS Code (with the Markdown All in One extension), Obsidian, Typora, and Zettlr offer deeper integration with your file system and workflow.

CLI tools like markdownlint and prettier can lint and format your Markdown files as part of a CI/CD pipeline, catching formatting issues before they reach production.

Markdown vs. Alternatives#

Why Markdown over other lightweight markup languages?

Markdown wins on simplicity and ecosystem size. If you need more power (cross-references, includes, custom directives), AsciiDoc or reStructuredText might serve you better. But for 90% of documentation and writing needs, Markdown is the right choice.

Quick Reference Cheat Sheet#

Here's a condensed reference you can bookmark:

# H1            ## H2           ### H3
 
**bold**        *italic*        ~~strikethrough~~
 
[Link text](url)                ![Alt](image-url)
 
- Unordered     1. Ordered      - [x] Task list
 
> Blockquote
 
`inline code`
 
---
 
| Col 1 | Col 2 |
| ----- | ----- |
| Data  | Data  |
 
Footnote reference[^1]
[^1]: Footnote content.

Keep this reference handy. Better yet, keep the akousa.net Markdown Editor bookmarked for when you need to test syntax quickly.

Wrapping Up#

Markdown is deceptively simple. The basics take five minutes to learn. But the full specification — with GFM extensions, nested structures, and HTML escape hatches — gives you enough power to write anything from a quick comment to comprehensive technical documentation.

The key to getting good at Markdown is the same as any tool: use it. Write your notes in Markdown. Write your README files by hand instead of copying templates. Experiment with tables and nested lists until the syntax becomes muscle memory.

If you found this guide useful, you might also want to explore other developer-focused tools on akousa.net — from JSON formatters and regex testers to the Markdown editor mentioned throughout this post. Every tool runs entirely in your browser with nothing to install.