What Markdown Is and Why You Need a Cheat Sheet

You type a few symbols into a plain text file, and minutes later it renders as a clean, structured web page. That is Markdown in action. Created in 2004 by John Gruber (with contributions from Aaron Swartz), Markdown is a lightweight markup language that converts simple plain text into valid HTML. No visual editor required, no proprietary format to worry about.

What Is Markdown and Why It Matters

The core idea behind Markdown is radical simplicity. A document should look readable before it ever gets rendered. Gruber put it this way:

A Markdown-formatted document should be publishable as-is, as plain text, without looking like it has been marked up with tags or formatting instructions.

That philosophy is why Markdown stuck around. It powers README files on GitHub, documentation wikis, blogging engines like Jekyll and Hugo, note-taking tools such as Obsidian and Notion, and even everyday communication on Discord, Reddit, and Stack Overflow. If you write anything on the internet, you have almost certainly encountered markdown语法 whether you realized it or not.

Because Markdown files are plain text, they work on any operating system, play nicely with Git version control, and remain accessible even if the app you used to create them disappears tomorrow. That platform independence is exactly why a reliable markup cheat sheet belongs in every writer's and developer's toolkit.

Who This Cheat Sheet Is For

This markdown cheatsheet is built for two audiences at once. If you are a beginner learning the syntax for the first time, each section explains not just the how but the why. If you are an experienced user tired of Googling the same table alignment trick every few weeks, this works as a markdown language cheat sheet you can bookmark and scan in seconds.

Think of it as a layered ref sheet: quick-reference tables for speed, plus context and platform notes for depth. Every section ahead covers syntax, real examples, common mistakes, and which platforms actually support each feature.

Headings, Paragraphs, and Horizontal Rules

Every well-structured document starts with a clear hierarchy. In Markdown, that hierarchy begins with headings, flows through paragraphs, and uses horizontal rules to visually separate distinct sections. Knowing the syntax is only half the story. Understanding when and why to use each element keeps your documents scannable and semantically correct.

Heading Levels H1 Through H6

