Markdown Formatting Cheat Sheet: Syntax, Tips, and Common Patterns

Markdown has become the default writing format for technical documentation, README files, blog platforms, note-taking apps, and chat systems. Created by John Gruber in 2004, its original goal was simple: let people write in plain text that reads naturally and converts cleanly to HTML. Two decades later, that simplicity has made it the lingua franca of developer communication. GitHub uses it for issues, pull requests, and wikis. Slack and Discord render it in messages. Static site generators like Jekyll, Hugo, and Astro treat it as the primary content format. If you write anything on the web, you will encounter Markdown.

The appeal lies in portability and readability. A Markdown file is just a text file -- it opens in any editor, diffs cleanly in version control, and survives format migrations that would destroy a Word document or Google Doc. You do not need a special application to read it. The raw source is legible on its own, and when rendered, it produces clean semantic HTML without the bloat of a WYSIWYG editor. This makes it ideal for documentation that lives alongside code, where the content needs to be versioned, reviewed, and merged just like the source files around it.

Understanding Markdown syntax thoroughly saves time in every project that touches documentation, content, or developer tooling. This guide covers the core syntax you will use daily, along with extended features like tables and fenced code blocks that appear across most modern Markdown implementations. When you need to convert your Markdown into clean HTML for publishing, a Markdown to HTML converter handles the transformation instantly without installing any build tools.

Headings in Markdown use hash symbols at the start of a line. A single hash produces an h1, two hashes produce an h2, and so on through h6. Always include a space between the hash and the heading text -- most parsers require it, and omitting it is a common source of rendering failures. For document structure, start with a single h1 for the title and use h2 through h4 for sections and subsections. Skipping heading levels (jumping from h2 to h4) is valid Markdown but produces poor accessibility and document outline structure.

Emphasis uses asterisks or underscores. Single delimiters produce italic text, double delimiters produce bold, and triple delimiters produce bold italic. Asterisks are preferred over underscores because underscore-based emphasis fails inside words on most parsers -- writing foo_bar_baz will not italicize bar on GitHub or CommonMark-compliant renderers. Strikethrough text uses double tildes and is a GitHub Flavored Markdown extension that is widely but not universally supported.

Line breaks in Markdown are surprisingly tricky. A single newline between lines of text does not produce a line break in the rendered output -- the lines are joined into a single paragraph. To force a line break within a paragraph, end the line with two or more spaces (a trailing space break) or use a backslash before the newline. To start a new paragraph, leave a blank line between blocks of text. This distinction between line breaks and paragraph breaks trips up nearly every Markdown beginner and remains a common source of formatting surprises even for experienced users.

When you need to transform heading capitalization for consistency across a large document, a case converter can quickly standardize your heading text to title case, sentence case, or any other convention your style guide requires.

Unordered lists use a dash, asterisk, or plus sign followed by a space. Ordered lists use a number followed by a period and a space. A practical tip: in ordered lists, you do not need to number items sequentially. Many writers use 1. for every item so that reordering the list does not require renumbering. The Markdown parser assigns the correct numbers in the rendered output. Nested lists require consistent indentation -- typically two or four spaces, depending on the parser. Mixing indentation depths within a single list is the fastest way to produce mangled output.

Links use the format [link text](URL), and images use the same syntax with an exclamation mark prefix: . Reference-style links let you define URLs at the bottom of the document and reference them by label throughout the text, which keeps long URLs from cluttering your prose. For documentation that includes many links to the same resources, reference-style links dramatically improve readability of the raw Markdown source.

Code formatting comes in two forms: inline code and code blocks. Inline code uses single backticks to mark short code references within a sentence. Fenced code blocks use triple backticks on separate lines above and below the code, with an optional language identifier after the opening backticks for syntax highlighting. Always specify the language when your rendering platform supports highlighting -- it significantly improves readability for code documentation. Indented code blocks (four spaces of indentation) are an older syntax that still works but is less explicit about language and harder to distinguish from nested list content.

When preparing Markdown content for a CMS or static site, clean URL slugs matter. A slug generator creates URL-friendly strings from your heading text, ensuring consistent and readable permalinks across your published content.

Tables in Markdown use pipes and dashes to define columns and rows. The header row is separated from data rows by a line of dashes, and colons within that separator line control column alignment -- a colon on the left aligns left, on the right aligns right, and colons on both sides center the column. Tables must have a header row and at least one data row to render correctly. While the columns do not need to be visually aligned in the source text, aligning them with spaces makes the raw Markdown far more readable during code review.

Blockquotes use the greater-than symbol at the start of each line. They can contain any other Markdown elements including paragraphs, lists, and code blocks. Nested blockquotes use additional greater-than symbols. Blockquotes are commonly used in documentation to highlight important notes, in email-style replies to quote previous messages, and in articles to set off quotations from the body text.

Several extended features are widely supported but not part of the original specification. Task lists use a dash followed by brackets with a space for unchecked items or an x for checked items. Footnotes use a caret and label syntax to define notes that render at the bottom of the document. Definition lists, automatic URL linking, and emoji shortcodes are available on some platforms but not others. Before relying on extended syntax, verify that your target rendering platform supports it -- GitHub Flavored Markdown, CommonMark, and other implementations each have different extension sets.

Horizontal rules use three or more dashes, asterisks, or underscores on a line by themselves. They create a visual separator between sections and are useful in long documents where heading-level breaks feel too heavy. Be careful with dash-based horizontal rules immediately after a paragraph -- some parsers interpret them as Setext-style h2 headings rather than horizontal lines. Adding a blank line before the dashes eliminates this ambiguity.

Consistency within a project matters more than which specific style you choose. Pick one heading style (ATX with hashes is standard), one list marker (dashes are most common), and one emphasis delimiter (asterisks) and stick with them across all files. Many teams enforce this with a Markdown linter like markdownlint, which catches style inconsistencies, trailing whitespace, and structural issues before they reach code review. A linter configuration file at the root of your repository establishes team conventions without requiring a style guide that nobody reads.

When writing documentation, structure your files for scanning rather than sequential reading. Lead each section with the most important information, use lists for steps and options, and keep paragraphs short. Readers of technical documentation are almost never reading top to bottom -- they are searching for a specific answer. Effective Markdown documentation respects that behavior with clear headings, prominent code examples, and information-dense opening paragraphs that help readers decide quickly whether a section contains what they need.

Version control and Markdown work well together, but long lines create noisy diffs. Consider using semantic line breaks -- starting a new line at each sentence boundary or natural clause break. The rendered output is identical (single newlines are ignored), but diffs show exactly which sentence changed rather than flagging an entire paragraph. This practice is especially valuable for collaborative documentation where multiple contributors edit the same files and review each other's changes through pull requests.

For projects that accept Markdown content but publish in HTML, previewing the rendered output before committing is essential. Minor syntax errors -- a missing blank line before a list, an unclosed backtick, a malformed link -- produce subtle rendering bugs that are easy to miss in the raw source. Converting your Markdown to HTML locally and inspecting the output catches these issues before they reach your readers.