Markdown Cheat Sheet: A Complete Guide to Markdown Syntax

Published on May 8, 2026

Markdown has become one of the most popular plain-text formatting languages in the world. Created by John Gruber in 2004 with the goal of making it easy to write rich text using a simple, readable syntax, Markdown has since been adopted by millions of developers, writers, and content creators. It powers the documentation on GitHub, the messages in Slack and Discord, the posts on Reddit, and countless static blogs and websites. If you spend any time writing online, learning Markdown is one of the highest-leverage skills you can pick up. This guide covers everything you need to get started, from basic text formatting to advanced features like tables and code blocks.

What is Markdown?

Markdown is a lightweight markup language that lets you write formatted text using a plain-text editor. The key insight behind Markdown is that the raw text itself should be readable even before it is rendered. When you write **bold** in Markdown, it is obvious to any human reader that the word should be bold, even without seeing the final HTML output. This readability sets Markdown apart from heavier markup systems like HTML or LaTeX, where the raw source can be difficult to parse visually.

Markdown files typically use the .md or .markdown extension. They can be rendered to HTML by any Markdown processor, and most platforms that support Markdown do this conversion automatically. The beauty of Markdown is its simplicity: you can learn the core syntax in about ten minutes and be productive immediately. As you need more advanced formatting, you can gradually pick up additional syntax elements like tables, footnotes, and definition lists.

There are several "flavors" of Markdown, which are extensions of the original specification. The most common is GitHub Flavored Markdown, or GFM, which adds features like task lists, tables, strikethrough text, and syntax highlighting for code blocks. Other popular flavors include CommonMark, which aims to standardize the language, and MultiMarkdown, which adds support for citations and metadata. Most Markdown tools, including the Markdown Preview tool on ToolBox, support the core syntax plus the most popular extensions.

Basic Markdown Syntax

Let us start with the fundamental building blocks of Markdown. These are the elements you will use in almost every document you write.

Headings. Use the hash symbol to create headings. One hash is a top-level heading, two hashes is a second-level heading, and so on, up to six levels. Always include a space after the hash symbols.

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

Text formatting. Surround text with asterisks or underscores to apply emphasis. Single asterisks or underscores produce italic text, and double asterisks or underscores produce bold text. You can combine them for bold italic text.

*italic text*
_italic text_
**bold text**
__bold text__
***bold italic text***

Links. Create hyperlinks by placing the display text in square brackets followed by the URL in parentheses. You can also add an optional title attribute in quotes.

