Markdown Syntax Guide

Try Syntax

Syntax Reference

What is Markdown Syntax?

Markdown is a lightweight plain-text formatting language created by John Gruber in 2004. It uses simple symbols and characters to mark up text, making it easy to write content that converts to HTML without looking cluttered in its raw form. Markdown has become the standard for documentation, README files, blogs, and any content that needs simple, readable formatting. Unlike HTML, which requires opening and closing tags, Markdown uses intuitive markers like asterisks for emphasis and hyphens for lists, making it accessible to anyone who can type plain text.

CommonMark is the most widely accepted specification for Markdown, defining how parsers should interpret the syntax. It emerged from community efforts to standardize Markdown behavior across different platforms, as the original syntax left many edge cases undefined. By learning CommonMark-compliant syntax, your content will render consistently across GitHub, GitLab, Discord, Slack, Reddit, Stack Overflow, and dozens of other platforms. The original Markdown specification by John Gruber remains foundational, though extensions like GitHub Flavored Markdown add features such as task lists, strikethrough text, and tables.

Modern Markdown comes in several flavors tailored to specific platforms. GitHub Flavored Markdown (GFM) adds tables, checkboxes, and autolinks. GitLab Markdown supports similar extensions plus diagrams. Learning core CommonMark syntax gives you a portable foundation that works everywhere, while platform-specific extensions let you leverage tool-specific features when needed.

How to Use the Markdown Syntax Guide

Follow these steps to learn and try Markdown syntax. Each step uses the actual panels on this page.

Paste, Upload, or Load Sample

Paste Markdown into the left Try Syntax panel, or click Upload to load a .md file. Click Sample to see example subscriber API docs. The right Syntax Reference panel shows CommonMark and GFM patterns.

Practice and Reference

Use the reference for headings, emphasis, lists, links, tables, code blocks. Copy examples into the left panel to try them. Covers CommonMark plus GitHub Flavored Markdown extensions.

Copy or Download

Click Copy or Download to save the reference. Use Clear to start fresh. All processing runs in your browser.

When You'd Actually Use This

Writing Documentation

Technical documentation, API reference guides, and software documentation are almost universally written in Markdown. Python docs, Node.js guides, and most open-source projects use Markdown for their documentation sites. A syntax reference keeps you productive when writing complex documentation with multiple heading levels, code examples, and cross-references.

README and Project Files

Every GitHub project has a README.md file describing the project, usage, installation, and contribution guidelines. These files are written entirely in Markdown and are often the first thing users see. Tables for feature comparisons, code blocks for examples, and formatted lists are all standard in README files.

Content Creation and Publishing

Blog platforms like Jekyll, Hugo, and Ghost accept Markdown for content. Medium-style platforms, ghost platforms, and static site generators all use Markdown as their primary input format. Knowing syntax helps you write faster and maintain consistent formatting across all your published content.

Collaborative Communication

Slack, Discord, GitHub issues, pull request comments, and forum posts all support Markdown formatting. When you're reviewing code, reporting bugs, or collaborating in chat, Markdown lets you format your message clearly without breaking the flow of conversation. Quick syntax knowledge saves you time in these daily workflows.

Common Questions (FAQ)

Can I use HTML inside Markdown?

Yes, Markdown allows you to mix raw HTML. If Markdown doesn't support something you need, you can write HTML directly and it will pass through to the output. However, this reduces portability and readability of your source. According to the CommonMark spec, HTML blocks and inline HTML are recognized and passed through unchanged. Use this sparingly—usually Markdown syntax is sufficient.

What's the difference between asterisks and underscores for emphasis?

Functionally, they're identical in CommonMark—*text* and _text_ both produce italics, **text** and __text__ both produce bold. The choice is stylistic. Many teams prefer asterisks for consistency and because they're easier to type on most keyboards. Underscores can cause issues in words with emphasis-like patterns (e.g., "file_name_here"), which is why asterisks are often recommended.

How do line breaks work in Markdown?

This is a common source of confusion. A single newline in your source is treated as a space—the line is merged with the next one. To create a real line break (a <br> in HTML), either add two spaces at the end of the line before pressing Enter, or use a backslash before the newline. For paragraph breaks, use a blank line (two consecutive newlines). The CommonMark spec explains this in detail with examples.

Are tables supported everywhere in Markdown?

No. Tables are part of GitHub Flavored Markdown and other extensions, but they're not in the CommonMark specification. Most modern platforms (GitHub, GitLab, Discord) support them, but some parsers will ignore the pipe syntax. If you need tables to work everywhere, verify that your target platform supports GFM or consider using a different approach.

How do I escape special characters?

Use a backslash (\) before characters that have special meaning in Markdown: backslash itself (\), backtick (`), asterisk (*), underscore (_), braces ({}), square brackets ([]), parentheses (()), hash (#), plus (+), minus (-), period (.), and exclamation (!). For example, \*not italic\* renders the asterisks literally instead of creating italics. According to CommonMark backslash escapes, only these specific characters need escaping.

What's the best way to format code in Markdown?

For inline code, use single backticks: `code here`. For code blocks, use triple backticks with an optional language tag (```javascript) for syntax highlighting. Avoid indenting code as a code block—fenced code blocks are clearer and more portable. If you need to show code containing backticks, use more backticks to delimit: ` ``backticks`` `. See code spans and fenced code blocks in the CommonMark spec.