Markdown Best Practices

Writing good Markdown is about more than just knowing the syntax. Following these best practices will ensure your documents are readable, portable, and easy to maintain.

1. Always use a space after # for headings

While some parsers allow #Heading, the standard and most compatible way is to include a space: # Heading.

❌ Avoid this:

#Heading Level 1

✅ Do this:

# Heading Level 1

2. Leave blank lines around blocks

Always place a blank line before and after block elements like headings, lists, code blocks, and horizontal rules. This helps the parser correctly identify the start and end of each section.

❌ Avoid this:

### My Heading
First paragraph here.
* Item 1
* Item 2

✅ Do this:

### My Heading

First paragraph here.

* Item 1
* Item 2

3. Be consistent with styles

If you prefer using asterisks (*) for unordered lists and emphasis, stick with them throughout the document. Avoid mixing them with dashes (-) or underscores (_) unnecessarily.

❌ Avoid this:

* Item one
- Item two
+ Item three

✅ Do this:

* Item one
* Item two
* Item three

4. Use Reference-Style Links for long documents

If your document has many links, using reference-style links (e.g. [Text][ref]) keeps the main text clean and easier to edit, as all the long URLs are moved to the bottom of the file.

✅ Best for long documents:

Please check our [Terms of Service][1] and [Privacy Policy][2].

[1]: https://example.com/tos
[2]: https://example.com/privacy

5. Don't Nest Elements Too Deeply

While you can nest lists and blockquotes, doing so more than two or three levels deep can make the document harder to read for both humans and some parsers. Keep it simple.

❌ Highly discouraged:

* Item 1
  * Item 1.1
    * Item 1.1.1
      * Item 1.1.1.1 (Wait, where am I?)

6. Use Meaningful Alt Text

Always provide descriptive alt text for images. This improves accessibility and helps with SEO if the document is being published on the web.

❌ Avoid this:

![image](/pix/beach.jpg)

✅ Do this:

![Sunset over Waikiki Beach](/pix/beach.jpg)

7. Avoid Indenting Paragraphs

In Markdown, indenting a paragraph by four spaces or a tab will turn it into a code block. Unless you intend to create a code block, avoid indenting the first line of your paragraphs.

❌ Leads to accidental code blocks:

    This paragraph has a tab at the start.
    It will be rendered inside a gray box.

By following these simple rules, you'll create Markdown that works gracefully across GitHub, Reddit, your personal blog, and any other platform you choose to use.