[Visit ToolBox](https://sady-tools.com)
[Visit ToolBox](https://sady-tools.com "Free Online Tools")

Images. The syntax for images is almost identical to links, but with an exclamation mark prefix. The square brackets contain the alt text.

![Alt text](https://example.com/image.jpg)

Lists. Use asterisks, plus signs, or hyphens for unordered lists. Use numbers followed by periods for ordered lists. Indent sub-items with two or four spaces.

- Item one
- Item two
  - Sub-item
  - Sub-item
1. First item
2. Second item

Blockquotes. Use the greater-than symbol to create blockquotes. You can nest blockquotes by adding additional greater-than symbols.

> This is a blockquote.
>> This is a nested blockquote.

Horizontal rules. Three or more hyphens, asterisks, or underscores on a line create a horizontal rule.

---
***

Advanced Markdown Syntax

Once you have mastered the basics, these advanced features will let you create richer documents.

Tables. Tables are created using pipes and hyphens. The header row is separated from the body by a row of hyphens. You can align columns using colons in the separator row.

| Name     | Age | City       |
|----------|:---:|:-----------|
| Alice    | 29  | San Francisco |
| Bob      | 35  | New York   |
| Charlie  | 42  | Chicago    |

Code blocks. For inline code, use single backticks. For code blocks, use triple backticks, optionally followed by a language name for syntax highlighting. Indented code blocks using four spaces also work but do not support language-specific highlighting.

This is `inline code`.

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

Task lists. Task lists are a GitHub Flavored Markdown extension. Use hyphens followed by square brackets with a space for an unchecked item or an x for a checked item.

- [x] Write the introduction
- [ ] Complete the examples
- [ ] Publish the article

Strikethrough. Use double tildes to create strikethrough text, another GFM extension.

This is ~~strikethrough~~ text.

Footnotes. Some Markdown processors support footnotes using the following syntax. The footnote reference goes in square brackets with a caret, and the definition uses the same syntax followed by a colon and the text.

Here is a statement with a footnote.[^1]

[^1]: This is the footnote content.

Escaping special characters. If you need to display a literal asterisk, backtick, or other Markdown character, prefix it with a backslash. For example, \* renders as a literal asterisk without triggering italic formatting.

Complete Markdown Syntax Reference Table

This table provides a quick reference for every major Markdown element covered in this guide. Bookmark this section for fast lookup when you need to recall a specific syntax pattern.

Markdown for Documentation Projects

Markdown is the backbone of modern software documentation. Whether you are maintaining an open-source library, writing internal team wikis, or publishing API references, Markdown offers a consistent, portable way to produce professional documentation. Here is how to get the most out of Markdown for documentation workflows.

Structure your README effectively. A well-structured README.md is the first thing visitors see on GitHub, GitLab, or Bitbucket. Start with a clear H1 heading for your project name, followed by a brief description. Use H2 headings for sections like Installation, Usage, Configuration, API Reference, Contributing, and License. This convention is so widely adopted that developers instinctively know where to find specific information in any well-written README. Use code blocks with language annotations for installation commands and code examples so they render with proper syntax highlighting.

Use relative links for internal navigation. Markdown supports relative links, which are essential for multi-page documentation. Link to other documentation files in the same repository using relative paths: [Setup Guide](./docs/setup.md). This keeps your documentation navigable and ensures links work whether the repository is viewed on GitHub, cloned locally, or deployed to a documentation site. You can also link to specific headings within the same document using anchor tags: [Jump to Installation](#installation).

Leverage admonitions and callouts. Many documentation platforms extend Markdown with special blockquote syntax for notes, warnings, and tips. In GitHub Flavored Markdown, you can use > **Note:** or > **Warning:** to create visually distinct callout boxes when rendered. These are invaluable for highlighting important caveats, security considerations, or deprecation notices that readers should not miss.

Keep a consistent style guide. For team documentation projects, establish a Markdown style guide. Agree on conventions for: heading capitalization (title case vs sentence case), spacing around headings, code block language annotations, and image sizing. Tools like markdownlint can automatically enforce these rules in CI/CD pipelines, ensuring consistency across contributions from multiple authors.

Markdown Extensions: GFM, MDX, and Beyond

The original Markdown specification was intentionally minimal, but the community has developed several extensions that address its limitations. Understanding these extensions helps you choose the right variant for your project.

GitHub Flavored Markdown (GFM) is the most widely used Markdown extension. It adds tables, task lists, strikethrough, autolinking of URLs, and fenced code blocks with syntax highlighting. GFM also disables some of the original Markdown's quirks, such as using underscores for emphasis inside words, to prevent unintended formatting. If you work with code repositories on GitHub or GitLab, you are already using GFM daily. Its specification is publicly documented, and many static site generators support it natively.

MDX is a powerful extension that lets you use JSX components inside Markdown documents. Popularized by frameworks like Next.js and Docusaurus, MDX allows you to import and use React components directly in your Markdown files. For example, you can embed an interactive chart, a live code editor, or a custom callout component alongside your regular Markdown content. MDX is ideal for documentation sites that need interactive examples, but it requires a build step and a React-based rendering environment. It is overkill for simple README files but transformative for rich technical documentation.

CommonMark is a standardization effort that aims to resolve ambiguities in the original Markdown specification. It provides a rigorous, unambiguous definition of Markdown syntax, complete with a test suite that processors can validate against. Many modern Markdown parsers are CommonMark-compliant, which means you can expect consistent behavior across different tools. When choosing a Markdown processor for a new project, CommonMark compliance is a strong indicator of reliability.

Other notable extensions include MultiMarkdown (which adds tables, footnotes, and metadata), RMarkdown (used in data science for combining R code with Markdown), and AsciiDoc (a more powerful alternative that is not technically Markdown but serves a similar purpose). For most users, GFM is the default choice, while MDX and CommonMark are worth exploring for specific use cases.

Where is Markdown Used?

Markdown has become ubiquitous across the internet. Here are some of the most prominent places you will encounter it.

GitHub and GitLab. Every repository on GitHub has a README.md file that renders as the landing page of the repository. Issues, pull requests, and comments all support Markdown. Writing clear Markdown is an essential skill for open source contributors because it directly affects how your project is presented to the world. GitHub uses GitHub Flavored Markdown, which includes syntax highlighting, task lists, and emoji support.

Documentation and static sites. Tools like Jekyll, Hugo, and Next.js can generate entire websites from Markdown files. Many documentation frameworks, including Docusaurus, GitBook, and MkDocs, use Markdown as their primary authoring format. This makes Markdown the de facto standard for technical documentation. If you are writing API docs, user guides, or tutorials, you will almost certainly be writing Markdown.

Blogging platforms. Ghost, Medium, and Dev.to all support Markdown for writing articles. Even if the platform uses a rich text editor, it is often backed by Markdown under the hood. Writing in Markdown gives you the freedom to switch platforms without losing your formatting.

Messaging and collaboration. Slack, Discord, Microsoft Teams, and many other collaboration tools support Markdown syntax for formatting messages. While the implementations vary, the core syntax is consistent enough that your skills transfer across platforms. Being able to format code snippets, lists, and emphasis in chat messages makes you a more effective communicator.

Frequently Asked Questions About Markdown

What is the difference between Markdown and HTML?

Markdown is a lightweight markup language designed for readability and ease of writing, while HTML is a full-featured markup language for structuring web pages. Markdown compiles to HTML, meaning you can use either or both in the same document. Markdown is simpler and faster for basic formatting, but HTML gives you finer control over layout, styling, and interactive elements. Most Markdown processors allow inline HTML for cases where Markdown syntax is insufficient.

Can I use Markdown for email newsletters?

Yes, many email marketing platforms support Markdown for composing newsletters. Tools like Mailchimp, ConvertKit, and Substack allow you to write in Markdown and automatically convert it to HTML for delivery. However, email HTML rendering varies across clients, so always preview your rendered Markdown email in multiple clients before sending. Some email-specific Markdown extensions, like MJML, are designed to handle email layout challenges.

Does Markdown support tables with merged cells?

Standard Markdown and GFM do not support merged or spanned cells in tables. Each cell in a Markdown table maps to exactly one row and one column. If you need merged cells for complex layouts, you have two options: use inline HTML within your Markdown document (<table> with colspan and rowspan attributes), or use a different format entirely. Some extended Markdown flavors, like Markdown Extra, do support cell merging, but this is not universal.

How do I add syntax highlighting to code blocks?

To enable syntax highlighting, specify the programming language immediately after the opening triple backticks. For example, ```javascript or ```python. The Markdown processor then applies the appropriate highlighting based on the language. Most platforms (GitHub, GitLab, and Markdown Preview tools) support dozens of languages. If you omit the language specifier, the code block renders as plain text without highlighting.

Markdown is a small language with big impact. Whether you are documenting a project, writing a blog post, or collaborating with a team, Markdown makes your text clearer and more expressive with minimal effort. Keep this guide handy, use a Markdown Preview tool to check your work, and you will be writing beautiful formatted text in no time.

Related Tools

These tools complement your Markdown workflow and help with text processing and formatting tasks.

• Markdown Preview - Preview and render Markdown content with live output and syntax highlighting.
• JSON Formatter - Format, validate, and beautify JSON data for configuration files and API work.
• Word Counter - Count words, characters, and lines in your Markdown documents and articles.
• Base64 Encoder - Encode and decode text or binary data to and from Base64 format.