Markdown: Complete Syntax Reference for Writers and Developers

Markdown is everywhere. It is the default writing format on GitHub, the backbone of most static site generators, the native language of tools like Obsidian and Notion, and the format developers reach for when writing READMEs, documentation, and technical notes. Despite being ubiquitous, many writers and developers only learn the basics — bold, italic, and a few heading levels — and miss the features that make Markdown genuinely powerful for structured writing.

You can write and preview Markdown instantly using the BrowseryTools Markdown Editor — free, no sign-up, everything stays in your browser.

Who Created Markdown and Why

Markdown was created by John Gruber, in collaboration with Aaron Swartz, and released in 2004. Gruber's stated goal was to create a plain-text writing format that is readable as-is — before any rendering — and that converts cleanly to valid HTML. The name is a play on "markup language" (HTML is HyperText Markup Language), flipping the concept: instead of adding syntax to control formatting, Markdown uses the natural punctuation habits people had already developed in plain-text email.

The motivation was practical. HTML is verbose and distracting to write inline. A sentence like <p>This is <strong>important</strong> text.</p> requires significant mental overhead compared to This is **important** text. Gruber wanted bloggers and writers to focus on words, not tags. The original Markdown specification was a Perl script that converted plain-text Markdown files to HTML.

Basic Syntax

The core Markdown syntax covers everything most writers need for structured documents.

Headings

Use hash signs to create headings. One hash for H1, two for H2, up to six for H6. Most style guides recommend only one H1 per document (typically the title) and using H2–H4 for content hierarchy.

# Heading 1
## Heading 2
### Heading 3
#### Heading 4

Emphasis and Strong

*italic* or _italic_
**bold** or __bold__
***bold and italic***
~~strikethrough~~

Links and Images

[Link text](https://example.com)
[Link with title](https://example.com "Page title")
![Alt text](image.png)
![Alt text](image.png "Image title")

Lists

Unordered lists use hyphens, asterisks, or plus signs. Ordered lists use numbers followed by periods. Indented items (2 or 4 spaces) create nested lists.

- Unordered item
- Another item
  - Nested item

1. First
2. Second
3. Third

Code

Inline code uses single backticks. Fenced code blocks use triple backticks with an optional language identifier for syntax highlighting.

Use `console.log()` for debugging.

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

Blockquotes

> This is a blockquote.
> It can span multiple lines.
>
> > Nested blockquotes work too.

Horizontal Rules

Three or more hyphens, asterisks, or underscores on a line by themselves create a horizontal rule.--- is the most common convention.

Extended Syntax

The original Markdown specification left out several features that writers commonly need. Extended syntax, supported by most modern processors, adds these capabilities.

Tables

| Column 1  | Column 2  | Column 3  |
|-----------|:---------:|----------:|
| Left      | Center    | Right     |
| aligned   | aligned   | aligned   |

The colon position in the separator row controls alignment: left (default), center (colons on both sides), or right (colon on the right).

Task Lists

- [x] Write first draft
- [x] Peer review
- [ ] Final edits
- [ ] Publish

Footnotes

Here is a claim that needs a citation.[^1]

[^1]: The supporting source or explanation goes here.

Markdown Flavors: CommonMark, GFM, and MDX

The original Markdown specification had ambiguities — places where processors made different decisions about edge cases. This led to incompatible implementations across different tools. Several standards efforts emerged to resolve this.

• CommonMark — a rigorous specification that resolves every ambiguity in the original Markdown spec with a formal test suite. Adopted by Discourse, Reddit, Stack Overflow, and many others. The most interoperable flavor.
• GitHub Flavored Markdown (GFM) — GitHub's extension of CommonMark that adds tables, task lists, strikethrough, autolinks, and literal URLs. If you write README files or GitHub comments, you are using GFM.
• MDX — Markdown extended with JSX component support, used heavily in React-based documentation sites (Next.js docs, Docusaurus, Astro). Allows importing and embedding React components directly in Markdown files.
• MultiMarkdown / Pandoc Markdown — feature-rich extensions for academic writing, with support for citations, math equations (LaTeX), and complex table formatting.

Where Markdown Is Used

• GitHub and GitLab — README files, issues, pull requests, wikis, and comments all render Markdown
• Notion — supports Markdown import/export and a subset of Markdown shortcuts for inline formatting
• Obsidian — a knowledge management app built entirely on Markdown files with wikilink extensions
• Static site generators — Jekyll, Hugo, Gatsby, Astro, and Next.js all use Markdown or MDX as the default content format
• Documentation platforms — ReadTheDocs, GitBook, and Docusaurus are built around Markdown
• Chat platforms — Slack, Discord, and Teams support subsets of Markdown for message formatting
• Email clients — some clients (Superhuman, HEY) support Markdown input

Markdown vs Rich Text Editors

Rich text editors (WYSIWYG — What You See Is What You Get) like Google Docs, Microsoft Word, or Contentful's built-in editor show formatted output while you type. Markdown shows the raw source. The tradeoffs are real.

• Markdown advantages — plain text files, works in any editor, version-controllable with git, no vendor lock-in, fast keyboard-only workflow
• Rich text advantages — immediately visual, no syntax to learn, easier for non-technical contributors, better for complex formatting (footnotes, comments, tracked changes)

For technical writing, developer documentation, and personal knowledge management, Markdown's portability and version-control compatibility make it the better choice. For collaborative business documents or content with complex formatting requirements, a rich text editor is often more practical.

Common Markdown Mistakes

• Missing blank lines — most block elements (headings, lists, code blocks) require a blank line before and after them to render correctly
• Spaces after hash signs — ##Heading without a space after the hashes is not a heading in most processors
• Inconsistent list markers — mixing - and * in the same list can produce unexpected results in some processors
• Forgetting to escape special characters — asterisks, underscores, and backticks inside text need a backslash escape if they should render literally
• Assuming extended syntax is universal — tables and task lists are GFM features not supported by all processors; check your target environment

The BrowseryTools Markdown Editor provides a live preview so you can catch rendering issues immediately as you write, without copying text into another tool. Paste your Markdown and see the rendered HTML output side by side.