Markdown Syntax Guide

This guide explains how Markdown syntax works, how different elements are written, and how support varies across Markdown implementations. Each section includes the syntax, practical examples, compatibility notes, and links to dedicated documentation for topics that require a deeper explanation.

Unlike the Markdown Cheat Sheet, which is designed for quick copy-and-paste, this guide explains the purpose and behavior of each Markdown element. If you're learning Markdown or troubleshooting formatting issues, this is the best place to start.

Not every Markdown application supports the same syntax. While most editors understand the core Markdown specification, many also add extensions such as tables, task lists, footnotes, and diagrams. Understanding the difference helps you choose syntax that works across the platforms you use.

💡 Tip: If you're writing content for GitHub, use GitHub Flavored Markdown (GFM). If your content will be viewed in different Markdown editors or static site generators, check which extensions they support before relying on advanced syntax.

Original Markdown includes headings, lists, emphasis, links, images, and blockquotes. CommonMark standardizes core behavior across parsers. GFM adds tables, task lists, strikethrough, fenced code blocks, and automatic links.

Use this page to understand how Markdown syntax works, not just how to write it. Each section explains:

• What the syntax does
• How to write it correctly
• Where it's supported
• Common formatting mistakes
• Links to detailed documentation for advanced topics

If you only need to copy syntax, the Markdown Cheat Sheet is a faster option.

Headings define the structure of a Markdown document and make content easier to navigate. They also help documentation tools, table of contents generators, and search engines understand the hierarchy of your content.

Syntax#

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

Example#

# Project Documentation

## Installation

### Requirements

### Configuration

## Usage

Compatibility#

