ToolSura
    ToolSura
    HomeTools
    Blog
    ToolSura
    ToolSuraPrivacy-First Tools

    Free utilities that run in your browser. No trackers, no accounts, no uploads.

    All Systems Operational

    Product

    • Free Online Tools
    • Contact
    • FAQs
    • About

    Legal

    • Privacy Policy
    • Cookie Policy
    • Terms & Conditions
    • Disclaimer

    Resources

    • Blog
    • Brand
    • Help

    Social Links

    • Bluesky
    • Mastodon
    • X
    • Product Hunt
    • GitHub
    • LinkedIn
    • DEV.to
    • YouTube

    © 2026 ToolSura. Free tools that run in your browser.

    Remote-First / Based in India

    Technical Manifesto

    Private • Client-Side • No Uploads

    ToolSura on Nick Launches
    Browser-Native
    Privacy-First
    Skip to main content
    Toolsura
    markdown
    C
    Callum Reid

    Every Markdown rule that matters, on one page

    September 28, 2026 · 7 min read

    A one-page Markdown syntax reference covering headings, emphasis, lists, links, code, tables, and escapes, with the CommonMark rule behind each one.

    "A 3D illustration of a Markdown document with a heading, numbered list, code block, table, and checkbox, surrounded by floating syntax tiles for the hash, list, image, link, and code symbols."
    "A 3D illustration of a Markdown document with a heading, numbered list, code block, table, and checkbox, surrounded by floating syntax tiles for the hash, list, image, link, and code symbols."

    Markdown looks like shorthand until you hit the edge cases. Two asterisks make bold text, or they do not, depending on what sits next to them. A list needs a blank line before it, or it becomes a paragraph. A backslash means something different inside a code span than outside one. Those are not quirks to memorize by feel; they are consequences of rules, and once you know the rules the edge cases stop being surprising.

    This cheat sheet covers the syntax defined by CommonMark version 0.31.2, the specification that removed most of Markdown's original ambiguity, plus the four extensions GitHub Flavored Markdown adds on top. Every entry below shows the syntax you type and the HTML you get back. When a rule has a sharp edge, the edge is called out.

    Key Takeaways

    • CommonMark 0.31.2 defines the core language; GFM is a strict superset adding tables, task lists, strikethrough, and autolinks.
    • Blank lines separate blocks. Most "why isn't my list working" problems are a missing blank line.
    • Code spans and fenced blocks are literal: Markdown syntax inside them renders as plain text, not markup.
    • A backslash escapes ASCII punctuation anywhere outside a code span.

    What Is a Markdown Syntax Cheat Sheet?

    A Markdown syntax cheat sheet is a lookup table for the symbols a parser recognizes and the HTML each one produces. It is not a style guide. It answers one question: given these characters, what will the renderer do with them?

    The value is that Markdown is genuinely ambiguous without a specification. Markdown was released in 2004 by John Gruber as a deliberately loose format, and parsers disagreed about the details for roughly a decade. CommonMark fixed that by writing an unambiguous grammar backed by more than 600 conformance test cases, and it is now the baseline that GitHub, GitLab, Reddit, and most modern renderers build on. When a converter claims CommonMark support, it means it agrees with that test suite rather than approximating the original syntax.

    A cheat sheet is worth keeping open because most people write Markdown for years without meeting the rules that only matter occasionally. Knowing them turns a puzzling render into a quick check.

    Headings and block structure

    Headings come in two forms. ATX headings use leading hashes, and CommonMark allows one to six of them, with an optional closing run:

    # Level 1
    ###### Level 6
    ### Closed style ###
    

    Setext headings underline the text instead, where a row of equals signs means level 1 and a row of hyphens means level 2:

    Setext Level 1
    ==============
    
    Setext Level 2
    --------------
    

    Prefer ATX. Setext level 2 is a single hyphen, and a stray hyphen under a line of text is an easy accident that silently changes a paragraph into a heading.

    Level ATX syntax Setext syntax
    1 # Heading Heading then =====
    2 ## Heading Heading then -----
    3 to 6 ### to ###### not available

    Three more block rules carry most of the weight:

    • Thematic break — three or more asterisks, hyphens, or underscores on their own line, such as ---, becomes an <hr>. Spaces between the characters are allowed, so - - - works too.
    • Indented code block — four leading spaces produces a <pre><code> block. This is the older form and it is fragile, because a stray space in an otherwise normal list changes the meaning. Fenced blocks are safer.
    • Fenced code block — three backticks or three tildes, optionally with a language hint after the opening fence. Tildes are the escape hatch when your code itself contains backticks.

    Emphasis, and why it trips people up

    Asterisks and underscores both mark emphasis, and both work in pairs:

    *italic* and _italic_
    **bold** and __bold__
    ***bold italic***
    

    The rule people miss is that the delimiter run has to match. CommonMark counts characters in the delimiter run, and the opening and closing runs must be equal length. This is wrong and renders literally:

    **bold*  and  *italic**
    

    The fix is to pick one delimiter per pair:

    **bold**  and  *italic*
    

    A related edge case is a delimiter that opens but never closes. *unclosed renders as literal text, because an unmatched delimiter is not emphasis. This is deliberate, and it is what lets you write 2 * 3 * 4 without the asterisks turning into italics.

    Lists, and the blank line people forget

    Unordered lists accept three markers interchangeably, and ordered lists take numbers followed by a period:

    - dash
    * asterisk
    + plus
    
    1. first
    2. second
    

    To nest, indent by the width of the parent item's content, commonly two or four spaces:

    - top level
      - nested item
    

    The single most common Markdown bug is a missing blank line before a list. Without it, the dash is read as the start of a setext heading underline or stays inside the paragraph as literal text:

    This paragraph is immediately followed by a list:
    - this item stays part of the paragraph
    
    This one works:
    
    - this item becomes a list
    

    Ordered lists only need an increasing sequence in CommonMark; the numbers you type are not required to be sequential. But write them in order anyway, because some renderers and older parsers are stricter.

    Links, images, and reference definitions

    Inline links put the target in parentheses right after the label. Titles go in quotes inside those parentheses:

    [link text](https://example.com)
    [link with title](https://example.com "Hover title")
    [escaped paren](https://example.com/a\(b\))
    

    Images use the same shape with a leading exclamation mark, and the text in brackets is the alt attribute:

    ![alt text](image.png)
    ![alt text](image.png "Title")
    

    Reference definitions separate the target from the label, which keeps paragraphs readable when you reuse the same URL many times. The definition goes anywhere in the document, and the label is referenced in brackets:

    [commonmark]: https://spec.commonmark.org/0.31.2/
    
    Read the [CommonMark spec][commonmark] before writing a parser.
    

    Autolinks wrap the URL in angle brackets and need no label text, which is the cleanest way to show a bare URL without it becoming a link in every renderer:

    <https://spec.commonmark.org/>
    

    Code, and why it is literal everywhere

    Inline code uses single backticks; fenced blocks use three. The defining property is that both treat their contents as literal text. This is what makes them safe:

    Use `*asterisks*` to show emphasis syntax literally.
    

    If your inline code itself needs a backtick, wrap the span in double backticks with a space on each side: `like this`.

    The language hint after the opening fence is a convention rather than a CommonMark requirement, but it drives syntax highlighting in most renderers, so it is worth writing. CommonMark itself does not color code; it only guarantees the text comes through unescaped and unparsed.

    Tables, task lists, and other GFM extensions

    Tables are the first GFM extension and the reason a lot of documentation moved to Markdown. A pipe-delimited header row, a delimiter row of dashes, then body rows:

    | Syntax | Produces |
    | --- | --- |
    | `**bold**` | strong emphasis |
    | `*italic*` | emphasis |
    

    Cells do not wrap across source lines in every implementation, so keep them on one line. Alignment is set with colons in the delimiter row: :--- left, :---: center, ---: right.

    Task lists are the second. They are ordinary list items with a bracket at the start, and the bracket must be a literal [ ] or [x] with a following space:

    - [x] shipped
    - [ ] pending
    

    Strikethrough is the third, and takes two tildes rather than one or three: ~~deleted text~~ becomes <del>. The fourth is extended autolinks, which turn bare www.example.com and bare email addresses into links without bracket syntax.

    Raw HTML passthrough is the fifth thing GFM documents, and it works in the opposite direction: a block of literal HTML in your Markdown passes through untouched. That is a genuine security consideration, which is the subject of why output needs sanitizing.

    Line breaks, escapes, and entities

    A single newline inside a paragraph is a soft break and stays a newline. To force a <br>, either end the line with two spaces or use a backslash, which is the more visible choice:

    Line one  
    Line two
    
    Line one\
    Line two
    

    A backslash escapes any ASCII punctuation character, which is how you write a literal asterisk without it becoming emphasis:

    \*not emphasis\*
    2 \* 3 \* 4
    

    Inside a code span, backslashes are literal. A backslash escape does not work there, and there is no need for one, because the code span is already inert.

    Named and numeric entity references pass through as well, in decimal and hexadecimal form:

    &nbsp; &amp; &copy;
    &#35; &#1234; &#X22;
    

    Related tools and further reading

    Now that you can read the syntax, these ToolSura tools cover the work that follows it. The Markdown to HTML converter renders what you write on the left into sanitized HTML on the right, entirely in your browser. The Markdown Linter checks source for the structural problems this sheet describes, such as inconsistent heading levels and missing alt text.

    If you are weighing the formats themselves rather than the syntax, Markdown vs HTML covers when each one fits. For the security question that follows any conversion, sanitizing Markdown output against XSS explains why a parser that accepts raw HTML needs a sanitizer downstream.

    The authoritative references are worth bookmarking: the CommonMark specification with its full conformance suite, the GitHub Flavored Markdown spec, and the GitHub writing documentation for how the extensions behave on the platform most people meet them.

    • Markdown Tables: Syntax and Gotchas
    • CommonMark vs GitHub Flavored Markdown
    Callum Reid

    Written by

    Callum Reid

    Markdown is a family of closely related dialects, and most bugs in it come from writing for one and rendering in another. On top of that sit tables, footnotes, task lists, strikethrough, attributes, maths and raw HTML. A renderer either enables a subset of these or ignores them silently, and ignored syntax usually surfaces as literal punctuation.

    Fenced code blocks are the most reliable part and still have edge cases. Info strings carry a language identifier for highlighting, and some renderers read options from the same string. An unclosed fence swallows the remainder of the document, which is why a stray backtick is worth checking first when a page renders short.

    Links get their own treatment. Reference-style links resolve anywhere in the document, which is convenient right up until two definitions collide. Bare URLs are autolinked by some renderers and left as plain text by others, and a link with mismatched brackets produces output that looks fine and points at the wrong place. Raw HTML is where sanitisation earns its place.

    Markdown passes HTML through by design, so a document containing a script tag or an event handler attribute reaches the browser unless the pipeline strips it. Sanitisers differ in which tags they allow, and allowing a tag for a benign reason can permit an attribute with a script handler, reintroducing the problem it was meant to remove. I cover heading level discipline too, because renderers frequently promote or demote headings to fit a template, and that silently breaks both the outline and accessibility.

    Share

    Frequently Asked Questions

    Comments

    Leave a Review

    Rate this tool
    Overall Rating
    Spam Protection Active