DriversRecommendedOutdated drivers can make a good PC feel brokenScan driver issues before chasing fixes manually.Scan NowOctober DealsAmazon USOctober deal check: compare before you payAmazon US: current deals, useful picks and tech finds.Check DealsWindows FixRecommendedWindows errors stealing your time? Find the fix fastScan stability, cleanup and performance issues.Fix Now×
Skip to content
World desk4 min

Common Markdown Syntax: A Practical Guide

A practical CommonMark guide to headings, emphasis, lists, quotes, links, images, and code, plus the key differences between CommonMark and GitHub Flavored Markdown.
Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Markdown turns plain text into structured documents with a small set of punctuation conventions. For headings, emphasis, lists, quotes, links, images, and code, the examples below use CommonMark—the clearest shared baseline. Tables, task lists, and strikethrough are extensions, so check which Markdown dialect your destination supports before relying on them.

What is Markdown?

Markdown is plain text written with punctuation that signals structure or formatting. Its design aims to keep the source readable even before a renderer turns it into formatted output. The syntax originated with John Gruber, with help from Aaron Swartz, and is now implemented in multiple dialects.

As an Amazon Associate I earn from qualifying purchases.

This guide uses CommonMark as its baseline. The CommonMark quick reference shows the core forms, while the CommonMark specification defines how they are parsed. GitHub Flavored Markdown (GFM) is one example of a platform dialect, not a guarantee that every editor supports the same additions.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

How do I add headings and paragraphs?

ATX headings

Put one to six hash marks before the heading text. The number of marks sets the heading level:

# Main heading
## Section heading
### Subsection heading

A single blank line separates paragraphs. A line break in your source is not necessarily rendered as a visible line break, so use a new paragraph when you mean a new paragraph.

Setext headings

CommonMark also supports an underline on the line below the text. One or more equals signs make a level-one heading; hyphens make a level-two heading:

First-level heading
===================

Second-level heading
--------------------

How do I make text italic or bold?

Wrap text in one asterisk or underscore for emphasis, and two for strong emphasis:

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
*italic* or _italic_
**bold** or __bold__

Use the form that stays clearest beside surrounding punctuation. If a phrase contains markup-like punctuation or nested emphasis, preview it in the renderer where the document will appear.

How do I make a list?

Unordered lists

Start each item with a hyphen, asterisk, or plus sign. Keep the marker and spacing consistent for readability:

- First item
- Second item
- Third item

Ordered lists

Use a number followed by a period or a closing parenthesis. A period-form list looks like this:

1. First step
2. Second step
3. Third step

List parsing has rules that can differ from older Markdown implementations. Indentation affects whether material belongs to a list item or starts a new block, and changing ordered-list delimiters starts a separate list in CommonMark. For nested lists or list items containing paragraphs and code, check the target renderer’s preview.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

How do I quote text or add a divider?

Block quotes

Begin a quoted line with a greater-than sign. A block quote can contain multiple paragraphs and other block elements:

> This is a quoted paragraph.
>
> This is another paragraph in the same quote.

Thematic breaks

Put three or more hyphens or asterisks on a line by themselves to create a thematic break:

---

***

How do I write a link or image?

Links

Use square brackets for the visible label and parentheses for the destination:

[CommonMark](https://commonmark.org/)

CommonMark also supports reference-style links, which can keep long destinations separate from the sentence where a link appears. The quick reference demonstrates that form.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Images

Put an exclamation mark before the link syntax. The bracketed text is alternative text describing the image when it cannot be seen or loaded:

![A short description of the image](https://example.com/image.png)

Use meaningful alternative text rather than repeating a filename; it gives readers context when the image is unavailable and helps assistive technology convey its purpose.

How do I format code?

Inline code

Wrap a short code fragment in backticks to display it as code rather than ordinary text:

Run `npm install` before starting the app.

Multiline code blocks

Surround a block with a matching fence of at least three backticks or tildes. Fences are convenient because the code can retain its indentation:

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
```text
First line
Second line
```

CommonMark also treats a block indented by four spaces as code. Use fenced blocks when they make the boundary of an example easier to see.

Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Does Markdown support tables, task lists, and strikethrough?

Not in CommonMark’s core syntax. GFM adds tables, task-list items, strikethrough, and other extensions. Its specification, version 0.29-gfm dated 2019-04-06, describes GFM as a strict superset of CommonMark. A table written for GFM may therefore remain unformatted in a CommonMark-only renderer.

GitHub also post-processes and sanitizes the HTML produced from GFM. Consequently, even support for a Markdown construct does not mean every renderer will handle raw HTML or generated output identically. For portable documents, stick to the CommonMark forms above unless you know the destination accepts a particular extension.

Why does my Markdown look different on GitHub or another app?

“Markdown” names a family of implementations, not one universal feature set. CommonMark formalizes core parsing rules; GFM builds on that baseline with extensions, and GitHub applies additional processing to the rendered result. Other apps may choose different extensions or parsing behaviors.

Free tools Windows power users keep installed

One-click scans. No signup required.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Differences can show up in punctuation escaping, line breaks, link titles, HTML, block quotes, list indentation, ordered-list markers, starting numbers, and fenced code blocks. If a nested list or other complex structure matters, preview it in the destination where it will be published. When the same source must work in several places, prefer CommonMark’s core syntax and avoid destination-specific extensions.

Quick reference: common Markdown syntax

Purpose CommonMark form
Heading # Heading or ## Heading
Italic *italic* or _italic_
Bold **bold** or __bold__
Unordered list - Item
Ordered list 1. Item
Block quote > Quoted text
Link [Label](https://example.com)
Image ![Alt text](image-url)
Inline code `code`
Fenced code block Three or more matching backticks or tildes around the block
Thematic break --- or ***
Table, task list, strikethrough GFM extensions; not CommonMark core syntax

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.

Leave a Reply

Your email address will not be published. Required fields are marked *

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

More from the Wire

  1. World desk4 min
    How to Spot an AI Voice Scam Before Sending MoneyDon’t rely on how a caller sounds. Pause, call back through a known number, and verify the emergency with another trusted person before sending money.
  2. Mountain View desk4 min
    Google’s SynthID Detector: How to Check AI-Generated Images, Video and AudioGoogle’s SynthID Detector looks for an embedded watermark in supported images, video and audio. Here is what its results do—and do not—show.
  3. Redmond desk20 min
    How to create a link to File or Folder in Windows 11Windows 11 gives you several ways to point to a file or folder without moving or duplicating it. You can create a desktop shortcut,…
Recommended PC Tool
Recommended PC Tool
Crashes, No Sound, or Screen Glitches?Free driver scan
PC Slower Than It Used to Be?Free scan - under a minute

Two free Windows tools

One Free Minute Could Fix That PC

Before you go - each of these free tools takes about a minute and tackles what quietly slows a Windows PC down.

Special offer. View Outbyte info, uninstall instructions, EULA, and Privacy Policy.