Best practice: Use a single H1 (#) for the document title, then organize the rest of your content with H2 (##) and H3 (###) headings.

Common Mistakes#

💡 Deep dive: Learn more about heading levels, document structure, and automatic table of contents generation in the Markdown Headings guide.

Paragraphs are created by leaving a blank line between blocks of text. Most Markdown parsers treat consecutive lines as part of the same paragraph unless a blank line separates them.

Example#

This is the first paragraph.

This is the second paragraph.

Compatibility#

Common Mistakes#

Note: Different editors may display extra blank lines differently, but the rendered output is usually the same.

💡 Deep dive: See the Markdown Paragraphs guide for spacing rules, paragraph wrapping, and editor behavior.

A line break starts a new line without creating a new paragraph. Support varies depending on the Markdown implementation.

Method 1 — Two Trailing Spaces#

First line··
Second line

(The dots represent two trailing spaces.)

Method 2 — HTML <br>#

First line<br>
Second line

Compatibility#

Common Mistakes#

Best practice: Use blank lines for new paragraphs and line breaks only when the content needs to stay within the same paragraph, such as addresses, poems, or formatted text.

💡 Deep dive: Read the Markdown Line Breaks guide to understand soft breaks, hard breaks, HTML line breaks, and renderer differences.

Markdown provides lightweight syntax for emphasizing text without using HTML. These formatting options are supported by most modern Markdown implementations.

Bold#

Use bold text to highlight important information.

**Bold Text**

Common mistake: Leave no spaces between the asterisks and the text.

Italic#

Use italics for emphasis, book titles, or introducing new terms.

*Italic Text*

Bold and Italic#

Combine both styles for stronger emphasis.

***Bold Italic***

Strikethrough#

Marks text as removed or no longer relevant.

~~Deprecated~~

Note: Strikethrough is part of GitHub Flavored Markdown and many modern Markdown editors, but it isn't included in the original Markdown specification.

Lists organize related information and are supported by every major Markdown implementation.

Unordered Lists#

- Item One
- Item Two
- Item Three

Alternative markers: * Item or + Item

Ordered Lists#

1. Install
2. Configure
3. Run

Tip: Most Markdown editors automatically continue numbering while you type.

Nested Lists#

- Frontend
  - HTML
  - CSS
  - JavaScript

Common mistake: Inconsistent indentation can produce unexpected rendering across Markdown parsers.

Task Lists#

- [ ] Write documentation
- [x] Review changes

Note: Task lists require GitHub Flavored Markdown or another implementation that supports this extension.

💡 Deep dive: Continue with Markdown Lists and Markdown Task Lists.

Links connect Markdown documents to websites, files, email addresses, or other resources.

Inline Links#

[MDConvertHub](https://mdconverthub.com)

Reference Links#

[Documentation][docs]

[docs]: https://example.com

Automatic Links#

<https://example.com>

Email Links#

<hello@example.com>

Compatibility#

Best practice: Use descriptive link text instead of generic phrases such as "Click here."

💡 Deep dive: Read the complete Markdown Links guide.

Images use the same syntax as links, prefixed with an exclamation mark.

Syntax#

![Alt Text](image.png)

Clickable Images#

[![Project Logo](logo.png)](https://example.com)

Compatibility#

Best practice: Always provide descriptive alt text to improve accessibility and give context when images can't be displayed.

💡 Deep dive: Continue to Markdown Images for image paths, reference images, sizing techniques, and GitHub examples.

Markdown tables organize structured information into rows and columns. They are widely supported in GitHub Flavored Markdown (GFM) and many modern Markdown editors, but they are not part of the original Markdown specification.

Basic Syntax#

| Name | Role | Experience |
|------|------|-----------|
| Alex | Developer | 5 Years |
| Emma | Designer | 3 Years |

Column Alignment#

Compatibility#

Implementation note: If your Markdown renderer doesn't support GFM tables, the table may appear as plain text.

Common Mistakes#

💡 Deep dive: Continue to Markdown Tables for multiline cells, alignment examples, escaped pipes, and GitHub-specific behavior.

Inline Code#

Use inline code to highlight commands, filenames, variables, or short code snippets within a sentence.

`npm install`

Example: Run npm install before starting the project.

Best practice: Reserve inline code for short snippets. Use fenced code blocks for complete examples.

Fenced Code Blocks#

```javascript
console.log("Hello, World!");
```

Language Identifiers#

Common examples include JavaScript, Python, HTML, CSS, JSON, Bash, TypeScript, and PHP.

Compatibility#

Implementation note: Syntax highlighting depends on the renderer, not Markdown itself. Two editors may display the same code block differently.

Common Mistakes#

💡 Deep dive: Read Markdown Code Blocks for syntax highlighting, language identifiers, and renderer support.

Blockquotes highlight quoted text, notes, or callouts.

Syntax#

> This is a blockquote.

Nested Blockquotes#

> Main Quote
>> Nested Quote

Compatibility#

Best practice: Use blockquotes for quoted content or informational notes, not for indentation or layout.

💡 Deep dive: See Markdown Blockquotes for nested quotes, callouts, and GitHub examples.

Horizontal rules visually separate major sections of a document.

Valid syntax includes:

---
***
___

Compatibility#

Common mistake: Leave a blank line above and below a horizontal rule to avoid unexpected rendering.

💡 Deep dive: Read Markdown Horizontal Rules for syntax details and platform notes.

Escape special Markdown characters with a backslash when they should appear as plain text instead of being interpreted as Markdown syntax.

Example#

\*Not italic\*

\# Not a heading

Common characters that can be escaped:

\*
\_
\`
\#
\[
\]
\(
\)
\\

Compatibility#

💡 Deep dive: Continue to Markdown Escaping Characters for parser behavior, code spans, and escaped punctuation.

Many Markdown implementations allow HTML when Markdown syntax alone isn't sufficient.

Example#

<b>Bold</b>

<sup>2</sup>

<sub>2</sub>

<br>

Compatibility#

Implementation note: Some platforms sanitize HTML for security reasons. Tags such as <script> are commonly removed, while simple formatting tags may still work.

Best practice: Prefer native Markdown syntax whenever possible. Use HTML only when Markdown doesn't support the formatting you need.

💡 Deep dive: Read Markdown HTML to learn which tags are commonly supported across different Markdown applications.

GitHub Flavored Markdown (GFM) extends the original Markdown syntax with additional formatting features that are widely used in GitHub repositories, documentation sites, and modern Markdown editors.

💡 Deep dive: Learn more in the GitHub Flavored Markdown (GFM) guide. For README workflows, see GitHub Markdown.

Markdown doesn't render the same way everywhere. Most platforms support the core syntax, while advanced features depend on the Markdown parser they use.

Note: Platform support changes over time. Always check the documentation for the Markdown application you're using before relying on advanced features.

Common Rendering Problems#

Most rendering issues are caused by differences between Markdown implementations, not by the Markdown syntax itself.

Choosing the Right Markdown Features#

If your content will be viewed in different applications, test advanced features such as tables, footnotes, Mermaid diagrams, and HTML before publishing.