Markdown Complete Guide - Syntax, Examples & Best Practices 2026

What Is Markdown?

Markdown is a lightweight markup language created by John Gruber in 2004, with significant contributions from Aaron Swartz. The core philosophy is elegant in its simplicity: text written in Markdown should be readable as-is, even before it's rendered. A plain text file with Markdown formatting looks like a naturally formatted document, not a wall of HTML tags.

Here's a comparison of the same content in HTML vs Markdown:

Hello World
This is a bold word and this is italic.

  
Item one
  
Item two

## Hello World
This is a bold word and this is *italic*.
Item one
Item two

The Markdown version is faster to write, easier to read in raw form, and just as expressive for most documentation needs.

Why Developers Love Markdown

Markdown has become the lingua franca of developer documentation for good reasons:

• GitHub READMEs: Every GitHub repository displays its README.md as the project homepage, rendered from Markdown
• Documentation sites: Tools like Jekyll, Hugo, Docusaurus, MkDocs, and Gatsby all use Markdown as their primary content format
• Note-taking: Apps like Obsidian, Notion, Bear, and Typora use Markdown, making notes portable across tools
• Blog platforms: Ghost, Hashnode, and Dev.to support Markdown for writing posts
• Chat tools: Slack, Discord, and Microsoft Teams support a subset of Markdown for text formatting
• Static site generators: Markdown content files compile to HTML, giving you a full website from plain text

Once you learn Markdown, you can write formatted content in any of these tools without switching mental models.

Basic Markdown Syntax

Headings

Headings are created with the # character. One # for H1 (the largest), up to six ###### for H6 (the smallest):

# Heading 1 — Page Title

Heading 2 — Major Section
Heading 3 — Subsection
#### Heading 4
##### Heading 5
###### Heading 6

Always put a space between the # and the heading text. Most parsers require it, and it's a best practice.

Bold and Italic

This text is bold

__This text is also bold__
*This text is italic*
_This text is also italic_
*This text is bold AND italic*
___This is also bold and italic___

The double asterisk () is the most universally supported syntax and is recommended over double underscores (__) for bold.

Lists

Unordered lists** use -, *, or + as bullet markers (pick one and be consistent):

- First item

Second item
  - Nested item (indent with 2 spaces)

  - Another nested item
Third item

Ordered lists use numbers followed by periods:

1. First step

Second step
Third step

Fun fact: the actual numbers in ordered lists don't matter to most parsers. You can write 1. 1. 1. and get a properly numbered 1, 2, 3 list. However, using correct numbers makes the raw text more readable.

Paragraphs and Line Breaks

Paragraphs are separated by a blank line. A single line break within a paragraph is treated as a space (the text flows together). To force a line break, end a line with two or more spaces, or use a backslash \ at the end of the line (GitHub Flavored Markdown).

Intermediate Markdown Syntax

Links

Link text

Link with title

[Link text][reference-id]
[reference-id]: https://example.com "Optional Title"

Images

Images use the same syntax as links but with an exclamation mark prefix:

!Alt text

!Alt text
![Logo][logo-ref]
[logo-ref]: https://example.com/logo.png "Company Logo"

Always write descriptive alt text for accessibility. Screen readers read the alt text to describe images to visually impaired users.

Blockquotes

> This is a blockquote.

>
> It can span multiple paragraphs.
> Nested blockquotes:
> > This is a nested quote.

Horizontal Rules

Three or more hyphens, asterisks, or underscores on their own line create a horizontal divider:

---

*

___

Inline Code and Code Blocks

Use single backticks for inline code: const x = 42;

For multi-line code blocks, use triple backticks. Specify the language after the opening backticks for syntax highlighting:

\\\javascript

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

}
\\\

The language identifier (javascript, python, bash, css, etc.) enables syntax highlighting in GitHub, VS Code, and most Markdown renderers.

Advanced Markdown Syntax

Tables

Tables are a GitHub Flavored Markdown (GFM) feature. Use pipes | and hyphens - to define columns:

Column 1
Column 2
Column 3

Cell A1
Cell A2
Cell A3
Cell B1
Cell B2
Cell B3


Left
Center
Right

Text
Text
Text

Task Lists (GitHub Flavored Markdown)

- [x] Write the README

[x] Add code examples
[ ] Deploy to production
[ ] Write tests

