Markdown Cheat Sheet — Complete Syntax Guide with Examples

Markdown is a lightweight markup language created by John Gruber in 2004 with the goal of allowing people to write in a plain text format that is easy to read and easy to convert into structurally valid HTML. The philosophy behind Markdown is that the raw text should be publishable as-is, without looking like it has been marked up with tags or formatting instructions. A Markdown document should be readable in its plain text form, with the formatting syntax serving as natural visual cues rather than distracting code. This design philosophy distinguishes Markdown from other markup languages like HTML or LaTeX, where the source code is dense with tags that obscure the actual content.

Markdown has become the de facto standard for writing documentation, README files, blog posts, forum comments, and technical articles across the software development ecosystem. Platforms like GitHub, GitLab, Bitbucket, Stack Overflow, Reddit, Discord, and countless content management systems support Markdown natively. Developers use it for project documentation and wikis, technical writers use it for knowledge bases and API documentation, and content creators use it for blog posts and newsletters. Its simplicity means that anyone can learn the basics in minutes and be productive immediately, without the learning curve associated with more complex formatting systems.

The Markdown ecosystem has grown to include several variants and extensions beyond the original specification. CommonMark is a standardized specification that resolves ambiguities in the original Markdown syntax. GitHub Flavored Markdown adds features like task lists, tables, strikethrough text, and automatic URL linking. Other extensions support footnotes, definition lists, mathematical notation, and diagram generation. Despite this fragmentation, the core syntax remains consistent across implementations, so learning standard Markdown provides a foundation that transfers to every platform and tool that supports the format.

Markdown files use the .md or .markdown extension and can be created and edited with any plain text editor. Because Markdown is plain text, files are small, version-control friendly, and portable across operating systems. There is no vendor lock-in or proprietary format to worry about. Your content remains accessible and editable indefinitely, regardless of which tool or platform you originally used to create it. This longevity and portability make Markdown an excellent choice for any content that needs to last.

Headings in Markdown are created by prefixing a line with one or more hash symbols. A single hash creates a top-level heading equivalent to an HTML h1 element, two hashes create a second-level heading equivalent to h2, and so on through six levels. The space between the hash symbols and the heading text is required for proper rendering. Headings are fundamental to document structure because they create a hierarchy that both readers and search engines use to understand the organization of the content. Well-structured headings also enable automatic generation of tables of contents in many Markdown renderers and documentation platforms.

Bold and italic formatting provide emphasis within body text. Wrapping text in double asterisks or double underscores makes it bold, while single asterisks or single underscores create italic text. Combining both with triple asterisks produces bold italic text. The asterisk syntax is generally preferred over underscores because underscores can cause issues in the middle of words in some Markdown parsers. For example, some renderers treat underscores within a word as literal characters rather than formatting markers, while asterisks are consistently interpreted as emphasis markers in all positions.

Strikethrough text, which displays with a horizontal line through it, is created by wrapping text in double tildes. This formatting is part of GitHub Flavored Markdown and is supported on most modern platforms. Strikethrough is commonly used to indicate corrections, show changes in pricing, mark completed items in a list, or convey a conversational tone where the author appears to cross out a thought. While not part of the original Markdown specification, it has become widely adopted and is expected by most Markdown users today.

Horizontal rules are created by placing three or more hyphens, asterisks, or underscores on a line by themselves. These render as a horizontal line spanning the width of the content area and are used to visually separate sections of a document. A blank line before and after the horizontal rule is recommended to prevent the hyphens from being interpreted as a heading underline. Horizontal rules are particularly useful in long documents where a visual break signals a major topic change that headings alone may not sufficiently communicate.

Inline links are the most common link format in Markdown. The syntax places the link text in square brackets immediately followed by the URL in parentheses. You can optionally add a title attribute by including a quoted string after the URL inside the parentheses, which displays as a tooltip when the user hovers over the link. This inline format keeps the link destination visible alongside the text, making it easy to verify URLs during writing and editing. For short URLs, inline links are clean and readable, but for long URLs they can make the source text harder to scan.

