Markdown Cheat Sheet

Headings and Paragraphs

Build the basic structure of a Markdown document.

Headings

Create ATX or Setext headings.

markdown

# Heading 1
## Heading 2
### Heading 3

📌 Add a space after each # marker

💡 Use one level-one heading per document

🔍 Setext syntax supports only levels one and two

🎯 Do not skip heading levels for visual sizing

headingsstructureatxsetext

Paragraphs and Line Breaks

Separate paragraphs and control hard line breaks.

markdown

First paragraph.

Second paragraph.

📌 A blank line starts a new paragraph

🔍 A normal newline is usually rendered as a space

⚡ Two trailing spaces create a hard line break

🎯 Prefer paragraphs over frequent manual breaks

paragraphsline-breakswhitespace

Emphasis and Text

Emphasize text and use GitHub text extensions.

Italic, Bold, and Combined

Add emphasis with asterisks or underscores.

markdown

*italic*
**bold**
***bold italic***

💡 Asterisks are less ambiguous inside words

📌 Match opening and closing delimiter counts

🎯 Use emphasis for meaning, not decoration

🔍 Delimiter behavior follows surrounding punctuation

emphasisitalicbold

Strikethrough

Mark deleted text with the GFM strikethrough extension.

markdown

~~removed text~~

📌 Strikethrough is a GFM extension

🔍 CommonMark alone does not define this syntax

💡 Use it to show revisions without hiding context

⚠️ Confirm support outside GitHub-style renderers

strikethroughgfmtext

Lists and Tasks

Create ordered, unordered, nested, and task lists.

Unordered and Ordered Lists

Create bullet and numbered lists.

markdown

- First item
- Second item
- Third item

1. First step
2. Second step

📌 Include a space after the list marker

💡 Use 1. repeatedly when automatic renumbering helps

🔍 Lists can contain paragraphs and other blocks

🎯 Keep marker style consistent within a list

listsordered-listunordered-list

Nested Lists and Task Lists

Nest list content and create GFM checkboxes.

markdown

- Parent
  - Child
    - Grandchild

📌 Indent child items beneath the parent content

🔍 Task lists are a GFM extension

⚡ Use lowercase x to mark a completed task

🎯 Keep project tracking out of permanent reference docs

nested-liststask-listsgfm

Links

Link inline, reuse destinations, and create autolinks.

Inline Links

Add link text, a destination, and an optional title.

markdown

