Markdown is a lightweight markup language that has become the go-to syntax for formatting text across various platforms. Whether you're writing GitHub documentation, creating README files, or formatting content in note-taking apps, knowing markdown can save you time and make your content more readable.

I've been using markdown for years in my development work, and I've compiled this cheat sheet as a quick reference to help you format your text efficiently. Let's dive in!

Table of contents

• Markdown basics

• Headers and titles

• Text formatting

• Lists

• Links

• Images

• Code formatting

• Tables

• Blockquotes

• Horizontal rules

• Line breaks

• Extended markdown

• Footnotes

• Task lists

• Emoji

• Common pitfalls

• Markdown tools and resources

Markdown basics

Markdown was created by John Gruber in 2004 with the goal of making text formatting intuitive and readable. The beauty of markdown is that it's simple to learn but powerful enough for most documentation needs.

The syntax is designed to be readable even in its raw form. You've probably used markdown-like formatting without even realizing it when using asterisks for emphasis in chat apps or using hashtags for headings.

Headers and titles

Headers are created using the hash symbol (#). The number of hash symbols corresponds to the heading level:

They render as:

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5

Heading 6

There's also an alternative syntax for H1 and H2 using underlines:

I personally stick to the hash symbol method as it's more consistent across all heading levels.

Text formatting

Markdown provides several ways to format text:

Bold text: Wrap text with double asterisks or double underscores

Italic text: Wrap text with single asterisks or single underscores

Bold and italic: Combine both with triple asterisks or underscores

Strikethrough: Use double tildes

I find it helpful to be consistent with your choice of symbols. I typically use asterisks for both bold and italic formatting since it's more universally supported across different markdown implementations.

Lists

Markdown supports both ordered and unordered lists.

Unordered lists

You can create unordered lists using asterisks, plus signs, or hyphens:

All three will render similarly:

• Item 1
• Item 2
  • Nested item 1
  • Nested item 2

For nested items, indent with spaces (typically 2 or 4 spaces).

Ordered lists

For ordered lists, use numbers followed by periods:

This renders as:

1. First item
2. Second item
3. Third item
   1. Nested item 1
   2. Nested item 2

A neat feature of markdown is that the actual numbers don't matter for rendering. This sequence would render identically:

This makes it easier to reorder items without having to renumber the entire list. Though for readability's sake, I still prefer to number them correctly in the source.

Links

Links are essential in documentation. Markdown offers several ways to create them:

Inline links

The most common format:

You can also add a title that appears on hover:

`

Reference links

These are useful when you have multiple references to the same URL:

The reference can be placed anywhere in the document, making the main text cleaner.

Auto links

For simple URLs, you can just wrap them in angle brackets:

Or in many markdown implementations, URLs typed directly will automatically become links:

One trick I've found useful is using reference links for URLs that appear multiple times in a document. It makes the source more maintainable if the URL ever changes.

Images

Images in markdown are similar to links, just with an exclamation mark at the beginning:

Like links, you can add titles:

And use reference style:

For adding width and height attributes, you'll typically need to use HTML:

Some extended markdown implementations allow for image alignment and sizing, but these aren't part of the standard syntax.

Code formatting

Code formatting is particularly important for technical documentation. Markdown provides two ways to format code:

Inline code

For small snippets within a paragraph, use backticks:

This renders as: Use the print() function to output text.

Code blocks

For larger blocks of code, use triple backticks to create a fenced code block:

Many markdown implementations support syntax highlighting by specifying the language after the first set of backticks:

This will render with JavaScript syntax highlighting:

Alternatively, you can indent code blocks with four spaces or one tab, but fenced code blocks are generally preferred for their readability and syntax highlighting capabilities.

Tables

Tables in markdown are created using pipes and hyphens:

This creates:

You can align columns using colons in the separator line:

This renders as:

Tables can be a bit tedious to format by hand, but there are many online tools that can generate markdown tables from CSV data or provide interactive table editors.

Blockquotes

Blockquotes are created using the greater-than character (>):

This renders as:

This is a blockquote. It can span multiple lines.

It can also have multiple paragraphs.

Blockquotes can be nested by adding additional > characters:

They can also contain other markdown elements:

I find blockquotes particularly useful for highlighting important notes or quotes from other sources in documentation.

Horizontal rules

Horizontal rules (dividers) can be created using three or more asterisks, hyphens, or underscores:

All three methods render as a horizontal line:

---

These can be useful for separating content sections, though I generally prefer using headers for major section divisions for better document structure.

Line breaks

Line breaks in markdown can be a bit tricky:

To create a new paragraph, leave a blank line between text blocks:

For a line break without a new paragraph (i.e., a soft break), end a line with two or more spaces, then press Enter:

Some markdown implementations also support the HTML <br> tag for line breaks.

The two-space method is not very intuitive (and hard to see in editors), which is why some extended markdown syntaxes have introduced additional ways to create line breaks.

Extended markdown

While the core markdown syntax is consistent across implementations, many platforms and tools add their own extensions. Here are some common extended features:

Footnotes

Footnotes are supported in GitHub Flavored Markdown and many other variants:

This creates a superscript number that links to the footnote content at the bottom of the page.

Task lists

Task lists (or checklists) are popular in project management contexts:

This renders as:

• Completed task
• Incomplete task
• Another task

Task lists are particularly useful in GitHub issues and project boards.

Emoji

Many markdown implementations support emoji through shortcodes:

This renders as emoji icons. The exact appearance varies by platform.

Definition lists

Some implementations support definition lists:

Heading IDs

Custom IDs can be assigned to headings for linking:

You can then link directly to this heading with [Link](#custom-id).

Highlighting

Some implementations support text highlighting:

Subscript and superscript

It's worth noting that support for these extended features varies widely. When writing for specific platforms like GitHub, Jekyll, or Discord, it's good to check their documentation for supported markdown extensions.

Common pitfalls

Even though markdown is designed to be simple, there are a few common issues people encounter:

1. Inconsistent line breaks: Remember that a single line break often doesn't create a new paragraph. Use blank lines between paragraphs.

2. Escaping special characters: If you want to use characters like *, _, # literally without their formatting function, escape them with a backslash:

3. List continuation: To include paragraphs within list items, indent them to align with the text:

4. URL spaces: Spaces in URLs need to be encoded (usually as %20). Many markdown processors don't handle this automatically.

5. Table formatting: Tables can break if content includes pipe characters. Escape them with backslashes.

6. Nested lists indentation: Make sure to use consistent indentation for nested lists (typically 2 or 4 spaces).

7. HTML in markdown: Most implementations allow HTML, but the integration can sometimes be tricky, especially with block-level elements.

A personal frustration I've encountered is inconsistent implementation across platforms. A markdown document that renders perfectly on GitHub might break on another platform due to subtle differences in implementation.

Markdown tools and resources

Here are some tools and resources that can help with your markdown workflow:

Editors with markdown support

• VS Code: Great syntax highlighting and preview

• Typora: WYSIWYG markdown editor

• StackEdit: Online markdown editor

• iA Writer: Distraction-free writing with markdown support

• Obsidian: Knowledge base that supports markdown linking

Markdown converters

• Pandoc: Convert between markdown and numerous other formats

• Marked 2: Preview tool for macOS

• Dillinger: Online markdown editor and preview

Cheat sheets and references

• GitHub Markdown Guide: Comprehensive guide to GitHub Flavored Markdown

• Markdown Guide: Detailed reference for all markdown elements

I personally use VS Code for most of my markdown writing due to its excellent extensions like "Markdown All in One" that provide shortcuts, auto-completion, and preview capabilities.

Conclusion

Markdown has become the de facto standard for simple text formatting across numerous platforms due to its readability and ease of use. This cheat sheet covers the essentials, but remember that different platforms may implement markdown slightly differently.

The best way to get comfortable with markdown is to use it regularly. Start with basic formatting like headers, lists, and emphasis, then gradually incorporate more advanced features as needed.

Whether you're documenting code, writing README files, or communicating with users during an outage, markdown provides a simple yet powerful way to format your text without getting in the way of your content.