Markdown Complete Guide: Syntax, Tips & Best Practices

March 31, 2026 · 12 min read

What Is Markdown?

Markdown is a lightweight markup language created by John Gruber in collaboration with Aaron Swartz in 2004. It lets you write formatted text using plain text syntax that remains readable even without rendering. Instead of clicking buttons in a word processor or writing verbose HTML tags, you use simple, intuitive characters like # for headings, ** for bold text, and - for lists.

The philosophy behind Markdown is elegantly simple: the source text should be as readable as the rendered output. When you open a Markdown file in any text editor, you can immediately understand its structure and content without needing special software or rendering engines.

Markdown has become the de facto standard for technical writing, documentation, README files, blog posts, and note-taking across the software development world. Major platforms like GitHub, GitLab, Reddit, Stack Overflow, Discord, Slack, Notion, and Obsidian all support Markdown natively, making it an essential skill for developers, technical writers, and content creators.

Why Use Markdown?

• Speed and Efficiency: Writing **bold** is significantly faster than typing <strong>bold</strong> or reaching for a formatting toolbar
• Universal Portability: Plain text files work everywhere, on every operating system, and in every text editor without compatibility issues
• Version Control Friendly: Git diffs are clean and meaningful with Markdown, making collaboration and change tracking straightforward
• Distraction-Free Writing: No formatting toolbar distractions or complex interfaces—just you and your content
• Easy Conversion: Markdown easily converts to HTML, PDF, DOCX, LaTeX, and dozens of other formats using tools like Pandoc
• Future-Proof: Plain text files will remain readable decades from now, unlike proprietary formats that may become obsolete
• Accessibility: Properly structured Markdown translates to semantic HTML, improving accessibility for screen readers

Headings and Document Structure

Headings are the backbone of document structure in Markdown. They use the # symbol, where the number of hash marks determines the heading level from 1 to 6:

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

Always include a space after the # symbol—most Markdown processors require it, and it improves readability. The rendered output creates proper HTML heading tags (<h1> through <h6>), which are crucial for document structure, accessibility, and SEO.

Heading Best Practices

Use heading levels sequentially without skipping levels. Don't jump from H1 to H3—this breaks the document hierarchy and creates accessibility issues for screen reader users. Think of headings as an outline: each level should logically nest within the previous one.

Most documents should have only one H1 heading (the title), with H2 headings for major sections and H3-H6 for subsections. This creates a clear information hierarchy that both humans and search engines can understand.

Alternative Heading Syntax

Markdown also supports an alternative syntax for H1 and H2 headings using underlines:

Heading 1
=========

Heading 2
---------

While this syntax is valid, the hash mark syntax is more common and supports all six heading levels, making it the preferred choice for most writers.

Text Formatting Essentials

Markdown provides simple, intuitive syntax for common text formatting needs. These formatting options work inline within paragraphs and can be combined for more complex styling.

Emphasis Syntax Details

Both asterisks (*) and underscores (_) work for emphasis, but asterisks are more commonly used and recommended. The key difference: asterisks work mid-word (un*frigging*believable), while underscores require word boundaries.

For bold text, use double asterisks or underscores. For italic text, use single asterisks or underscores. Combine three for bold italic text. This consistency makes your Markdown source more readable and predictable.

Escaping Special Characters

If you need to display literal asterisks, underscores, or other Markdown syntax characters, escape them with a backslash:

This is \*not italic\* and \*\*not bold\*\*
Use \# to show a hash mark without creating a heading

