Markdown Syntax — Complete Guide with Live Examples

Markdown is a plain-text formatting syntax designed to be readable as-is and convertible to HTML. A file written in Markdown looks clean as raw text and renders as formatted HTML when processed. It’s the standard format for README files, documentation, blog posts, and developer writing tools.

Use the Markdown Preview on this site to write and preview Markdown in real time, with GitHub-Flavored Markdown (GFM) support.

Basic syntax

Headings

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

Alternative syntax for H1 and H2 (underline style):

Heading 1
=========

Heading 2
---------

Paragraphs and line breaks

Paragraphs are separated by a blank line:

This is paragraph one.

This is paragraph two.

For a line break within a paragraph (renders as <br>), end a line with two or more spaces:

Line one  
Line two

Emphasis

*italic* or _italic_
**bold** or __bold__
***bold italic*** or ___bold italic___
~~strikethrough~~

Renders as: italic, bold, bold italic, strikethrough

Horizontal rule

---
or
***
or
___

All three produce a <hr> element.

Lists

Unordered lists

- Item one
- Item two
  - Nested item (2 spaces indent)
  - Another nested item
- Item three

Also valid with * or + as the bullet character.

Ordered lists

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

The actual numbers don’t matter — Markdown counts the items. This is valid:

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

Task lists (GitHub Flavored Markdown)

- [x] Completed task
- [ ] Uncompleted task
- [ ] Another task

Renders as checkboxes in GitHub, Notion, and many other GFM renderers.

Links and images

Links

[Link text](https://example.com)
[Link text](https://example.com "Optional title")

Reference-style links (define once, use multiple times):

[Link text][reference]

[reference]: https://example.com "Optional title"

Auto-links (URLs become clickable in many parsers):

<https://example.com>
<user@example.com>

Images

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

Image with link:

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

The alt text serves two purposes: it’s read by screen readers for accessibility, and it displays if the image fails to load. Always write meaningful alt text.

Code

Inline code

Use the `code` formatting for inline code references.

Backtick pairs wrap inline code: const x = 1 renders with monospace font.

Fenced code blocks

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

The language identifier after the opening backticks enables syntax highlighting in most renderers. Common language identifiers: javascript, typescript, python, bash, css, html, json, yaml, sql, rust, go, java, cpp, c, markdown.

Indented code blocks (4 spaces):

    code here
    more code

Fenced code blocks with triple backticks are preferred over indentation — they support language identifiers and don’t conflict with list indentation.

Blockquotes

> This is a blockquote.
>
> Blank line with > continues the blockquote.

> Nested quotes:
>
> > A nested blockquote

Tables (GitHub Flavored Markdown)

| Header 1 | Header 2 | Header 3 |
|---|---|---|
| Cell | Cell | Cell |
| Cell | Cell | Cell |

Column alignment:

| Left | Center | Right |
|:---|:---:|---:|
| Left-aligned | Centered | Right-aligned |

The colons in the separator row define alignment: :--- = left, :---: = center, ---: = right.

Tables in standard Markdown are verbose but necessary for structured data. The Markdown Preview renders GFM tables.

HTML in Markdown

Standard Markdown allows inline HTML. This is useful for elements Markdown doesn’t support natively:

<details>
  <summary>Click to expand</summary>
  
  Hidden content here.
</details>

<kbd>Ctrl</kbd>+<kbd>C</kbd>

<mark>Highlighted text</mark>

GitHub renders <details>, <summary>, <kbd>, and other HTML elements. Some parsers sanitize HTML for security — check your target renderer.

Escaping characters

Prefix special Markdown characters with \ to display them literally:

\* Not italicized \*
\# Not a heading
\[Not a link\]
\`Not code\`

Characters that need escaping: \ * _ { } [ ] ( ) # + - . !

Footnotes (extended syntax)

Many Markdown processors (including GitHub) support footnotes:

This needs a footnote.[^1]

[^1]: This is the footnote text.

GitHub Flavored Markdown (GFM) extensions

GFM adds several elements beyond CommonMark (the standard spec):

• Task lists (- [x] checkboxes)
• Tables
• Strikethrough (~~text~~)
• Autolinks (bare URLs become links)
• Emoji (:smile:, :rocket:)
• Mentions (@username in GitHub context)
• Issue references (#123 links to GitHub issues)

The Markdown Preview renders GFM, matching what GitHub, VS Code, and most developer tools display.

Markdown to HTML conversion

Markdown is converted to HTML by a parser. The most common parsers:

Most parsers produce the same output for standard syntax. Differences emerge with extended syntax (footnotes, tables, attributes) — check your parser’s documentation.

Writing Markdown efficiently

VS Code

VS Code has built-in Markdown preview (Ctrl+Shift+V or Cmd+Shift+V). Split view with Ctrl+K V opens a side-by-side preview.

Extensions worth installing:

• Markdown All in One — auto-completion, table formatting, keyboard shortcuts
• markdownlint — catches style issues and common errors
• Prettier — auto-formats Markdown files

Obsidian

Obsidian is a popular knowledge management tool that uses Markdown files as its format. It extends Markdown with wiki-style [[internal links]], callouts, and graph views.

README files

GitHub renders README.md files in repository root directories. Conventions:

• Start with project name as H1
• Brief description (1–2 sentences)
• Installation instructions
• Usage examples with code blocks
• License mention

Use the Markdown Preview to verify your README renders correctly before pushing, especially for tables and code blocks.

Common Markdown mistakes

Missing blank lines before/after block elements. A heading immediately after a paragraph (no blank line) may not render as a heading in all parsers. Always add blank lines before and after headings, lists, code blocks, and blockquotes.

Inconsistent list indentation. Nested lists require consistent indentation. Most parsers use 2 or 4 spaces; mixing causes incorrect nesting.

Spaces in links. [text](url with spaces) breaks in most parsers. Encode spaces as %20 or use angle brackets: [text](<url with spaces>).

Forgetting alt text on images. ![]() is valid syntax but meaningless for screen readers. Always write descriptive alt text.

Using inline HTML for what Markdown supports natively. Writing <b>bold</b> instead of **bold** works but is unnecessary verbosity that makes the source harder to read.

Related tools

• Markdown Preview — live Markdown editor with GFM support
• Text Diff — compare two versions of a Markdown document
• Word Counter — count words in Markdown files