Reference-style links separate the link text from the URL by using a label system. The link text is followed by a label in square brackets, and then the label is defined elsewhere in the document with the URL. This approach keeps the body text clean and readable by moving long URLs to the bottom of the document or to the end of the paragraph. Reference links are especially valuable in documents with many links or when the same URL is referenced multiple times, because updating the URL in the definition automatically updates every reference to it.

Images use syntax nearly identical to links but with an exclamation mark prefix. The square brackets contain alt text that describes the image for screen readers and displays when the image fails to load, while the parentheses contain the image URL. Like links, images can include an optional title attribute. Markdown does not natively support image sizing or alignment, so if you need to control image dimensions, most renderers accept raw HTML img tags within Markdown documents. Some extended Markdown flavors add custom syntax for image dimensions, but this is not standardized across platforms.

Automatic linking is a feature in GitHub Flavored Markdown and many other modern renderers that converts bare URLs and email addresses into clickable links without requiring any special syntax. Simply typing a full URL starting with http or https will render it as a clickable link. To prevent automatic linking, you can wrap the URL in backticks to render it as inline code. Automatic linking is convenient for quick notes and casual writing, but explicit link syntax with descriptive text is preferred for published content because it gives readers context about the link destination before they click.

Unordered lists are created by starting each line with a hyphen, asterisk, or plus sign followed by a space. All three markers produce identical output, so the choice is a matter of personal preference or team convention. Hyphens are the most popular choice in the developer community because they are easy to type, visually distinct from content, and less likely to be confused with other Markdown syntax like emphasis markers. Consistency within a single document is more important than which specific marker you choose, so pick one and stick with it throughout.

Ordered lists are created by starting each line with a number followed by a period and a space. Interestingly, the actual numbers you use do not matter for the rendered output in most Markdown parsers. You can number every item as 1 and the renderer will still produce a properly sequenced list. This design choice means you can insert items in the middle of a list without renumbering everything below. However, many writers prefer to use sequential numbers for the sake of readability in the raw Markdown source, especially in short lists where the effort of maintaining accurate numbering is minimal.

Nested lists are created by indenting list items with spaces or a tab. The indentation level determines the nesting depth, allowing you to create multi-level outlines and hierarchies. You can nest unordered lists inside ordered lists and vice versa, mixing list types at different levels to suit the content structure. Most Markdown processors require two to four spaces of indentation per nesting level, though the exact requirement varies by renderer. Testing your nested lists in the target platform is advisable because indentation handling is one of the areas where Markdown implementations differ most.

Task lists, also known as checkboxes, are a GitHub Flavored Markdown extension that adds interactive checkboxes to list items. Each item starts with a square bracket pair containing either a space for unchecked or an x for checked. On platforms like GitHub, these checkboxes are interactive in rendered views, allowing users to toggle them directly. Task lists are widely used in issue descriptions, pull request templates, and project planning documents to track progress on a set of related items. Even on platforms that render them as static checkboxes, they provide a clear visual indicator of completion status.

Inline code is created by wrapping text in single backticks and is used for short code references within a sentence. This is appropriate for variable names, function calls, file paths, command names, CSS properties, configuration keys, and any other technical term that should be visually distinguished from the surrounding prose. Inline code renders in a monospaced font with a subtle background color, making it immediately recognizable as a technical term rather than regular text. Using inline code consistently for technical references improves readability and helps readers quickly scan for the specific terms they are looking for.

Fenced code blocks are created by wrapping multiple lines of code in triple backticks on their own lines. The opening triple backticks can be followed by a language identifier that enables syntax highlighting in renderers that support it. Common language identifiers include javascript, python, html, css, json, bash, sql, typescript, and many more. Syntax highlighting dramatically improves code readability by color-coding keywords, strings, comments, and other language elements. Always specify the language when the code block contains a recognizable programming language, as the highlighting provides significant value to readers.

Indented code blocks are an older Markdown syntax where lines indented with four spaces or a tab are treated as code. While this syntax still works in most renderers, fenced code blocks with backticks are strongly preferred because they support language-specific syntax highlighting, do not require every line to be individually indented, and have a clear start and end delimiter that prevents ambiguity with other indented elements like nested lists. Many modern Markdown style guides recommend using fenced code blocks exclusively and avoiding the indented code block syntax entirely.