You create a markdown header by placing one to six hash symbols (#) before your text. The number of hashes corresponds directly to the heading level. One hash gives you an H1, two give you an H2, and so on down to H6.

A markdown title using H1 should appear only once per document, just like a book has one title on its cover. H2 headings carve out the major chapters, and H3 headings break those chapters into digestible pieces. Skipping levels (jumping from H2 straight to H4) hurts both accessibility and SEO, so keep the hierarchy sequential.

One compatibility detail worth remembering: always place a space between the hash symbols and your heading text. Writing #Heading without a space may not render correctly in every processor. The Markdown Guide also recommends adding blank lines before and after headings to avoid rendering issues on certain platforms.

Paragraphs and Line Breaks

Paragraphs in Markdown require no special characters. Simply separate blocks of text with a blank line, and each block becomes its own <p> element. Where things get tricky is line breaks within a single paragraph.

Imagine you want two lines stacked together without starting a new paragraph. You have two reliable options:

• Trailing spaces: End the line with two or more spaces, then press return. The renderer inserts a <br> tag.

• HTML tag: Type <br> directly at the end of the line. This is the html for new line approach and works universally across processors.

Here are line break examples showing the difference:

The trailing-spaces method is invisible in most editors, which makes it easy to accidentally delete. Many teams prefer the explicit <br> tag or configure their linters to preserve markdown-specific trailing whitespace. If you use pre-commit hooks, tools like pre-commit-hooks support a --markdown-linebreak-ext argument that protects those intentional trailing spaces in .md files.

One important best practice: never indent paragraphs with tabs or spaces unless they are inside a list. Unexpected indentation can trigger a code block in some parsers.

Horizontal Rules and Separators

When you need a visual divider between sections, a markdown horizontal line does the job. Three or more hyphens (---), asterisks (***), or underscores (___) on their own line all produce the same <hr> HTML element. You can even add spaces between characters (- - -) or use more than three (------).

All three variants render identically, so the choice is stylistic. Hyphens are the most popular because they are less likely to be confused with bold or italic markers. Think of the html horizontal ruler equivalent: Markdown simply gives you a shorthand that compiles to <hr> without writing any HTML yourself.

The one mistake that catches nearly everyone at least once: forgetting to leave a blank line before ---. Without that blank line, the parser interprets the dashes as a Setext-style H2 underline instead of a horizontal rule. Your paragraph suddenly becomes a heading, and the divider vanishes.

Platform support is nearly universal. GitHub, Obsidian, Notion, and VS Code all render horizontal rules correctly. Discord is the notable exception, displaying --- as literal dashes rather than a divider.

With headings giving your document structure, paragraphs and line breaks controlling flow, and horizontal rules providing visual breathing room, you have the foundational skeleton of any Markdown file. The next layer to master is how you style the text itself: bold, italic, strikethrough, and the formatting combinations that bring your content to life.

Text Formatting and Inline Styles

Structure gets your document organized, but inline formatting is what gives individual words and phrases their weight. Bold draws the eye to critical terms, italics add emphasis or mark titles, and strikethrough signals outdated information. Knowing how to apply these styles in Markdown is straightforward. Knowing how to combine them without breaking your syntax is where most people stumble.

Bold, Italic, and Strikethrough

Bold and italics in markdown rely on asterisks or underscores wrapped around your text. A single wrapper produces italic, a double wrapper produces bold, and a triple wrapper gives you both at once. Strikethrough uses tildes instead.

A practical tip: prefer asterisks over underscores for italics markdown and bold. Underscores can behave unpredictably inside compound words like file_name_here, where some parsers interpret them as formatting markers. Asterisks never have this problem because they are not valid word characters.

Strikethrough (~~text~~) is worth a special note. It is part of GitHub Flavored Markdown (GFM) and not included in John Gruber's original specification. If you are writing for a platform that only supports basic CommonMark, your tildes will render as literal characters. GitHub, GitLab, Reddit, Discord, and Obsidian all support it. Standard CommonMark parsers do not.

Underline Workarounds and Highlight Syntax

When you search for underline markdown options, you will quickly discover that Markdown has no native underline syntax. This is intentional. On the web, underlined text is strongly associated with hyperlinks, so underlining regular text creates confusion for readers. Still, certain contexts like academic papers or formal reports call for underlined words.

The workaround is to drop into raw HTML. If your Markdown processor supports inline HTML (most do), you can use the <ins> tag as a text underliner:

• <ins>underlined text</ins> renders as underlined text

• This works on GitHub, GitLab, and most static site generators.

• Discord and Reddit do not support inline HTML, so underline in markdown is simply not possible on those platforms.

The html code for italics equivalent here is the <em> tag, which produces the same result as wrapping text in single asterisks. You rarely need to write <em> manually since Markdown's native syntax is shorter, but knowing the HTML equivalent helps when debugging rendering issues or working inside table cells where Markdown formatting sometimes breaks.

For markdown highlight syntax, the double equals sign (==text==) works in Obsidian and a handful of other processors. On platforms that do not support it, the <mark> HTML tag achieves the same yellow-highlight effect. GitHub does not render either option, so highlighted text is best reserved for personal knowledge bases rather than shared repositories.

Combining Multiple Formatting Styles

Real documents rarely use a single style in isolation. You might need a bold word inside an italic phrase, or an italic label inside a hyperlink. Markdown handles nesting well as long as you keep your delimiters balanced.

Here are the most common combinations:

• Bold inside italic: *This is italic and **this word** is also bold*

• Italic inside bold: **This is bold and _this word_ is italic**

• Italic inside a link: [*italic link text*](https://example.com)

• Bold link: [**bold link text**](https://example.com)

• Inline code inside bold: **Run the build command**

• Strikethrough with bold: ~~**removed bold text**~~

The key rule is to nest different delimiter types. Mixing asterisks for the outer layer and underscores for the inner layer (or vice versa) keeps the parser from getting confused about where each style starts and ends. For example, **This _works_ perfectly** is cleaner than trying to use all asterisks for both layers.

One edge case that trips people up: you cannot apply formatting inside inline code spans. Anything between backticks is rendered literally. Writing **not bold** displays the asterisks as plain characters, not bold text. If you need styled code, you will have to use HTML tags like <code><strong>text</strong></code> instead.

With single-element and combined formatting covered, the next logical step is structuring content into ordered sequences, checklists, and quoted passages, where indentation rules and nesting behavior introduce a new set of challenges.

Lists, Task Lists, and Blockquotes

Formatted text gives words their visual weight, but content rarely exists as standalone sentences. Most real writing involves sequences, grouped items, and referenced material. Markdown lists let you organize information into scannable structures, while blockquotes let you set apart quoted or highlighted passages. The syntax looks simple on the surface, yet indentation rules and nesting behavior are where most formatting headaches begin.

Ordered and Unordered Lists

Unordered markdown lists use a dash (-), asterisk (*), or plus sign (+) followed by a space before each item. All three produce identical HTML output, so the choice is purely stylistic. The important rule: pick one delimiter and stick with it throughout a single list. Mixing them in the same list can cause rendering inconsistencies across processors.

• - Item one

• - Item two

• - Item three

For a markdown ordered list, prefix each item with a number followed by a period. Here is something that surprises many beginners: the actual numbers you type do not matter. Markdown always renders the list sequentially starting from whatever number you use first. You could write 1. 1. 1. for every item and the output would still display as 1, 2, 3. That said, using sequential numbers in your source makes the raw file easier to read and edit.

1. 1. First item

2. 2. Second item

3. 3. Third item

For compatibility, always use periods after numbers rather than parentheses. Writing 1) works in CommonMark but fails in several other processors, so 1. is the safer choice according to the Markdown Guide.

Nesting is where markdown bullet points gain real power. Indent a sub-item by two to four spaces (depending on the processor), and it becomes a child of the item above. You can nest unordered lists inside ordered lists and vice versa:

• Child

  • Grandchild| Three indentation levels, each with a bullet. Nested ordered |1. Parent 1. Child 1. Grandchild| Numbered sub-lists beneath each parent item. Mixed nesting |1. Step one

• Detail A

• Detail B

1. Step two` | Ordered steps with unordered sub-details. The critical detail: align the list marker of the child item directly below the first character of the parent item's text content. On GitHub, that typically means three spaces for items under a numbered list (to account for the digit, period, and space) and two spaces for items under a bullet list. Getting this alignment wrong is the single most common reason nested lists break.

Task Lists and Checkboxes

A markdown task list extends the basic unordered list with interactive checkboxes. The syntax adds brackets after the dash: - [ ] for an unchecked item and - [x] for a completed one.

• - [x] Write the introduction

• - [x] Draft the outline

• - [ ] Add code examples

• - [ ] Final review

On platforms that support them, these render as actual clickable checkboxes. You can toggle items directly in GitHub issues, pull requests, and rendered Markdown files without editing the source. GitLab, Obsidian, Notion, and most modern editors also support task lists.

The platform caveat is important: task lists are a GitHub Flavored Markdown extension. Standard CommonMark does not recognize the [ ] syntax, so your checkboxes will render as literal brackets on processors that only implement the base spec. Reddit and Stack Overflow do not support them either.

A few practical tips for task lists:

• If your item description starts with a parenthesis, escape it with a backslash: - [ ] \(Optional) Follow-up task

• Task lists can be nested just like regular lists. Indent four spaces to create sub-tasks beneath a parent task.

• On GitHub, task list progress is automatically summarized in issue and pull request lists, showing a fraction like "2/4" so you can track completion at a glance.

For project management workflows, task lists turn a simple Markdown file into a lightweight tracker. They are especially useful in README files, issue templates, and sprint planning documents where you need visible progress without switching to a separate tool.

Blockquotes and Nested Quotes

Quotation markdown uses the greater-than symbol (>) at the start of a line to create a blockquote. The rendered output appears as indented text with a vertical bar on the left, visually distinguishing it from the surrounding content.

A basic markdown quote looks like this:

• > This is a quoted paragraph.

For multi-paragraph blockquotes, place a > on the blank line between paragraphs to keep them inside the same markdown block quote container:

• > First paragraph of the quote.

• >

• > Second paragraph, still inside the same blockquote.

Nested blockquotes use double angle brackets. Each additional > adds another level of indentation, which is useful for representing threaded conversations or layered citations:

• > Original statement

• >

• >> Response to the original statement

Blockquotes can also contain other Markdown elements. You can place headings, lists, bold text, and even code blocks inside a quote markdown block. The Markdown Guide confirms that most formatted elements work within blockquotes, though not every processor handles every combination identically.

When should you use a blockquote versus a callout or admonition? The distinction matters:

GitHub's alert syntax (> [!NOTE], > [!TIP], > [!WARNING]) builds on the blockquote format but adds colored icons and distinct styling. These are sometimes called admonitions or callouts depending on the platform. Obsidian uses a similar but slightly different callout syntax. If you need cross-platform compatibility, a plain blockquote with bold lead-in text is the safest approach.

One best practice that applies to all blockquotes: always place a blank line before and after the quoted block. Without those blank lines, some processors will merge the blockquote into the surrounding paragraph or fail to render the vertical bar correctly.

Definition lists deserve a brief mention here as well. Some extended processors (MultiMarkdown, PHP Markdown Extra) support them with this syntax:

• Term

• : Definition of the term

These render as <dl>, <dt>, and <dd> HTML elements. GitHub does not support definition lists natively, so they are best reserved for documentation systems that explicitly enable them.

Lists and blockquotes handle the structural side of content organization. The next challenge is embedding richer elements: hyperlinks, images, code blocks, tables, and diagrams that turn a plain document into a fully functional reference.

Links, Code Blocks, Tables, and Diagrams

Structured text and formatted lists carry your ideas, but most documents need to point readers somewhere else, display source code, or present data in rows and columns. Markdown handles all of these with concise syntax that stays readable in its raw form. This section covers the markdown link syntax for every hyperlink type, the rules for embedding code, the pipe-based table format, and a powerful feature most cheat sheets skip entirely: Mermaid diagrams.

Links, Images, and Hyperlink Syntax

Markdown gives you several ways to create clickable links. The most common is the inline link, where you wrap the visible text in square brackets and the URL in parentheses immediately after. You can also add an optional title that appears on hover:

• Inline link: [Link Text](https://example.com)

• Inline link with title: [Link Text](https://example.com "Hover title")

Reference-style links separate the URL from the text, which keeps long paragraphs clean. You define a label anywhere in the document and reference it inline:

• Reference in text: [Link Text][label]

• Definition elsewhere: [label]: https://example.com "Optional title"

This approach shines in documents with many repeated URLs. Change the URL in one place and every reference updates automatically.

For images, the syntax mirrors links but starts with an exclamation mark. The text inside the brackets becomes the alt attribute, which is critical for accessibility:

• Image: ![Alt text](image-url.png)

• Image with title: ![Alt text](image-url.png "Image title")

Want a clickable image that links somewhere? Nest the image syntax inside a link. This is the Markdown equivalent of a hyperlink image html pattern:

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

Many processors also support autolinks. Simply paste a bare URL like https://example.com and platforms such as GitHub will automatically convert it into a clickable hyperlink without any bracket syntax.

One detail that catches people off guard: if your URL contains parentheses (common in Wikipedia links), you need to encode them as %28 and %29 or wrap the entire URL in angle brackets. Otherwise the parser misreads where the URL ends.

Inline Code and Fenced Code Blocks

Displaying code in Markdown ranges from a single command mentioned mid-sentence to multi-line markdown code blocks with full syntax highlighting. The backtick key on your keyboard is the gateway to all of it.

For inline code, wrap the text in single backticks. This renders the content in a monospace font and prevents any Markdown formatting inside from being processed:

• git status renders as git status

If your code md snippet itself contains a backtick, use double backticks as the delimiter: backtick. The parser uses the outer pair and treats the inner backtick as literal text.

For multi-line code segments, you have two options:

• Fenced Code Blocks : Wrap your code with triple backticks (```) on the lines immediately preceding and following the block. You can append an optional language identifier (like js, python, or html) to the opening backticks to enable syntax highlighting.

`\\javascript`

const greeting = "Hello, World!";

console.log(greeting);

\\`\`

• Indented Code Blocks : Indent every line of the block by at least four spaces or one tab. This is the traditional CommonMark approach but does not support syntax highlighting or language specifications.

One of the most powerful extensions supported by GitHub, GitLab, and Obsidian is Mermaid diagrams. By specifying mermaid as the language identifier for a fenced code block, you can render flowcharts, sequence diagrams, and Gantt charts directly from plain text:

`\\mermaid`

graph TD;

  A[Start] --> B(Process);

  B --> C{Decision};

  C -- Yes --> D[Result 1];

  C -- No --> E[Result 2];

\\`\`

This raw text compiles into a fully rendered, interactive vector diagram on compatible platforms, allowing you to manage documentation and technical architecture in the same plain-text file.

Markdown Flavors and Platform Compatibility

You have learned the syntax for headings, lists, links, and code blocks. But here is the frustrating reality: writing valid Markdown does not guarantee it renders the same everywhere. A table that looks perfect on GitHub might display as raw pipes on Reddit. A footnote that works in Obsidian disappears entirely on Discord. The reason is that "Markdown" is not a single language. It is a family of flavors, each extending the original specification in different directions.

Understanding which flavor powers which platform saves you from writing syntax that silently fails. This section maps the landscape so you can write with confidence regardless of where your content ends up.

CommonMark vs GitHub Flavored Markdown vs MDX

The original Markdown spec from John Gruber left many edge cases undefined. Different parsers interpreted ambiguous situations differently, which led to fragmentation. CommonMark emerged as an effort to create a strict, unambiguous standard. It covers the basics thoroughly: headings, paragraphs, links, images, emphasis, blockquotes, lists, code blocks, and horizontal rules. Nothing more.

GitHub Flavored Markdown (GFM) builds on CommonMark and adds features that developers need daily. If you have ever wondered about the GFM meaning, it is simply GitHub's extended superset of CommonMark. GFM introduces tables, task lists, strikethrough, autolinked URLs, and syntax highlighting in fenced code blocks. Since GitHub is where millions of README files and documentation pages live, GFM has become the de facto standard for developer-facing Markdown.

MultiMarkdown takes a different path. It targets academic and technical writers who need footnotes, citations, definition lists, metadata headers, cross-references, and even table captions. It is highly extensible but less widely supported outside dedicated writing tools.

MDX is the newest entrant and the most radical departure. It lets you embed JSX components directly inside Markdown files, making it popular for documentation sites built with React or Next.js. If you need interactive elements, live code playgrounds, or custom UI components inside your docs, MDX is the flavor that enables it. The tradeoff is that MDX files are not portable to standard Markdown renderers.

Obsidian Flavored Markdown deserves its own mention. It supports CommonMark and GFM as a base, then layers on wiki-style internal links ([[Link]]), block references, callouts (> [!NOTE]), and highlights (==text==). These extensions make obsidian markdown powerful for personal knowledge management but mean your notes may not render correctly if exported to other platforms without conversion.

Platform Compatibility Reference

The table below maps common syntax elements to the platforms where they actually work. This is the reference that most cheat sheets leave out, and it is the one you will reach for every time you write Markdown for a new audience.

A few platform-specific notes worth keeping in mind:

• Reddit: Uses a simplified Markdown flavor. Markdown reddit posts support bold, italic, strikethrough, links, lists, blockquotes, inline code, code blocks, and tables. They do not support task lists, footnotes, or HTML tags. Reddit's new editor also has a rich-text mode that generates Markdown behind the scenes.

• Discord: Supports basic formatting (bold, italic, strikethrough, spoiler tags), inline code, code blocks with syntax highlighting, blockquotes, and masked links. Discord message formatting does not include tables, images via Markdown syntax, task lists, or headings.

• Stack Overflow: Uses CommonMark with a few additions like spoiler blocks (>!). No task lists, no footnotes, no tables via pipe syntax (though HTML tables work).

• Notion: Supports Markdown shortcuts for formatting as you type (headings, bold, italic, code, lists) but stores content in its own block-based format. Pasting Markdown into Notion converts it, but exporting from Notion produces Markdown with some fidelity loss.

Comments, Footnotes, and Extended Syntax

Sometimes you need text in your source file that should never appear in the rendered output. Markdown comments serve this purpose. The standard approach borrows HTML comment syntax:

• <!-- This is a comment in markdown that will not render -->

This works on any platform that processes HTML, including GitHub, GitLab, and most static site generators. The comment is invisible in the rendered page but remains visible in the raw source. Obsidian offers an alternative syntax for markdown comments using double percent signs: %%This is an Obsidian-only comment%%. This variant is faster to type but will not work outside Obsidian.

When should you use comments in markdown? Common use cases include:

• Leaving notes for collaborators about why a section is structured a certain way

• Temporarily hiding content without deleting it

• Adding TODO reminders that should not appear in published documentation

• Storing metadata or instructions for build tools that process the file

Footnotes let you add references or tangential information without interrupting the main text. The syntax uses a caret inside brackets for the reference marker and a matching definition elsewhere in the document:

• Reference in text: This claim needs a source.[^1]

• Definition: [^1]: Source title, author, year.

The rendered output places a superscript number in the text that links to the footnote content at the bottom of the page. You can use words as identifiers too ([^note]), and the footnote definitions do not need to appear at the end of the file. The processor collects and numbers them automatically.

Footnote support varies significantly. According to parser comparison data, GitLab Flavored Markdown, Markdown Extra, and MultiMarkdown all support footnotes natively. GitHub added footnote support more recently. Standard CommonMark and Discord do not support them at all.

Other extended features worth knowing about:

• Abbreviations: Define an abbreviation once (*[HTML]: Hyper Text Markup Language) and every instance of that term in the document gets a tooltip. Supported in Markdown Extra and PHP-based processors.

• Subscript and superscript: H~2~O for subscript and X^2^ for superscript. Supported in MultiMarkdown and some extended processors, but not in GFM or CommonMark.

• Custom heading IDs: ### My Heading {#custom-id} lets you control the anchor slug for deep linking. Supported in Markdown Extra, MultiMarkdown, and some static site generators.

The practical takeaway: before using any extended syntax, check whether your target platform supports it. Writing a document full of footnotes and definition lists only to discover your publishing platform ignores them is a frustrating experience. When in doubt, stick to the GFM feature set. It covers the widest range of real-world platforms while still offering tables, task lists, and strikethrough beyond the CommonMark baseline.

Knowing which syntax works where is half the battle. The other half is avoiding the subtle formatting mistakes that cause perfectly valid-looking Markdown to break in unexpected ways.

Common Markdown Mistakes and How to Fix Them

Syntax that looks correct in your editor can still break in the rendered output. These failures are rarely obvious. A list collapses into a single paragraph, a table displays as raw pipes, or a link swallows half your sentence. The fixes are almost always small, but finding the root cause without guidance means staring at identical-looking lines wondering what went wrong.

Below are the most common pitfalls grouped by category, each paired with the specific fix that resolves it.

Indentation and Whitespace Pitfalls

Whitespace is functional syntax in Markdown. A single misplaced space or inconsistent markdown indent can change how an entire block renders. These are the mistakes that trip people up most often:

• Missing blank lines around blocks: Headings, lists, and code blocks need an empty line before and after them. Without that gap, many processors merge them into the preceding paragraph. This is the most common mistake in written Markdown.

• Inconsistent nested list indentation: A sub-item must align with the first character of the parent item's text content. On most processors, that means two spaces under a bullet list and three spaces under a numbered list. Mixing markdown tab characters with spaces makes alignment unpredictable because tab width varies across editors. Always use spaces for markdown tabulation in nested lists.

• Trailing whitespace causing unintended line breaks: Two spaces at the end of a line insert a <br>. If your editor auto-trims trailing spaces, your intentional line breaks vanish. If it does not, accidental spaces create breaks where you did not want them.

• No space after heading hash: Writing #Heading without a space between the # and the text causes some renderers to treat the line as a plain paragraph rather than a heading.

The fix for all of these is consistent formatting habits: use spaces instead of tabs, always leave one blank line between blocks (never more than one), and configure your editor to visualize whitespace characters so nothing hides from you.

Broken Links and Escaped Characters

Links and special characters introduce a second category of silent failures. Your markdown note might look fine in the source, but the rendered output tells a different story:

• Parentheses in URLs: Links to Wikipedia or other sites with parentheses in the path break the parser. [Link](https://en.wikipedia.org/wiki/Markdown_(language)) fails because the parser reads the first closing parenthesis as the end of the URL. Fix it by encoding as %28 and %29, or wrap the URL in angle brackets: [Link](<https://en.wikipedia.org/wiki/Markdown_(language)>).

• Tables missing the header separator: A table requires a delimiter row of hyphens between the header and data rows. Omit it and the entire table renders as plain text with visible pipes. Every table needs at least | --- | --- | on the second line.

• Unescaped special characters: Characters like *, _, [, #, and \ have syntactic meaning. If you want them displayed literally, prefix them with a backslash: \*not italic\*.

• Nested formatting conflicts: Trying to bold text inside an already-italicized block using the same delimiter type confuses the parser. Use asterisks for one layer and underscores for the other: *italic and **bold** inside* works, but mixing identical delimiters at both levels does not.

A quick markdown warning to remember: if a link, image, or formatted span looks correct but renders broken, check for unescaped special characters first. Nine times out of ten, that is the culprit.

Linting Tools and Team Style Guides

Catching these mistakes manually is tedious, especially across a team where everyone has slightly different habits. Automated linting solves this at scale.

markdownlint is the most widely adopted tool. It checks for over 50 rules covering everything discussed above: blank lines around blocks, consistent heading styles, proper list indentation, trailing whitespace, and line length limits. You can run it as a CLI tool, a VS Code extension, or a pre-commit hook that blocks improperly formatted files from entering your repository.

For team-wide consistency, pair markdownlint with an .editorconfig file in your project root. EditorConfig standardizes settings like indent size, tab-vs-spaces, trailing newline behavior, and line endings across every editor your team uses. A minimal configuration for Markdown files looks like this:

Microsoft's own documentation style guide enforces a 100-character line limit for exactly this reason: shorter lines produce cleaner diffs and make it easier for multiple contributors to work on the same file without merge conflicts.

A few additional style conventions worth adopting as a team:

• Use ATX-style headings (#) exclusively. Never mix with Setext-style underlines.

• Always specify a language identifier on fenced code blocks, even if it is just text.

• Use hyphens (-) for unordered lists rather than asterisks, to avoid visual confusion with emphasis markers.

• Keep one markdown note per concept. If a list item grows beyond two sentences, promote it to its own subsection with a heading.

With linting catching formatting errors before they reach production and a shared style guide eliminating ambiguity, your team's Markdown stays consistent regardless of who writes it. The remaining question is how to put all of this syntax knowledge to work in real projects, from README files and API docs to full knowledge bases built on structured writing.

Markdown for Every Workflow

Knowing the syntax is one thing. Knowing where to apply it is what turns a cheat sheet into a daily advantage. Markdown shows up in nearly every stage of a modern workflow, from the first draft of a readme file to a published knowledge base that an entire team relies on. The syntax elements you choose depend on the job at hand.

Markdown for Documentation and README Files

A readme file is often the first thing a developer sees when they land on a repository. Good github formatting readme practices make the difference between a project that gets adopted and one that gets skipped. README-style documentation works best when it focuses on user workflows rather than isolated feature descriptions. As Bump.sh's documentation guide explains, workflow-driven docs that chain operations into practical scenarios reduce the learning curve and improve adoption.

Here are the syntax elements that matter most for documentation:

1. README files and API docs: H1 for the project name, H2 for sections (Installation, Usage, API Reference), task lists for setup steps, fenced code blocks with language identifiers for examples, and tables for configuration options or endpoint summaries.

2. Blogging with static site generators: YAML front matter for metadata, headings for article structure, images with descriptive alt text, and horizontal rules to separate thematic sections. Jekyll, Hugo, and Astro all consume standard Markdown files directly.

3. Academic writing: Footnotes for markdown citation references, LaTeX equations for formulas, cross-references for figures and sections, and definition lists for terminology. Tools like RStudio's visual editor support Pandoc-powered features including equations, embedded code chunks, and citation management. If you work in R, keeping an rmarkdown cheat sheet (sometimes called an rmd cheat sheet) nearby speeds up report generation considerably.

For academic contexts where you need to markdown cite sources inline, the footnote syntax ([^1]) paired with a bibliography tool like Pandoc's citeproc handles most needs. This workflow lets you write in plain text while producing properly formatted citations in the final output.

Project Management and Team Collaboration

Markdown turns lightweight text files into functional project trackers. Task lists in GitHub issues let teams track progress without leaving the repository. Sprint planning documents use nested checkboxes for epics and sub-tasks. Pull request templates combine headings, lists, and code blocks to standardize how changes are described and reviewed.

The syntax that drives project workflows:

1. Issue templates: Task lists for acceptance criteria, blockquotes for context from stakeholders, and inline code for referencing specific functions or commands.

2. Meeting notes: H2 headings for agenda items, unordered lists for discussion points, and task lists for action items assigned to team members.

3. Interactive documentation sites: MDX enables embedding react js markdown components directly inside docs, powering live code playgrounds and interactive API explorers on platforms built with Next.js or Docusaurus.

From Notes to Knowledge Base Pages

The real power of Markdown emerges when quick notes evolve into structured, shareable documentation. You start with a rough draft in plain text, add headings for organization, insert links to related pages, and suddenly you have the skeleton of a knowledge base. The challenge is that plain Markdown files alone lack the collaboration layer, visual richness, and template systems that teams need at scale.

This is where workspaces like AFFiNE's Page Docs bridge the gap. You get Markdown-style writing as the foundation, but with rich blocks, embedded tables, PDF previews, media, and templates layered on top. For readers who have worked through this cheat sheet and want to turn that knowledge into organized, shareable documentation, Page Docs offers a natural next step: structured writing and real-time collaboration without being limited to plain text files.

The progression looks like this: learn the syntax, practice it in a focused editor, then move into a workspace that lets you combine Markdown fluency with the visual and collaborative features a team actually needs. That final step is where syntax knowledge becomes a lasting productivity habit rather than a skill you exercise only when editing config files.

Quick Reference Card and Recommended Tools

Every section above covered syntax in depth, with context, platform notes, and edge cases. Sometimes you just need the answer in three seconds flat. This condensed md cheatsheet puts every essential element in one scannable table, followed by the keyboard shortcuts and tools that make writing Markdown feel effortless.

Essential Syntax At a Glance

Bookmark this table. It covers the elements you will reach for in 90% of your writing, organized by category so you can jump straight to what you need. Consider it your markdown syntax cheat sheet in its most compact form.

Editor Shortcuts and Productivity Tips

Most Markdown editors share a few useful shortcuts: Ctrl+B or Cmd+B for bold, Ctrl+I or Cmd+I for italic, and backticks for inline code. In VS Code, install Markdown All in One for table of contents generation, list continuation, and preview shortcuts. In Obsidian, use backlinks and graph view to turn notes into a connected knowledge base.

If you want a printable markdown cheat sheet pdf, export this section from your editor or save the rendered page as PDF. For interactive practice, use CommonMark's tutorial, GitHub's preview, or a Markdown-aware workspace where you can see source and rendered output side by side.

• AFFiNE Page Docs. A structured workspace for applying this markdown guide cheat sheet with rich blocks, PDF previews, templates, and collaborative knowledge-base pages.

• VS Code. Best for docs-as-code workflows, Git-based editing, and extension-driven Markdown previews.

• Obsidian. Best for personal knowledge management and linked Markdown notes.

• markdownlint. Best for enforcing consistent style rules across a team.

Use this mark down cheat sheet as a quick reference when you forget syntax, but rely on preview, linting, and platform-specific documentation when publishing. Markdown is simple, but the exact rendering rules still depend on where your content will live.

Markdown Cheat Sheet FAQs

1. What is the difference between CommonMark and GitHub Flavored Markdown?

CommonMark is a strict, unambiguous base specification covering headings, paragraphs, links, images, emphasis, blockquotes, lists, code blocks, and horizontal rules. GitHub Flavored Markdown (GFM) builds on CommonMark by adding tables, task lists, strikethrough, autolinked URLs, and syntax highlighting in fenced code blocks. If you need features like checkboxes or pipe-based tables, you are using GFM extensions that standard CommonMark processors will not recognize.

2. How do you create a line break in Markdown without starting a new paragraph?

You have two reliable methods. First, end the line with two or more trailing spaces before pressing return, which inserts atag. Second, type the HTMLtag directly at the end of the line. The trailing-spaces method is invisible in most editors and easy to accidentally delete, so many teams prefer the explicit HTML tag or configure their linters to preserve markdown-specific trailing whitespace.

3. Why does my Markdown table not render correctly?

The most common cause is a missing header separator row. Every Markdown table requires a delimiter row of hyphens (like | --- | --- |) between the header row and the data rows. Without it, the entire table displays as plain text with visible pipe characters. Also ensure you are on a platform that supports tables, as basic CommonMark and some platforms like Stack Overflow do not render pipe-based tables natively.

4. Can you underline text in Markdown?

Markdown has no native underline syntax by design, since underlined text on the web is strongly associated with hyperlinks. The workaround is using the HTML tag: underlined text. This works on GitHub, GitLab, and most static site generators. However, platforms like Discord and Reddit do not support inline HTML, making underline impossible there. For structured documentation that goes beyond plain-text limitations, tools like AFFiNE's Page Docs let you apply rich formatting including underlines within a Markdown-style workspace.

5. What tools can help enforce consistent Markdown formatting across a team?

The most widely adopted tool is markdownlint, which checks over 50 rules covering blank lines around blocks, consistent heading styles, proper list indentation, trailing whitespace, and line length. Pair it with an .editorconfig file to standardize indent size, tab-vs-spaces, and trailing newline behavior across every editor your team uses. You can run markdownlint as a CLI tool, a VS Code extension, or a pre-commit hook that blocks improperly formatted files from entering your repository.

Related Blog Posts

1. What Is a Template? Types, Uses & 2026 Examples - AFFiNE