Markdown Reference Guide

Markdown is a lightweight markup language that allows you to format text using plain text syntax. Created by John Gruber in 2004, it was designed to be easy-to-read and easy-to-write, while converting to structurally valid HTML.

This comprehensive guide covers both basic and extended Markdown syntax, best practices, and real-world usage examples.

Basic Syntax

All Markdown applications support these fundamental elements from John Gruber's original design document.

Headings

Create headings using hash symbols (#). The number of hashes corresponds to the heading level (1-6).

Hash Style:

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

Alternate Underline Style (H1 and H2 only):

Heading level 1
===============

Heading level 2
---------------

Best Practices:

Always put a space between the hash symbols and heading text
Put blank lines before and after headings for compatibility
Use only one H1 per document for SEO

✅ Do this:

Try to put a blank line before...

# Heading

...and after a heading.

❌ Don't do this:

Without blank lines, this might not look right.
#Heading
Don't do this!

Paragraphs and Line Breaks

Paragraphs: Separate paragraphs with one or more blank lines.

This is the first paragraph.

This is the second paragraph.

Line Breaks: End a line with two or more spaces, then press return.

This is the first line.  
And this is the second line.

Alternatively, use the HTML <br> tag:

This is the first line.<br>
And this is the second line.

Best Practices:

Don't indent paragraphs with spaces or tabs
Use trailing whitespace or <br> tags for line breaks
Be consistent with your line break method

Emphasis

Add emphasis by making text bold, italic, or both.

Bold Text:

I just love **bold text**.
I just love __bold text__.
Love**is**bold

Italic Text:

Italicized text is the *cat's meow*.
Italicized text is the _cat's meow_.
A*cat*meow

Bold and Italic:

This text is ***really important***.
This text is ___really important___.
This text is __*really important*__.
This text is **_really important_**.
This is really***very***important text.

Best Practices:

Use asterisks for emphasis in the middle of words for compatibility
Be consistent with your emphasis style throughout the document

✅ Do this:

Love**is**bold
A*cat*meow
This is really***very***important text.

❌ Don't do this:

Love__is__bold
A_cat_meow
This is really___very___important text.

Blockquotes

Create blockquotes using the > character.

Simple Blockquote:

> Dorothy followed her through many of the beautiful rooms in her castle.

Multiple Paragraphs:

> Dorothy followed her through many of the beautiful rooms in her castle.
>
> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.

Nested Blockquotes:

> Dorothy followed her through many of the beautiful rooms in her castle.
>
>> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.

Blockquotes with Other Elements:

> #### The quarterly results look great!
>
> - Revenue was off the chart.
> - Profits were higher than ever.
>
> *Everything* is going according to **plan**.

Best Practices:

Put blank lines before and after blockquotes
You can be "lazy" and only put > before the first line of each paragraph

Lists

Organize items into ordered (numbered) and unordered (bulleted) lists.

Unordered Lists:

- First item
- Second item
- Third item
- Fourth item

You can also use * or +:

* First item
* Second item

+ First item
+ Second item

Ordered Lists:

1. First item
2. Second item
3. Third item
4. Fourth item

The numbers don't have to be in order, but should start with 1:

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

Nested Lists:

1. First item
2. Second item
3. Third item
    - Indented item
    - Indented item
4. Fourth item

Adding Elements in Lists:

Paragraphs:

* This is the first list item.
* Here's the second list item.

    I need to add another paragraph below the second list item.

* And here's the third list item.

Blockquotes:

* This is the first list item.
* Here's the second list item.

    > A blockquote would look great below the second list item.

* And here's the third list item.

Code Blocks:

1. Open the file.
2. Find the following code block on line 21:

        <html>
          <head>
            <title>Test</title>
          </head>

3. Update the title to match the name of your website.

Images:

1. Open the file containing the Linux mascot.
2. Marvel at its beauty.

    ![Tux, the Linux mascot](/assets/images/tux.png)

3. Close the file.

Best Practices:

Use consistent list markers throughout the same list
Indent nested elements by 4 spaces or 1 tab
Put blank lines between list items if any item contains multiple paragraphs

Links

Create links using several different syntaxes.

Inline Links:

My favorite search engine is [Duck Duck Go](https://duckduckgo.com).

[This link](https://example.com) has no title attribute.

My favorite search engine is [Duck Duck Go](https://duckduckgo.com "The best search engine for privacy").

Reference-Style Links:

This is [an example][1] reference-style link.

You can also use [an example] [1] with a space.

[1]: http://example.com/ "Optional Title Here"

Implicit Link Name Shortcut:

Visit [Daring Fireball][] for more information.

[Daring Fireball]: http://daringfireball.net/

URLs and Email Addresses:

<https://www.markdownguide.org>
<[email protected]>

Formatting Links:

I love supporting the **[EFF](https://eff.org)**.
This is the *[Markdown Guide](https://www.markdownguide.org)*.
See the section on [`code`](#code).

Best Practices:

Try to URL encode spaces with %20
URL encode parentheses: ( as %28 and ) as %29
Use reference-style links for cleaner, more readable source text

Images

Add images using syntax similar to links, but with an exclamation mark.

Inline Images:

![The San Juan Mountains are beautiful!](/assets/images/san-juan-mountains.jpg "San Juan Mountains")

![Alt text](/path/to/img.jpg)

Reference-Style Images:

![Alt text][id]

[id]: url/to/image "Optional title attribute"

Linking Images:

[![An old rock in the desert](/assets/images/shiprock.jpg "Shiprock, New Mexico")](https://www.flickr.com/photos/example)

Best Practices:

Always include meaningful alt text for accessibility
Use descriptive filenames for images
Consider image file sizes for web performance

Code

Denote code using backticks for inline code or indentation for code blocks.

Inline Code:

At the command prompt, type `nano`.

Use the `printf()` function.

Escaping Backticks:

``Use `code` in your Markdown file.``

Code Blocks (Indented):

    <html>
      <head>
        <title>Test</title>
      </head>
    </html>

Best Practices:

Use inline code for function names, filenames, and short code snippets
Use code blocks for multi-line code examples
Consider fenced code blocks (covered in Extended Syntax) for better syntax highlighting

Horizontal Rules

Create horizontal rules using three or more asterisks, dashes, or underscores.

***

---

_________________

Best Practices:

Put blank lines before and after horizontal rules
Be consistent with your chosen horizontal rule style

Escaping Characters

Use backslashes to display literal characters that would otherwise format text.

\* Without the backslash, this would be a bullet in an unordered list.

Characters You Can Escape:

Character	Name
\	backslash
`	backtick
*	asterisk
_	underscore
{}	curly braces
[]	brackets
<>	angle brackets
()	parentheses
#	hash mark
+	plus sign
-	minus sign
.	dot
!	exclamation mark
\|	pipe

Extended Syntax

These elements extend the basic syntax by adding additional features. Not all Markdown applications support these elements.

Tables

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

Basic Table:

| Syntax      | Description |
| ----------- | ----------- |
| Header      | Title       |
| Paragraph   | Text        |

Alignment:

| Syntax      | Description | Test Text     |
| :---        |    :----:   |          ---: |
| Header      | Title       | Here's this   |
| Paragraph   | Text        | And more      |

Formatting Text in Tables:

| Command | Description |
| --- | --- |
| `git status` | List all *new or modified* files |
| `git diff` | Show file differences that **haven't been** staged |

Escaping Pipe Characters:

| Name     | Character |
| ---      | ---       |
| Backtick | `         |
| Pipe     | &#124;    |

Best Practices:

You don't need to make the raw Markdown line up
Add pipes on either end of rows for best compatibility
Use table generators for complex tables

Fenced Code Blocks

Create code blocks without indentation using three backticks or tildes.

Basic Fenced Code Block:

```
{
  "firstName": "John",
  "lastName": "Smith",
  "age": 25
}
```

Syntax Highlighting:

```json
{
  "firstName": "John",
  "lastName": "Smith",
  "age": 25
}
```

```javascript
function greet(name) {
  console.log("Hello, " + name + "!");
}
```

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

Using Tildes:

~~~
No language indicated, so no syntax highlighting.
~~~

Best Practices:

Specify the language for syntax highlighting when possible
Use fenced code blocks instead of indented ones when you can
Common language codes: javascript, python, html, css, bash, json, xml, sql

Footnotes

Add footnotes to provide additional information without cluttering the main text.

Basic Footnotes:

Here's a simple footnote,[^1] and here's a longer one.[^bignote]

[^1]: This is the first footnote.

[^bignote]: Here's one with multiple paragraphs and code.

    Indent paragraphs to include them in the footnote.

    `{ my code }`

    Add as many paragraphs as you like.

Best Practices:

Footnotes can be placed anywhere in the document
Identifiers can be numbers or words, but no spaces
Keep footnote content concise and relevant

Heading IDs

Add custom IDs to headings for direct linking and CSS styling.

### My Great Heading {#custom-id}

Linking to Heading IDs:

[Link to custom heading](#custom-id)

Best Practices:

Use descriptive, URL-friendly IDs
Check if your Markdown processor supports this feature
Consider automatic ID generation for consistency

Definition Lists

Create glossaries and term definitions.

First Term
: This is the definition of the first term.

Second Term
: This is one definition of the second term.
: This is another definition of the second term.

Multiple Terms:

Term 1
Term 2
: Definition a

Term 3
: Definition b

Complex Definitions:

Apple

: Pomaceous fruit of plants of the genus Malus in 
  the family Rosaceae.

: An American computer company.

Orange

: The fruit of an evergreen tree of the genus Citrus.

Strikethrough

Strike through text to show deletions or corrections.

~~The world is flat.~~ We now know that the world is round.

Best Practices:

Use strikethrough to show corrections, not just for emphasis
Don't overuse as it can hurt readability

Task Lists

Create interactive checklists and todo lists.

- [x] Write the press release
- [ ] Update the website
- [ ] Contact the media
- [x] Research competitors
  - [x] Company A
  - [ ] Company B
  - [ ] Company C
- [ ] Finalize launch date

Best Practices:

Use task lists for actionable items
Nest subtasks for complex projects
Many applications allow clicking checkboxes to toggle completion

Emoji

Add emoji using Unicode characters or shortcodes.

Copy and Paste:

Gone camping! ⛺ Be back soon.

That is so funny! 😂

Shortcodes (application-dependent):

Gone camping! :tent: Be back soon.

That is so funny! :joy:

Common Shortcodes:

:smile: 😄
:heart: ❤️
:thumbsup: 👍
:warning: ⚠️
:information_source: ℹ️

Highlight

Highlight important text (not widely supported).

I need to highlight these ==very important words==.

Alternative with HTML:

I need to highlight these <mark>very important words</mark>.

Subscript and Superscript

Subscript:

H~2~O

Superscript:

X^2^

HTML Alternatives:

H<sub>2</sub>O

X<sup>2</sup>

Best Practices:

Test compatibility with your Markdown processor
Use HTML tags for better compatibility
Common uses: chemical formulas, mathematical expressions, footnote references

HTML Integration

Markdown allows HTML tags for features not covered by Markdown syntax.

Inline HTML:

This **word** is bold. This <em>word</em> is italic.

Block-Level HTML:

<div style="color: blue;">
  This is a blue div.
</div>

Markdown in HTML (Extended):

<div markdown="1">
This is *true* markdown text.
</div>

Common HTML Tags in Markdown:

<br> for line breaks
<hr> for horizontal rules
<img> for images with custom attributes
<a> for links with custom attributes
<table> for complex tables
<kbd> for keyboard keys: <kbd>Ctrl</kbd>+<kbd>C</kbd>

Best Practices:

Use HTML sparingly; prefer Markdown when possible
Separate block-level HTML elements with blank lines
Test HTML compatibility with your Markdown processor

Best Practices

General Guidelines

Consistency: Choose one style for each element and stick to it throughout your document
Readability: Write Markdown that's easy to read as plain text
Compatibility: Test your Markdown with your target applications
Performance: Optimize images and minimize HTML usage

Document Structure

# Document Title

Brief introduction paragraph.

## Table of Contents

- [Section 1](#section-1)
- [Section 2](#section-2)

## Section 1

Content here...

### Subsection 1.1

More detailed content...

## Section 2

More content...

## Conclusion

Wrap up your document.

---

*Last updated: [Date]*

Writing Tips

Use descriptive link text: Instead of "click here", use "download the user manual"
Write meaningful alt text: Describe what's in the image, not that it's an image
Keep paragraphs short: Easier to read on screens
Use lists for scannable content: Break up dense text
Include a table of contents: For longer documents

Common Pitfalls

Missing spaces: #Heading vs # Heading
Inconsistent list markers: Mixing -, *, and + in the same list
Incorrect escaping: Not escaping special characters when needed
Poor link text: Using "click here" or bare URLs
Missing alt text: Images without descriptive alternatives

Testing Your Markdown

Preview in your target application
Test on different devices and screen sizes
Validate HTML output for proper structure
Check accessibility with screen readers
Verify links are working

Markdown Flavors

Different applications support different "flavors" of Markdown:

CommonMark: Standardized version
GitHub Flavored Markdown (GFM): Adds tables, task lists, strikethrough
Markdown Extra: Adds tables, footnotes, definition lists
MultiMarkdown: Adds tables, footnotes, citations
R Markdown: For data science and statistical analysis

Always check which flavor your application uses and what features are supported.

This comprehensive guide covers the essential Markdown syntax you'll need for most writing tasks. Markdown's simplicity and readability make it perfect for documentation, README files, blog posts, and technical writing. Start with the basic syntax and gradually incorporate extended features as needed.

For the most up-to-date information and application-specific features, consult your Markdown processor's documentation.

Basic Syntax

Headings

Paragraphs and Line Breaks

Emphasis

Blockquotes

Lists

Links

Images

Code

Horizontal Rules

Escaping Characters

Extended Syntax

Tables

Fenced Code Blocks

Footnotes

Heading IDs

Definition Lists

Strikethrough

Task Lists

Emoji

Highlight

Subscript and Superscript

HTML Integration

Best Practices

General Guidelines

Document Structure

Writing Tips

Common Pitfalls

Testing Your Markdown

Markdown Flavors

On this page

Basic Syntax

Extended Syntax

HTML Integration

Best Practices

Markdown Flavors