This renders as interactive checkboxes on GitHub and many Markdown editors, making task lists great for project tracking in README files.

Footnotes

Footnotes are supported in GFM and many extended Markdown implementations:

Here is a claim that needs citation.[^1]
[^1]: This is the footnote text that appears at the bottom of the document.

Definition Lists (MultiMarkdown)

Term

:   Definition of the term
Another Term
:   First definition
:   Second definition

Strikethrough (GFM)

~~This text is crossed out~~

Markdown Flavors: Which One Should You Use?

Not all Markdown is the same. Over the years, different tools have added extensions and changed behavior, creating several "flavors":

CommonMark

A standardized specification for Markdown, designed to resolve ambiguities in the original Gruber specification. CommonMark aims to be the definitive standard. If you want maximum portability, write CommonMark-compatible Markdown.

GitHub Flavored Markdown (GFM)

The most widely used flavor, extending CommonMark with: tables, task lists, strikethrough, autolinks, and code block syntax highlighting. If you're writing READMEs or GitHub documentation, you're writing GFM.

MultiMarkdown

Adds footnotes, tables, definition lists, cross-references, and metadata. Popular in academic and technical writing communities.

MDX

Markdown + JSX, used in modern JavaScript documentation (Docusaurus, Nextra, etc.). Lets you embed React components directly in Markdown files.

Markdown in Different Tools

Tool

Markdown Support

Notes

GitHub	GFM	Full support including task lists and tables
VS Code	CommonMark + extensions	Built-in preview with Ctrl+Shift+V
Obsidian	Extended Markdown	Backlinks, embeds, dataview queries
Notion	Subset of Markdown	Import/export supported
Jekyll	Kramdown	Static site generator for GitHub Pages
Hugo	Goldmark	Fast static site generator
Docusaurus	MDX	React-based documentation framework

Best Practices for Writing Good Markdown

1. Use ATX-style headings (# H1, ## H2) rather than Setext-style (underlines with = or -). ATX headings are more consistent and universally supported.

2. One blank line before and after headings, lists, and code blocks. This prevents rendering issues in some parsers.

3. Consistent list markers.** Pick either - or * for unordered lists and stick with it throughout a document.

4. Descriptive link text. Write read the documentation instead of click here. This is better for accessibility and SEO.

5. Use reference-style links for long URLs. They keep the paragraph text readable and allow you to reuse the same URL multiple times.

6. Always specify a language in fenced code blocks. ``javascript is better than ` — it enables syntax highlighting and is more explicit.

7. Keep lines under 80 characters. Especially important for documentation that will be reviewed in code review tools.

8. Add alt text to all images. It's required for accessibility and helps SEO.

Markdown README Template

Here's a complete template for a GitHub README.md:

# Project Name
Brief one-line description of what this project does.
Features
Feature one
Feature two
Feature three

Installation
\\\bash
npm install your-package
\\\
Usage
\\\javascript
const tool = require('your-package');
tool.doSomething();
\\\`
Contributing
Pull requests are welcome. For major changes, please open an issue first.
License
MIT

Converting Markdown to HTML and PDF

Markdown's primary output is HTML, but it can also be converted to:

• PDF: Using Pandoc, markdown-pdf, or VS Code's Markdown PDF extension
• Word .docx: Pandoc supports Markdown → DOCX conversion
• Slides: Reveal.js, Marp, and Slidev can turn Markdown into presentations
• ePub: Pandoc can generate ePub ebooks from Markdown

The tool Pandoc is the universal document converter and supports Markdown as a first-class input format.

Markdown vs Rich Text Editors

Aspect

Markdown

Rich Text (WYSIWYG)

Learning curve	Moderate (learn syntax)	Low (familiar UI)
Portability	Excellent (plain .txt)	Poor (vendor lock-in)
Version control	Perfect (meaningful diffs)	Difficult (binary/XML)
Formatting consistency	High (structure from syntax)	Variable
Speed for power users	Faster (keyboard-only)	Slower

Markdown wins decisively for technical documentation, developer tools, and any content that needs to live in version control. Rich text editors are better for non-technical users creating one-off documents.

Write and Preview Markdown Online

Try our free Markdown Editor to write, preview, and export Markdown online. It supports GitHub Flavored Markdown, live side-by-side preview, syntax highlighting, and one-click HTML export — all running in your browser with no sign-up required.