Common characters that need escaping include: \ ` * _ { } [ ] ( ) # + - . !

Lists: Ordered, Unordered, and Nested

Lists are fundamental to organizing information in Markdown. They're simple to create and support nesting for hierarchical content.

Unordered Lists

Create unordered (bulleted) lists using -, *, or + followed by a space. All three markers work identically, but consistency within a document improves readability:

- First item
- Second item
- Third item
  - Nested item (indent with 2 spaces)
  - Another nested item
- Fourth item

The standard indentation for nested lists is two spaces, though some parsers accept four. Stick with two spaces for maximum compatibility.

Ordered Lists

Ordered (numbered) lists use numbers followed by periods and a space:

1. First step
2. Second step
3. Third step
   1. Sub-step A
   2. Sub-step B
4. Fourth step

Here's a useful feature: the actual numbers you use don't matter. Markdown automatically renumbers lists sequentially when rendered. You can use 1. for every item, making it easier to reorder items without renumbering:

1. First item
1. Second item
1. Third item

This renders as a properly numbered 1, 2, 3 list. This technique is particularly helpful when maintaining long lists or frequently reordering items.

Task Lists

Many Markdown flavors (including GitHub Flavored Markdown) support task lists with checkboxes:

- [x] Completed task
- [ ] Incomplete task
- [ ] Another incomplete task

Task lists are invaluable for project management, issue tracking, and to-do lists in documentation.

Definition Lists

Some extended Markdown syntaxes support definition lists for glossaries and term definitions:

Term 1
: Definition for term 1

Term 2
: First definition for term 2
: Second definition for term 2

While not universally supported, definition lists are useful for technical documentation and glossaries.

Links and Images

Markdown makes it easy to add hyperlinks and images while keeping the source text readable.

Inline Links

The most common link syntax uses square brackets for the link text and parentheses for the URL:

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

The optional title text appears as a tooltip when users hover over the link. This is useful for providing additional context without cluttering the visible link text.

Reference-Style Links

For documents with many links or repeated URLs, reference-style links improve readability:

This is [a link][1] and here's [another link][2].

[1]: https://example.com
[2]: https://example.com/page "Optional title"

You can also use descriptive references instead of numbers:

Check out [Google][google] and [GitHub][gh].

[google]: https://google.com
[gh]: https://github.com

Reference definitions can appear anywhere in the document and won't be rendered in the output. Many writers place them at the end of sections or at the document's end.

Automatic Links

Wrap URLs or email addresses in angle brackets to create automatic links:

<https://example.com>
<[email protected]>

Most modern Markdown parsers also automatically convert bare URLs into clickable links, though this behavior isn't guaranteed across all platforms.

Images

Image syntax is nearly identical to link syntax, with an exclamation mark prefix:

![Alt text](image.jpg)
![Alt text](image.jpg "Image title")

The alt text is crucial for accessibility—it describes the image for screen reader users and displays when the image fails to load. Always provide meaningful alt text that conveys the image's content and purpose.

Reference-style syntax works for images too:

![Logo][logo]

[logo]: /images/logo.png "Company logo"

Linking Images

To make an image clickable, wrap the image syntax in link syntax:

[![Alt text](thumbnail.jpg)](full-size.jpg)

This technique is commonly used for image galleries or linking thumbnails to full-resolution versions.

Code Blocks and Syntax Highlighting

Markdown excels at displaying code, making it the preferred format for technical documentation and programming tutorials.

Inline Code

For short code snippets within text, use single backticks:

Use the `print()` function to display output.
The `config.json` file contains settings.

If your code contains backticks, use double backticks to wrap it:

``Use `backticks` in code``

Fenced Code Blocks

For multi-line code blocks, use triple backticks (```) or triple tildes (~~~) before and after the code:

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

This creates a properly formatted code block with monospace font and preserved whitespace.

Syntax Highlighting

Specify the programming language immediately after the opening backticks to enable syntax highlighting:

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

```python
def greet(name):
    return f"Hello, {name}!"
```

```bash
#!/bin/bash
echo "Hello, World!"
```

Most Markdown processors support dozens of languages. Common identifiers include: javascript, python, java, cpp, csharp, ruby, go, rust, php, sql, html, css, json, yaml, bash, and shell.

Indented Code Blocks

The original Markdown specification uses indentation (4 spaces or 1 tab) to create code blocks:

    function example() {
        return true;
    }

While this works, fenced code blocks are preferred because they support syntax highlighting and are more explicit about where the code block begins and ends.

Line Numbers and Highlighting

Some Markdown processors support additional features like line numbers and line highlighting. GitHub, for example, allows you to highlight specific lines:

```javascript{1,3-5}
function example() {
  const x = 1;
  const y = 2;
  const z = 3;
  return x + y + z;
}
```

Check your platform's documentation for specific syntax and supported features.

Tables and Data Presentation

Tables aren't part of the original Markdown specification, but they're widely supported through extended syntax and are essential for presenting structured data.

Basic Table Syntax

Create tables using pipes (|) and hyphens (-):

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

The outer pipes are optional, and you don't need to align the pipes perfectly—Markdown processors handle alignment automatically. However, aligned tables are more readable in source form:

Header 1  | Header 2  | Header 3
----------|-----------|----------
Cell 1    | Cell 2    | Cell 3
Cell 4    | Cell 5    | Cell 6

Column Alignment

Control column alignment using colons in the separator row:

| Left-aligned | Center-aligned | Right-aligned |
|:-------------|:--------------:|--------------:|
| Left         | Center         | Right         |
| Text         | Text           | Text          |

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

Table Formatting Tips

Tables support inline Markdown formatting within cells:

| Feature      | Status | Notes                    |
|--------------|--------|--------------------------|
| **Bold**     | ✓      | Use `**text**`           |
| *Italic*     | ✓      | Use `*text*`             |
| `Code`       | ✓      | Use backticks            |
| [Links](#)   | ✓      | Standard link syntax     |
| Line breaks  | ✗      | Not supported in cells   |

You cannot use block-level elements (headings, lists, code blocks) within table cells. For complex content, consider restructuring your document or using HTML tables directly.

Table Limitations and Alternatives

Markdown tables work well for simple data but have limitations:

• No cell merging or spanning
• No nested tables
• Limited formatting options
• Can become unwieldy with many columns

For complex tables, consider using HTML directly or converting your Markdown to a format that supports advanced table features.

Blockquotes and Horizontal Rules

Blockquotes

Blockquotes use the > character at the beginning of lines, similar to email reply formatting:

> This is a blockquote.
> It can span multiple lines.
>
> And include multiple paragraphs.

You can nest blockquotes by adding additional > characters:

> First level quote
>
>> Nested quote
>>
>>> Deeply nested quote

Blockquotes can contain other Markdown elements:

> ## Heading in blockquote
>
> This blockquote contains:
> - A list
> - **Bold text**
> - `Code`
>
> And a [link](https://example.com).

Use blockquotes for quotations, callouts, warnings, or to visually distinguish supplementary information from main content.

Horizontal Rules

Create horizontal rules (dividers) using three or more hyphens, asterisks, or underscores on a line by themselves:

---

***

___

All three produce identical results. You can include spaces between the characters:

- - -

* * *

_ _ _

Horizontal rules are useful for separating major sections or indicating thematic breaks in your content.

Extended Syntax Features

Beyond the core Markdown specification, many processors support extended syntax for additional functionality. These features aren't universally supported, so check your platform's documentation.

Footnotes

Footnotes allow you to add references without cluttering the main text:

Here's a sentence with a footnote.[^1]

[^1]: This is the footnote content.

Footnotes automatically number sequentially and typically render at the document's end with backlinks to the reference points.

Automatic URL Linking

Many processors automatically convert URLs to clickable links without requiring explicit link syntax:

Visit https://example.com for more information.

This feature is convenient but not guaranteed across all platforms. For maximum compatibility, use explicit link syntax.

Emoji

GitHub Flavored Markdown and other platforms support emoji shortcodes:

:smile: :heart: :thumbsup: :rocket:

These render as actual emoji characters: 😊 ❤️ 👍 🚀

You can also use Unicode emoji directly in your Markdown source, though shortcodes are more readable and portable.

Math Equations

Some platforms support LaTeX-style math equations using dollar signs:

Inline math: $E = mc^2$

Block math:
$$
\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$

This feature is common in academic and scientific writing platforms but not universally supported.

Diagrams and Charts

Platforms like GitHub support Mermaid diagrams directly in Markdown:

```mermaid
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
```

This renders as an interactive diagram, perfect for flowcharts, sequence diagrams, and system architecture documentation.

Collapsible Sections

HTML <details> and <summary> tags work in many Markdown processors:

<details>
<summary>Click to expand</summary>

Hidden content goes here.
It can include **Markdown** formatting.

</details>

This creates expandable/collapsible sections, useful for FAQs, optional details, or lengthy content that shouldn't clutter the main view.

Markdown Flavors and Variants

While the original Markdown specification provides a foundation, numerous "flavors" have emerged with additional features and modifications. Understanding these variants helps you choose the right syntax for your platform.

CommonMark

CommonMark is a strongly specified, highly compatible specification of Markdown. It aims to resolve ambiguities in the original specification and provide a standard that implementations can target. CommonMark is the foundation for many modern Markdown processors.

GitHub Flavored Markdown (GFM)

GitHub Flavored Markdown extends CommonMark with features specifically useful for GitHub:

• Tables
• Task lists
• Strikethrough text
• Automatic URL linking
• Emoji shortcodes
• Syntax highlighting in code blocks
• @mentions and issue references

GFM is one of the most widely used Markdown flavors and has influenced many other implementations.

Markdown Extra

Markdown Extra adds features like:

• Tables
• Definition lists
• Footnotes
• Abbreviations
• Fenced code blocks
• Special attributes for headers and links

Originally created for PHP Markdown, these features have been adopted by many other processors.

MultiMarkdown

MultiMarkdown extends Markdown with features for academic and technical writing:

• Footnotes
• Tables
• Citations and bibliography
• Math support
• Metadata (title, author, date)
• Cross-references

Pandoc Markdown

Pandoc's Markdown variant is extremely feature-rich, supporting:

• All CommonMark features
• Extensive table options
• Math equations
• Citations
• Footnotes
• Definition lists
• Metadata blocks
• Custom attributes

Pandoc is a universal document converter, making its Markdown flavor particularly powerful for converting between formats.

Best Practices and