Markdown adds document structure to plain text with familiar punctuation. This reference follows CommonMark, a specification designed to make parsing behavior consistent. Individual platforms may add tables, footnotes, task lists, or other extensions; those features are not portable CommonMark unless the receiving system documents them.

Headings

Place one to six hash signs at the start of a line, followed by a space. The count gives the heading level. A document normally has one level-one heading and uses levels in order.

Rendered result

A level-three heading

### A level-three heading

CommonMark also supports “setext” headings: text followed by a line of equals signs becomes level one, and a line of hyphens becomes level two. Hash-style headings are easier to recognize when copied out of context. A missing space changes the interpretation: #topic is ordinary text, not an ATX heading.

Emphasis

One asterisk or underscore pair usually creates emphasis; two create strong emphasis. Asterisks are often less surprising inside identifiers because underscores within an alphanumeric word do not create emphasis under CommonMark.

Rendered result

This is emphasized, this is strong, and this is both.

This is *emphasized*, this is **strong**, and this is ***both***.

Delimiters must open and close in valid positions. Punctuation and whitespace affect that decision, which explains why an unmatched asterisk sometimes remains visible. For emphasis across complex punctuation, simplify the sentence or check it in the target renderer.

Lists

Unordered lists use -, +, or * followed by a space. Ordered lists use digits plus a period or right parenthesis. Indent continuation lines and nested content so their relationship is clear.

Rendered result
  • Tea
  • Coffee
    • Ground
    • Whole bean
  1. Measure.
  2. Mix.
- Tea
- Coffee
  - Ground
  - Whole bean

1. Measure.
2. Mix.

The source numbers do not always determine every displayed number; a parser creates an ordered-list sequence, though a starting number other than 1 can be significant. To begin a paragraph literally with something like 1986., escape the period as 1986. if the parser would otherwise make a list.

An inline link places visible text in brackets and the destination in parentheses. Optional title text can follow the URL in quotes. Use descriptive text that makes sense without “click here.”

Rendered result

Read the CommonMark specification.

Read the [CommonMark specification](https://spec.commonmark.org/0.31.2/).

Reference-style links separate the destination from the sentence, which can make repeated or long URLs easier to edit:

Read the [CommonMark specification][spec].

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

An image adds an exclamation mark before link syntax: ![Alt text](image.png). The bracketed text is the text alternative, not a caption. Describe the image’s purpose succinctly; use empty alt text only when the image is genuinely decorative. Markdown does not make a remote image private or reliable, so consider where the file is hosted.

Block quotations and code

A greater-than sign at the beginning of a line creates a block quotation. Continue the marker on subsequent paragraphs for source clarity.

Rendered result

A quoted paragraph can contain emphasis.

> A quoted paragraph can contain *emphasis*.

Backticks create inline code and protect Markdown punctuation inside it: **literal asterisks**. Fenced code blocks begin and end with lines containing at least three backticks or tildes. An optional info string such as html can request syntax highlighting, but highlighting is an implementation feature.

```html
<p>Visible as code, not an HTML paragraph.</p>
```

If the code itself contains a run of three backticks, use a longer fence around it. Long lines may overflow narrow screens, so a publishing stylesheet should let code blocks scroll horizontally rather than forcing the whole page wider.

Escaping punctuation

A backslash prevents an ASCII punctuation character from taking on Markdown meaning. For example, *not emphasis* renders as literal asterisks. In a code span or fenced code block, punctuation is already literal, so backslash escaping generally is not needed.

When literal backticks are needed inline, wrap the span with a longer run: two backticks can contain one. HTML character references, such as &amp; for an ampersand, are also recognized, but relying on raw HTML can reduce portability or be blocked by a security filter.

Thematic breaks and line breaks

A line containing three or more matching asterisks, hyphens, or underscores—with optional spaces—can create a thematic break. A blank line around it avoids ambiguity, especially because hyphens can also make a setext heading.

Rendered result

End of one scene.

Beginning of another.

End of one scene.

---

Beginning of another.

Ordinary single line endings inside a paragraph are generally treated like spaces. For an explicit hard line break, end a line with a backslash or at least two spaces. The backslash is visible in source and less likely to be removed accidentally by an editor.

Common ambiguities

  • A hyphen after text may underline a heading or begin a list, depending on blank lines and position.
  • Asterisks can mean emphasis, list markers, or a thematic break.
  • Indentation can nest a list item, continue its paragraph, or create code.
  • Parentheses in a link destination may need balancing or escaping.
  • Platform extensions can make source behave differently elsewhere.

Use blank lines generously between block elements, keep list indentation consistent, and preview with a CommonMark-compatible renderer. Markdown is readable because punctuation carries structure; a little spacing makes that structure evident to both humans and parsers.

Sources and further reading