Markdown Syntax

Complete syntax reference for headings, emphasis, links, lists, code, tables and more

Headings

Syntax	Shorthand	Example	Rendered	Notes
`# Heading`	`H1`	`# My Title`	H1	Largest heading; maps to <h1>
`## Heading`	`H2`	`## Section`	H2	Maps to <h2>
`### Heading`	`H3`	`### Subsection`	H3	Maps to <h3>
`#### Heading`	`H4`	`#### Detail`	H4	Maps to <h4>
`##### Heading`	`H5`	`##### Note`	H5	Maps to <h5>
`###### Heading`	`H6`	`###### Fine print`	H6	Smallest heading; maps to <h6>

Emphasis

Syntax	Shorthand	Example	Rendered	Notes
`text`	`Bold`	`hello`	hello	Also __text__
`text`	`Italic`	`hello`	hello	Also _text_
`*text*`	`Bold + Italic`	`*hello*`	hello	Also ___text___
`~~text~~`	`Strikethrough`	`~~hello~~`	hello	Requires GFM support
`code`	`Inline code`	`var x = 1`	var x = 1	Monospace; escapes HTML

Links & Images

Syntax	Shorthand	Example	Rendered	Notes
`[text](url)`	`Inline link`	`[Google](https://google.com)`	Google	Opens in same tab by default
`[text](url "title")`	`Link + title`	`[G](https://g.com "Go")`	Google	Title shown on hover
`[text][ref]`	`Reference link`	`[Google][g] ... [g]: url`	Google	Define URL elsewhere in doc
`![alt](url)`	`Inline image`	`![Logo](logo.png)`	<img>	Alt text improves accessibility
`<url>`	`Autolink`	`<https://example.com>`	link	URL or email becomes clickable

Lists

Syntax	Shorthand	Example	Rendered	Notes
`- item`	`Unordered`	`- Apple - Banana`	* Apple	Also * or + as bullet
`1. item`	`Ordered`	`1. First 2. Second`	1. First	Numbers auto-increment in output
`- nested`	`Nested list`	`- Item - Sub`	* Item > Sub	Indent 2+ spaces to nest
`- [ ] task`	`Task (unchecked)`	`- [ ] Todo`	[ ] Todo	GitHub Flavored Markdown
`- [x] task`	`Task (checked)`	`- [x] Done`	[x] Done	GFM checked task item

Code Blocks

Syntax	Shorthand	Example	Rendered	Notes
```lang	`Fenced block`	```js code ```	<pre>	Language hint enables syntax highlight
`code`	`Indented block`	`let x = 1;`	<pre>	4 spaces or 1 tab indentation
`code`	`Inline code`	Use `npm install`	npm install	Single backtick pair

Blockquotes

Syntax	Shorthand	Example	Rendered	Notes
`> text`	`Blockquote`	`> This is a quote`	" quote	Renders as <blockquote>
`>> text`	`Nested quote`	`>> Inner quote`	"" inner	Double > for nested blockquote
`> Note`	`Callout style`	`> Warning: text`	callout	Bold first word for callout pattern

Tables

Syntax	Shorthand	Example	Rendered	Notes
`\| Col \| Col \|`	`Header row`	`\| Name \| Age \|`	<th>	Pipes define columns
`\|-----\|-----\|`	`Separator`	`\| --- \| --- \|`	divider	Required after header row
`\| :--- \|`	`Left align`	`\| :--- \|`	left	Colon on left side
`\| ---: \|`	`Right align`	`\| ---: \|`	right	Colon on right side
`\| :---: \|`	`Center align`	`\| :---: \|`	center	Colons on both sides

Horizontal Rules

Syntax	Shorthand	Example	Rendered	Notes
`---`	`Rule (hyphens)`	`---`	<hr>	Three or more hyphens
`***`	`Rule (asterisks)`	`***`	<hr>	Three or more asterisks
`___`	`Rule (underscores)`	`___`	<hr>	Three or more underscores

Escaping

Syntax	Shorthand	Example	Rendered	Notes
`\*`	`Escape char`	`\literal\`	literal	Backslash escapes: \\ ` * _ { } [ ] ( ) # + - . !

Frequently Asked Questions

Markdown is a lightweight markup language created by John Gruber in 2004 that lets you write plain text that converts to HTML. A line starting with # becomes an <h1>, **text** becomes bold, and *text* becomes italic. Because it reads naturally as plain text and renders to clean HTML, it became the standard for README files, documentation, forums like Reddit and Stack Overflow, and note-taking apps. Most modern editors and platforms support it out of the box.

CommonMark is a strict, unambiguous specification for Markdown that resolves years of inconsistency between implementations. GitHub Flavored Markdown (GFM) extends CommonMark with task lists (- [ ] / - [x]), tables, strikethrough (~~text~~), and autolinks. Most developer platforms — GitHub, GitLab, VS Code — use GFM. For pure documentation sites, CommonMark is the safer baseline.

A blank line creates a new paragraph. For a line break within a paragraph without starting a new one, end the line with two or more spaces before pressing Enter. Alternatively, some parsers accept a backslash \ at end of line. The safest cross-platform approach is using a blank line for paragraph breaks and <br> HTML tag for mid-paragraph breaks.

Yes — most Markdown parsers allow raw HTML inline. Block-level HTML like <div>, <table>, or <blockquote> must be surrounded by blank lines and must not be indented. Inline HTML like <kbd>, <sup>, <br>, and <span> can be used freely. HTML is useful for features Markdown lacks: colored text, keyboard shortcuts, subscript, or custom attributes.