Markdown: The Complete Guide to Syntax, Flavors, and Best Practices

What is Markdown?

Markdown is a lightweight markup language created by John Gruber and Aaron Swartz in 2004. The core idea is deceptively simple: add a handful of plain-text punctuation conventions that translate directly into HTML. A pound sign becomes a heading, asterisks wrap bold text, a hyphen starts a list item. The raw file stays readable by a human — no angle brackets, no tag soup — while still producing clean, structured HTML when passed through any Markdown parser.

That dual nature is why Markdown has become the default writing format for developers. It works in a plain-text editor, survives version control with meaningful diffs, and renders beautifully across GitHub, documentation platforms, static-site generators, and note-taking apps. You write once and the same source file works everywhere.

Why Markdown became the standard

Several factors pushed Markdown from a niche blogging tool to an industry default:

• Readable in raw form. A README.md is perfectly legible in a terminal without rendering. No other markup language shares that property.
• Minimal learning curve. The core syntax fits on a single page. Most developers are productive in under an hour.
• Version-control friendly. Because it is plain text, Git diffs show exactly what changed. Binary word-processor formats cannot do this.
• Portable. A .md file opens in any text editor and renders in any Markdown-aware tool. There is no proprietary lock-in.
• GitHub adoption. When GitHub chose Markdown for READMEs, issues, and pull requests, it became the lingua franca of open-source documentation overnight.

Full Markdown syntax reference

The following sections cover every element of standard Markdown. You can try all of these live in the Markdown Editor — type on the left and watch the preview update on the right in real time.

Headings

Headings are created with one to six # characters followed by a space. The number of hashes maps directly to HTML heading levels h1 through h6.

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

An alternative "setext" style uses underlines of equals signs or dashes for h1 and h2 respectively, but the # syntax is almost universally preferred because it is unambiguous and works for all six levels.

Bold and italic emphasis

Wrap text with asterisks or underscores to add emphasis. Use one for italic, two for bold, and three for bold italic.

*italic* or _italic_
**bold** or __bold__
***bold italic*** or ___bold italic___

Asterisks are generally preferred because underscores inside words (like file_name_here) can trigger unwanted italic on some parsers. Stick with asterisks for consistent results across tools.

Unordered and ordered lists

Start each item with a hyphen, asterisk, or plus sign for an unordered list. Use numbers followed by a period for ordered lists. Indent with two or four spaces to nest items.

- Item one
- Item two
  - Nested item
  - Another nested item
- Item three

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

The actual numbers you write in an ordered list do not matter to most parsers — they will count from 1 regardless. Writing 1. 1. 1. is a common pattern that makes reordering easier during editing.

Links

Inline links wrap the display text in square brackets and the URL in parentheses. Add an optional title in quotes for a tooltip.

