Markdown Guide: Syntax, Examples, and Cheat Sheet (2026)

Headings

Headings are created by placing one to six hash symbols (#) at the beginning of a line, followed by a space. The number of hash symbols determines the heading level:

Always leave a blank line before and after headings for best compatibility across Markdown processors. Heading levels should be sequential; do not skip from H2 to H4 without an H3 in between.

Text Formatting

Markdown provides simple syntax for common text formatting:

You can also use underscores (_) for bold (__text__) and italic (_text_), but asterisks are more commonly used and have fewer edge cases with words containing underscores.

Links and Images

Inline Links

The syntax for links is [link text](URL). For example, [Google](https://google.com) renders as a clickable link with "Google" as the visible text. You can add a title attribute with [link text](URL "title text").

Reference Links

For documents with many links, reference-style links keep the text readable. Define the URL elsewhere in the document using [label]: URL, then reference it with [link text][label]. This separates content from URLs, making long documents easier to maintain.

Images

Image syntax is identical to links but with an exclamation mark prefix: . The alt text is important for accessibility and SEO. For images that need specific sizing, you may need to use raw HTML within your Markdown.

Lists

Unordered Lists

Create unordered (bullet) lists using a dash (-), asterisk (*), or plus sign (+) followed by a space. Nest items by indenting with 2 or 4 spaces:

• First item
• Second item
  • Nested item
  • Another nested item
• Third item

Ordered Lists

Create ordered (numbered) lists using a number followed by a period and a space. Interestingly, the actual numbers you use do not matter; Markdown will render them sequentially. However, it is best practice to number them correctly for readability in the source text.

Task Lists (GitHub Flavored Markdown)

Task lists add checkboxes to list items. Use - [ ] for unchecked and - [x] for checked items. This is a GitHub Flavored Markdown extension and is not available in all Markdown processors. Task lists are commonly used in GitHub issues and pull requests for tracking progress.

Code Blocks

According to developer surveys, 89 percent of technical documentation includes code blocks with syntax highlighting, making this one of Markdown's most important features.

Inline Code

Wrap inline code with single backticks: `variable_name` renders as variable_name. Use this for short code references within a sentence.

Fenced Code Blocks

For multi-line code, use triple backticks (```) before and after the code. Add a language identifier after the opening backticks for syntax highlighting:

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

Most Markdown renderers support syntax highlighting for hundreds of languages including JavaScript, Python, TypeScript, Go, Rust, SQL, and many more.

Tables

Tables use pipes (|) to separate columns and dashes (-) to create the header row separator. Alignment is controlled with colons:

• Left-aligned (default): :--- or ---
• Center-aligned: :---:
• Right-aligned: ---:

Tables are a GitHub Flavored Markdown extension. In standard Markdown (CommonMark), tables are not natively supported. Most modern Markdown processors and platforms support GFM tables.

Blockquotes

Blockquotes use the greater-than symbol (>) at the beginning of each line. They are commonly used for quoting external sources, highlighting important notes, or providing callouts:

> This is a blockquote. It can span multiple lines by starting each line with >.

Nested blockquotes use multiple greater-than symbols (>>). Many documentation platforms extend blockquotes with admonition syntax for notes, warnings, and tips.

Horizontal Rules

Create a horizontal line (thematic break) with three or more dashes (---), asterisks (***), or underscores (___) on their own line. These are useful for separating major sections within a document.

Advanced Markdown Features

Footnotes

Some Markdown processors support footnotes using [^1] in the text and [^1]: Footnote text at the bottom. This is common in academic and long-form writing but is not part of CommonMark or GFM.

Definition Lists

Definition lists use the format Term\n: Definition. Supported by PHP Markdown Extra and some other processors but not by CommonMark or GFM.

Math Notation

Many platforms support LaTeX math notation within Markdown using dollar signs: $E = mc^2$ for inline math and $$....$$ for block math. GitHub, GitLab, Obsidian, and Jupyter Notebooks all support this.

CommonMark vs. GitHub Flavored Markdown

CommonMark is the standardized specification of Markdown that resolves ambiguities in Gruber's original description. GitHub Flavored Markdown (GFM) is a superset of CommonMark that adds tables, task lists, strikethrough, autolinks, and disallowed raw HTML tags. Most platforms implement GFM or a close variant. When writing Markdown, targeting GFM syntax ensures maximum compatibility across platforms.

The Bottom Line

Markdown is the most widely used documentation format in the world, voted most admired by developers for three consecutive years. Its simple syntax (headings with #, bold with **, links with [text](url)) makes it fast to write and easy to read as plain text. Whether you are writing README files, documentation, blog posts, or notes, Markdown's portability and simplicity make it the ideal choice. Over 2,199 companies use it across every industry.

Convert your Markdown to HTML instantly with our free Markdown to HTML converter.

Frequently Asked Questions