The Complete Markdown Syntax Guide: Every Rule, Extension, and Feature Explained with Examples

What is Markdown?

Markdown is a lightweight markup language.

1. Basic Syntax (Core Markdown)

These are the elements defined in John Gruber's original Markdown specification. They work everywhere Markdown is supported.

1.1 Headings

Markdown supports six levels of headings, corresponding to HTML <h1> through <h6>:

Rules:

• Always put a space after the # signs
• Use headings sequentially (do not jump from H2 to H5)
• Use only one H1 per page (the title)
• ATX-style (#) is preferred over Setext-style (=== under text)

Alternative syntax (Setext):

Underline heading text with === (H1) or --- (H2).

1.2 Paragraphs and Line Breaks

Paragraphs are separated by a blank line. Line breaks require two trailing spaces or a backslash at the end of a line.

1.3 Emphasis (Bold and Italic)

Pro tip: Use asterisks (*) rather than underscores (_) for better compatibility. Underscores in the middle of words (like file_name) will not trigger italic.

1.4 Blockquotes

Create blockquotes with the > character. They can contain other Markdown elements as long as everything is preceded by >.

1.5 Lists (Ordered and Unordered)

Unordered lists use *, -, or + with indent for nesting. Ordered lists use numbers followed by a period. Use 1. for every item and the renderer handles sequential numbering.

Important rules:

• Indent nested items by 2 or 4 spaces (be consistent)
• Leave a blank line between list items for paragraphs inside list items

1.6 Code (Inline and Blocks)

Inline code uses single backticks: `code` renders as code.

Code blocks are traditionally created by indenting with 4 spaces. The modern approach uses fenced code blocks (see GFM section).

1.7 Horizontal Rules

Use three or more *, -, or _ on a line. Include a blank line before and after to avoid being parsed as a Setext heading.

1.8 Links

Inline links: [MarkdownMaster Editor](https://markdownmaster.site/editor/) renders as MarkdownMaster Editor.

With title attribute: [MarkdownMaster](https://markdownmaster.site/ "Free Online Markdown Editor")

Reference-style links define the URL once and reference it multiple times.

URLs and email addresses: Enclose in angle brackets: <https://markdownmaster.site>.

1.9 Images

Follow the same pattern as links with a leading !: ![Alt text](https://example.com/image.png "Optional title"). Always include descriptive alt text for accessibility and SEO.

1.10 Escaping Characters

Use the backslash \ to display literal Markdown characters: \*, \#, \[, \(, \|, and so on.

2. GitHub Flavored Markdown (GFM)

GFM extends standard Markdown with features specifically useful for code collaboration and technical documentation. It is the default on GitHub, GitLab, and many modern platforms.

2.1 Tables

Tables use pipes (|) and dashes (-) to define columns and headers. Alignment is controlled with colons in the separator row: :--- (left), :---: (center), ---: (right). For a dedicated deep-dive, see our complete Markdown tables guide.

2.2 Fenced Code Blocks with Syntax Highlighting

Use three backticks or tildes to create fenced code blocks. Add a language identifier for syntax highlighting.

2.3 Task Lists (Checkboxes)

Create task lists with - [ ] (incomplete) and - [x] (complete). Task lists work in any list context.

2.4 Strikethrough

Wrap text with double tildes: ~~crossed out~~ renders as crossed out.

2.5 Autolinks

GFM automatically turns URLs into clickable links: https://markdownmaster.site (no brackets needed).

2.6 Disallowed Raw HTML

For security, GFM strips certain HTML tags. Safe tags like <a>, <img>, <strong>, <em>, <code>, <pre>, <blockquote>, <table> are allowed. Unsafe tags like <script>, <iframe> are removed.

3. Extended Syntax (Common Extensions)

These features are not part of the original Markdown spec or GFM, but are supported by many popular Markdown processors and editors.

3.1 Tables (Advanced)

Multi-line tables and grid tables are supported in processors like Pandoc.

3.2 Footnotes

Add footnotes with [^label] and define them at the bottom.

3.3 Heading IDs

Some processors let you add custom IDs to headings: ### My Heading {#custom-id}. This allows deep linking to specific sections.

3.4 Definition Lists

Supported in Pandoc and Kramdown for glossary-style content where a term has one or more definitions.

3.5 Highlight and Subscript/Superscript

Some processors support ==highlighted text== (highlighted), X^2^ (X²), and H~2~O (H₂O). Not universally supported.

3.6 Emoji

Most modern Markdown platforms support emoji shortcodes: :smile: becomes smiley, :rocket: becomes rocket, :+1: becomes thumbs up. GitHub and GitLab have excellent emoji support.

3.7 Mathematical Expressions (LaTeX)

Rendered by MathJax or KaTeX in supporting platforms. Use $E = mc^2$ for inline math and $$...$$ for display math.

3.8 Diagrams (Mermaid)

GitHub, GitLab, and Notion support Mermaid diagram code blocks. Mermaid supports flowcharts, sequence diagrams, Gantt charts, class diagrams, and more.

4. Best Practices

See also: Markdown for Developers — how to use these features in real-world development workflows.

1. Use blank lines around block elements - headings, lists, code blocks, and blockquotes should be separated by blank lines.
2. Prefer asterisks over underscores - *italic* and **bold** avoid issues with filenames.
3. Use fenced code blocks - Always cite the language for syntax highlighting.
4. Lazy numbering - Use 1. for all ordered list items.
5. Keep lines under 80-100 characters for readability in diff views.
6. Alt text always - Every image needs meaningful alt text.
7. One H1 per page - Use a single # Title per document.
8. Test with an editor - Use the MarkdownMaster Editor to preview before publishing.

5. Complete Example Document

Here is a full Markdown document demonstrating syntax in context:

# Project Documentation Guide

## Getting Started

This guide helps you set up and run the project.

### Prerequisites

- **Node.js** v18 or later
- **npm** v9 or later
- A code editor (VS Code recommended)

### Installation

1. Clone the repository
2. Install dependencies: npm install
3. Start the server: npm run dev

> Tip: Use npm run build for production.

## API Reference

| Header | Value | Required |
|--------|-------|----------|
| X-API-Key | Your secret key | Yes |
| Content-Type | application/json | Yes |

### POST /api/users

Create a new user with name and email fields.

## Configuration

- ~~debug: true~~ (deprecated)
- port: Server port (default: 3000)
- features: Feature flags for markdown-editor and export-html

## Contributing

- [x] Read the contributing guide
- [ ] Set up development environment
- [ ] Write tests
- [ ] Submit a pull request

Open this in MarkdownMaster Editor to see it rendered live.

6. Quick Reference Cheat Sheet

Ready to practice? Open the MarkdownMaster Editor - a free online Markdown editor with live preview and HTML export.

Bookmark this page - it is the only Markdown syntax guide you will ever need.