Code blocks can contain any text, not just programming code. They are also used for displaying terminal output, configuration file contents, log entries, data samples, and any other text that should be rendered verbatim without Markdown processing. Text inside a code block is rendered exactly as written, preserving whitespace, line breaks, and special characters. This makes code blocks the appropriate choice whenever you need to show content that should not be interpreted as Markdown syntax, such as text that contains asterisks, brackets, or other characters that would otherwise trigger formatting.

Tables in Markdown are created using pipes and hyphens to define columns and rows. The first row contains column headers, the second row contains a separator line of hyphens with pipes between columns, and subsequent rows contain the data. Column alignment can be controlled by placing colons in the separator row: a colon on the left aligns left, on the right aligns right, and colons on both sides center the column. While the raw Markdown for tables can look uneven with varying column widths, most editors offer table formatting plugins that automatically align the pipes for readability.

Tables in Markdown have significant limitations compared to HTML tables. Markdown tables do not support merged cells, multi-line content within cells, nested tables, or row spanning. Each cell must contain its content on a single line, and complex layouts are not possible without falling back to raw HTML. For simple tabular data like comparison charts, feature lists, pricing tiers, and configuration options, Markdown tables are perfectly adequate. For complex data presentations, consider using HTML tables within your Markdown document or generating the table output from a separate tool.

Blockquotes are created by prefixing lines with the greater-than symbol. They are traditionally used for quoting external sources, and they render with a visual indicator, typically a vertical bar on the left side and a slightly indented or shaded background. Blockquotes can contain any Markdown formatting including headings, lists, code blocks, and nested blockquotes. Nested blockquotes are created by using multiple greater-than symbols, allowing you to represent a chain of quoted replies similar to email threading.

Beyond their traditional use for quotations, blockquotes are frequently repurposed in documentation as callout boxes for notes, warnings, tips, and important information. GitHub Flavored Markdown has formalized this pattern with alert syntax that renders styled callout boxes using blockquote syntax with special keywords. These callouts use a greater-than prefix followed by a keyword in brackets such as NOTE, TIP, IMPORTANT, WARNING, or CAUTION, each rendering with a distinct color and icon. This pattern has become standard in open-source documentation because it draws attention to critical information that readers should not overlook.

Footnotes allow you to add supplementary information without interrupting the flow of the main text. The footnote reference is placed inline using a caret and label in square brackets, and the footnote content is defined at the bottom of the document using the same label. When rendered, the reference becomes a superscript number linking to the footnote content, and the footnote typically appears at the bottom of the page or document. Footnotes are supported in many Markdown flavors including PHP Markdown Extra, Pandoc, and some GitHub contexts, though they are not part of the original specification or CommonMark.

Definition lists provide a way to present terms and their definitions in a structured format. The term is written on its own line, and the definition follows on the next line prefixed with a colon and a space. Multiple definitions can be provided for a single term, and definitions can contain multiple paragraphs and other block-level elements. Definition lists are useful for glossaries, API documentation where you need to describe parameters and their meanings, and any content that follows a term-and-explanation pattern. Support for definition lists varies across Markdown processors.

Mathematical notation is supported in Markdown through LaTeX syntax, typically delimited by dollar signs. Single dollar signs create inline math expressions, while double dollar signs create display math blocks that are centered on their own line. This feature is essential for scientific and academic writing where equations, formulas, and mathematical symbols need to be rendered accurately. Platforms like GitHub, Jupyter notebooks, and many documentation sites support math rendering through libraries like MathJax or KaTeX that convert the LaTeX syntax into properly formatted mathematical notation.

Diagram generation from text descriptions is an increasingly popular Markdown extension. Tools like Mermaid allow you to write diagram definitions in fenced code blocks that render as flowcharts, sequence diagrams, Gantt charts, class diagrams, and other visualizations. GitHub natively supports Mermaid diagrams in Markdown files, making it possible to include visual documentation alongside text without managing separate image files. The text-based diagram source is version-controllable, diffable, and easy to update, which addresses the longstanding challenge of keeping documentation diagrams synchronized with the codebase they describe.