Markdown Syntax Guide: From Basics to Advanced

What is Markdown?

Markdown is a lightweight markup language created by John Gruber in 2004. Its purpose is simple: let you write formatted text using plain characters that are readable even without rendering. A Markdown file is just a text file with formatting hints — **bold** for bold, *italic* for italic, # for headings.

Markdown has become the standard writing format for developers and technical writers. GitHub uses it for README files, issues, and pull requests. Static site generators like Hugo, Jekyll, and Astro use it for content. Documentation platforms like GitBook and MkDocs are built on it. Note-taking apps like Obsidian and Notion support it natively.

If you write on the internet — especially anything technical — Markdown is an essential skill. Try our Markdown Preview tool to see your Markdown rendered in real time as you type.

Basic Text Formatting

Headings

Use # symbols to create headings. The number of # determines the level:

• # Heading 1 — Top-level heading (use once per document, like an article title).
• ## Heading 2 — Section heading.
• ### Heading 3 — Subsection heading.
• #### Heading 4 through ###### Heading 6 — Deeper levels (rarely needed).

Emphasis

• *italic* or _italic_ renders as italic.
• **bold** or __bold__ renders as bold.
• ***bold italic*** renders as bold italic.
• ~~strikethrough~~ renders as strikethrough text.

Paragraphs and line breaks

Separate paragraphs with a blank line. For a line break within a paragraph, end the line with two spaces or use <br>. Simply pressing Enter once does not create a new line in most Markdown renderers — the text continues on the same line.

Lists, Links, and Images

Unordered lists

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

- First item
- Second item
  - Nested item
  - Another nested item
- Third item

Ordered lists

Use numbers followed by a period. The actual numbers do not matter — Markdown auto-numbers them:

1. First step
2. Second step
3. Third step

Task lists

Supported on GitHub and many Markdown renderers:

- [x] Completed task
- [ ] Incomplete task
- [ ] Another task

Links

[Link text](https://example.com) creates a clickable link.

[Link text](https://example.com "Tooltip") adds a tooltip on hover.

Images

![Alt text](image-url.jpg) embeds an image. The alt text is important for accessibility and SEO.

Code Blocks and Blockquotes

Inline code

Wrap text in backticks for inline code: `const x = 42` renders as const x = 42.

Code blocks

Use triple backticks with an optional language identifier for syntax highlighting:

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

Common language identifiers: javascript, typescript, python, html, css, json, bash, sql. Most renderers support dozens of languages for syntax highlighting.

Blockquotes

Use > at the start of a line:

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

Blockquotes can be nested (>>) and can contain other Markdown elements.

Tables

Markdown tables use pipes and hyphens:

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Cell 1 | Cell 2 | Cell 3 |
| Cell 4 | Cell 5 | Cell 6 |

Align columns with colons in the separator row:

• :--- left-aligned (default).
• :---: centered.
• ---: right-aligned.

Tables are one of Markdown's weaker areas — complex tables with merged cells or rich content are better handled in HTML. Most Markdown renderers allow inline HTML for cases Markdown cannot handle.

Advanced Markdown Features

Footnotes

Supported in many extended Markdown flavors:

This has a footnote[^1].

[^1]: This is the footnote content.

Definition lists

Some renderers support definition lists:

Term
: Definition of the term.

Automatic links

URLs and email addresses can be auto-linked by wrapping in angle brackets: <https://example.com> or simply pasting the URL (GitHub auto-links bare URLs).

Horizontal rules

Three or more hyphens, asterisks, or underscores on a line: --- or *** or ___.

HTML in Markdown

Most Markdown renderers allow raw HTML. You can use <details> for collapsible sections, <kbd> for keyboard shortcuts, or any other HTML element. Useful when Markdown's formatting is insufficient.

Math (LaTeX)

GitHub and many documentation platforms support LaTeX math: $E = mc^2$ for inline math and $$ blocks for displayed equations.

Markdown Flavors and Compatibility

Not all Markdown is the same. Different platforms extend the base syntax:

• CommonMark: A strict specification of the original Markdown. The baseline standard.
• GitHub Flavored Markdown (GFM): Adds task lists, tables, strikethrough, autolinks, and fenced code blocks. The most widely used flavor.
• MDX: Markdown with JSX components. Used in React-based documentation sites. Lets you embed interactive components in your Markdown.
• MultiMarkdown: Adds footnotes, tables, citations, and cross-references. Popular in academic writing.

When writing Markdown, target GFM unless you know your renderer supports a specific flavor. GFM features are supported nearly everywhere.

Practice your Markdown skills with our Markdown Preview — type Markdown on the left and see the formatted output on the right, updating in real time.