[DevSheets](https://devsheets.io)

📌 Put descriptive text inside square brackets

🔍 Titles appear as optional hover text

💡 Angle brackets create explicit autolinks

🎯 Avoid vague link text such as click here

linksanchorsautolinks

Reference Links

Reuse a destination without repeating the URL.

markdown

Read the [CommonMark spec][spec].

[spec]: https://spec.commonmark.org/

💡 Reference labels are case-insensitive

📌 Definitions do not render as visible content

⚡ Reuse one definition for repeated destinations

🎯 Place definitions near the section or document end

reference-linkslinksdefinitions

Images

Embed images with useful alternative text.

Inline and Reference Images

Embed an image with an optional title.

markdown

![DevSheets logo](/images/logo.png)

📌 Describe the image purpose in the alt text

🔍 Image syntax adds ! before normal link syntax

💡 Relative paths keep repository images portable

⚠️ Do not put essential information only in an image

imagesaccessibilityalt-text

Code

Format inline code and multi-line code blocks.

Inline Code

Mark commands, filenames, and identifiers inline.

markdown

Run `npm install` first.

📌 Backticks preserve spaces inside code spans

💡 Use multiple backticks around literal backticks

🎯 Reserve inline code for exact technical values

🔍 Code spans do not parse other Markdown formatting

inline-codecode-spansbackticks

Fenced Code Blocks

Create multi-line code blocks with language hints.

markdown

~~~js
const message = 'Hello'
console.log(message)
~~~

📌 Put the language immediately after the opening fence

💡 Tilde fences help when documenting backtick fences

🔍 Syntax highlighting depends on the renderer

🎯 Prefer fenced blocks over four-space indentation

fenced-codesyntax-highlightingcode-blocks

Indented Code Blocks

Create a code block with four leading spaces.

markdown

const port = 3000
    startServer(port)

📌 Indent every code line by at least four spaces

🔍 Indented blocks cannot declare a language hint

⚠️ Indentation may be interpreted as list nesting

🎯 Use fenced blocks for most documentation

indented-codecode-blocksindentation

Quotes and Separators

Quote content and divide major sections.

Blockquotes

Quote one or more paragraphs and nested blocks.

markdown

> A quoted sentence.

📌 Prefix quoted lines with >

💡 Add > on blank lines for readable source

🔍 Blockquotes can contain other block elements

🎯 Use quotes only for content attributed elsewhere

blockquotesquotesnesting

Thematic Breaks

Insert a horizontal separator between sections.

markdown

---

📌 Use at least three matching markers

⚠️ A hyphen line can become a Setext heading

💡 Add blank lines around thematic breaks

🎯 Use separators sparingly in structured documents

thematic-breakshorizontal-rulesstructure

Tables

Present compact tabular data with the GFM table extension.

GFM Tables

Create a table and control column alignment.

markdown

| Name | Role |
| --- | --- |
| Ana | Developer |

📌 Tables are a GFM extension

🔍 Colons set left, center, or right alignment

💡 Outer pipe characters are optional

⚠️ Keep complex content out of table cells

tablesgfmalignment

Escaping and Entities

Display syntax characters literally.

Backslash Escapes and Entities

Escape punctuation or use an HTML entity.

markdown

\*not italic\*
\# not a heading

📌 Backslashes escape ASCII punctuation

🔍 Entity references are decoded before rendering

💡 Use code spans for longer literal syntax

⚠️ Backslashes do not escape arbitrary letters

escapingentitiespunctuation

HTML in Markdown

Use raw HTML when the renderer permits it.

Inline and Block HTML

Mix supported HTML with Markdown content.

markdown

Press <kbd>Ctrl</kbd> + <kbd>C</kbd>.

⚠️ Renderers may sanitize or remove raw HTML

📌 Markdown inside HTML blocks varies by context

💡 Use HTML only when Markdown cannot express the result

🎯 Test output on the actual publishing platform

htmlraw-htmldetails

GitHub Features

Use common GitHub-specific document features.

Footnotes

Add GitHub-supported footnote references and definitions.

markdown

A statement with a source.[^1]

[^1]: The supporting note.

📌 Footnotes are not part of core CommonMark

🔍 GitHub renders definitions at the document bottom

💡 Use meaningful labels in long source files

⚠️ Confirm support on non-GitHub renderers

footnotesgithubreferences

GitHub Alerts

Highlight important information in GitHub documents.

markdown

> [!NOTE]
> Helpful context for the reader.

📌 Alerts are a GitHub-specific extension

💡 Reserve alerts for genuinely notable information

🔍 The marker must begin the blockquote

⚠️ Other renderers may show a normal blockquote

alertsgithubcallouts

Document Patterns

Combine syntax into portable project documentation.

README Structure

Organize a concise project README.

markdown

# Project Name

One-sentence project description.

## Installation

## Usage

🎯 Lead with the project outcome

📌 Keep installation steps copyable and current

💡 Add sections only when the project needs them

🔍 Preview the file in its target renderer

readmedocumentationstructure

Portable Markdown Checklist

Choose syntax that works across common renderers.

markdown

# Use core syntax first

- Headings
- Lists
- Links
- Fenced code

📌 CommonMark is the safest syntax baseline

🔍 GFM adds tables, tasks, and strikethrough

⚠️ Soft line break rendering can differ

🎯 Test the destination instead of assuming parity

portabilitycommonmarkgfm

Markdown

Table of Contents

Headings and Paragraphs

Emphasis and Text

Lists and Tasks

Links

Images

Code

Quotes and Separators

Tables

Escaping and Entities

HTML in Markdown

GitHub Features

Document Patterns