[Link text](https://example.com)
[Link with title](https://example.com "Tooltip text")

<!-- Reference-style link -->
[Link text][ref-label]

[ref-label]: https://example.com

Reference-style links keep long URLs out of the paragraph text, making the source easier to read — useful in technical documentation with many external citations.

Images

Image syntax is identical to links with an exclamation mark prepended. The text in brackets becomes the alt attribute, which is important for accessibility and SEO.

![Alt text](https://example.com/image.png)
![Alt text](./local-image.png "Optional title")

Inline code and code blocks

Surround a word or short snippet with single backticks for inline code. Use triple backticks (fences) for multi-line code blocks. Add a language identifier after the opening fence to enable syntax highlighting in tools that support it.

Use the `console.log()` function to debug.

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

Language identifiers are not part of the original Markdown spec but are universally supported by modern parsers and essential for syntax highlighting in READMEs, documentation, and code-review platforms. Common values include js, ts, python, bash, json, css, and sql.

Blockquotes

Prefix a line with > to create a blockquote. Multiple > characters nest quotes.

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

>> This is a nested blockquote.

Blockquotes are conventionally used for quotations, callout notes, warnings, and tips in documentation. Some platforms like GitHub support special callout syntax (> [!NOTE]) built on top of standard blockquote syntax.

Tables

Tables use pipe characters to separate columns and a separator row of dashes beneath the header. Colons in the separator control column alignment.

| Syntax   | Description | Notes        |
| :------- | :---------: | -----------: |
| Header   | Centered    | Right-align  |
| Cell     | Cell        | Cell         |

Tables are a GitHub Flavored Markdown extension, not part of the original spec, but they are supported by virtually every modern parser including the Markdown Editor. Pipes at the start and end of each row are optional but recommended for readability.

Horizontal rules

A horizontal rule (<hr>) is produced by three or more hyphens, asterisks, or underscores on a line by themselves. Blank lines around the rule are recommended to avoid accidental parsing as a heading separator.

---

***

___

Task lists

Task lists are a GitHub Flavored Markdown extension. Prefix a list item with [ ] for an unchecked checkbox or [x] for a checked one. They render as interactive checkboxes in GitHub issues and pull requests.

- [x] Write the introduction
- [x] Add syntax examples
- [ ] Proofread the document
- [ ] Publish

Markdown syntax cheat sheet

The table below summarises the most-used syntax elements with the output they produce.

CommonMark vs GitHub Flavored Markdown

The original Markdown spec by John Gruber was intentionally underspecified, leaving many edge cases up to individual parser authors. This led to a fragmented ecosystem where the same source file would render differently in different tools. Two standards emerged to address this.

CommonMark

CommonMark (commonmark.org) is a strict, unambiguous specification for Markdown published in 2014 by John MacFarlane and others. It defines exactly what every parser must do for every construct, including hundreds of edge cases that the original spec left undefined. A CommonMark-compliant parser produces identical output for the same input regardless of implementation. The Markdown Editor uses the marked library which follows CommonMark-compatible parsing rules, so the preview matches what you will see in most production environments.

GitHub Flavored Markdown (GFM)

GitHub Flavored Markdown is a superset of CommonMark published by GitHub in 2017. It adds the following extensions on top of the CommonMark base:

• Tables — the pipe-based table syntax described above.
• Task lists — checkboxes in list items with [ ] and [x].
• Strikethrough — wrapping text in ~~double tildes~~ produces struck-through text.
• Autolinks — bare URLs and email addresses are automatically turned into clickable links without requiring angle brackets.
• Disallowed raw HTML — a small set of HTML tags (like <script>) are filtered out for security.

Because GitHub is where most developers encounter Markdown in the wild, GFM has become the de-facto standard. When writing for a general audience, assume GFM and you will cover all bases.

Where Markdown is used

READMEs and open-source repositories

The most visible use of Markdown is the README.md file that appears on every GitHub and GitLab repository homepage. A well-written README is the front door to a project — it explains what the software does, how to install it, and how to contribute. Markdown makes it easy to include code examples, badges, tables of contents, and installation steps without any special tooling.

Documentation sites

Tools like Docusaurus, MkDocs, VitePress, Nextra, and Astro treat Markdown (or its extended variant MDX) as their primary content format. Authors write in .md or .mdx files, and the framework generates a full static website with navigation, search, and theming. This combination — Markdown for content, a framework for structure — is the standard approach for developer documentation.

Static-site generators and blogs

Jekyll pioneered the practice of writing blog posts in Markdown with YAML front-matter metadata. Hugo, Gatsby, Next.js, and Eleventy all followed suit. The author writes a .md file, the generator applies a template, and the result is a fast static HTML page. No database, no CMS login — just files in a Git repository.

Note-taking and knowledge management

Obsidian, Notion, Bear, Logseq, Typora, and Joplin all use Markdown as their native storage format (or a close variant). This means your notes are portable — they are plain text files you can open in any editor or migrate between apps at any time. For developers who want long-term ownership of their notes, a Markdown-based tool is the clear choice.

Chat and collaboration platforms

Slack, Discord, Mattermost, Teams, and many other chat tools support subsets of Markdown for message formatting. Backtick-wrapped text renders as code, asterisks toggle bold, and triple backticks create code blocks — the same muscle memory from writing READMEs works in daily communication.

Converting Markdown to HTML

Every Markdown editor, documentation tool, and static-site generator converts Markdown to HTML under the hood using a parser library. The most widely-used JavaScript parsers are:

• marked — fast, CommonMark-compatible, used by the Markdown Editor on this site. Processes everything locally in the browser with no server round-trip.
• markdown-it — highly configurable, supports CommonMark and numerous plugins including GFM extensions.
• remark — part of the unified.js ecosystem, parses Markdown into an AST for programmatic transformation before rendering. Used by MDX and many documentation frameworks.
• Showdown — one of the older JavaScript implementations, still in active use in many legacy projects.

On the server side, Python's python-markdown and markdown2, Ruby's kramdown and Redcarpet, Go's goldmark, and Rust's pulldown-cmark are all popular choices with excellent CommonMark compliance.

If you are embedding Markdown-generated HTML into a website that accepts user input, always sanitise the output with a library like DOMPurify before inserting it into the DOM. This prevents cross-site scripting (XSS) attacks that exploit raw HTML tags or attributes passed through the parser.

Tips for writing clean Markdown documents

Use one blank line between elements

Separate paragraphs, headings, lists, code blocks, and other block elements with a single blank line. Omitting blank lines can confuse parsers and produce unexpected output — for example, a list immediately after a heading without a blank line may parse as part of the heading on some older parsers.

Prefer ATX headings over Setext

The hash-prefix ATX style (## Heading) works for all six levels and is consistent. The underline-based Setext style only covers h1 and h2 and is visually noisy. Use ATX throughout for consistency.

Always add alt text to images

The alt text in ![alt text](url) is not optional. It is used by screen readers for accessibility, displayed when the image fails to load, and indexed by search engines. Write a concise description of what the image shows, not just "image" or the filename.

Add language identifiers to code blocks

A fenced code block without a language identifier misses syntax highlighting. Always add the language: ```javascript, ```python, ```bash. If the content is truly language-agnostic output, use ```text.

Keep line lengths reasonable

Hard-wrapping lines at 80 or 100 characters makes Markdown more readable in terminals and plain-text editors. However, some tools treat a single line break within a paragraph as a hard break (a <br>), so be aware of how your target parser handles this. CommonMark requires two spaces at the end of a line to force a line break inside a paragraph.

Use reference-style links for long URLs

When a paragraph contains multiple long URLs, inline links can make the source difficult to read. Move URLs to the bottom of the section as reference definitions. The paragraph stays clean and the URLs are still easy to find and update.

Preview before publishing

Even experienced Markdown authors make mistakes — a missed backtick, an extra asterisk, a miscounted indent. Always preview your document before publishing it. The Markdown Editor shows a live rendered preview as you type so you catch formatting errors instantly, without round-tripping to GitHub or a deployment pipeline.

Getting started with Markdown today

The best way to learn Markdown is to use it. Open the free online Markdown Editor on this site and start typing. The editor is seeded with a sample document that demonstrates the most common syntax, so you can immediately see how each element renders. The toolbar buttons for Bold, Italic, Headings, Links, Lists, Code, and Blockquotes let you insert formatted syntax at the cursor without memorising every character — and once you have used each one a handful of times, you will not need the toolbar at all.

When you are ready to save your work, click Copy Markdown to grab the raw source, Copy HTML to get the rendered markup, or Download .md to save a local file. Everything runs in your browser — nothing is ever uploaded to a server.

Markdown has remained popular for over two decades because it solves a real problem: formatted text that is readable by both humans and machines, lives happily in version control, and requires no special software to write or read. Once you build the habit, you will find yourself reaching for ** and ## everywhere.