Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 39 ยท Markdown and Documentation

Markdown Syntax: The Complete Guide

Learn all core Markdown syntax - headings, emphasis, lists, links, images, code, quotes, rules and HTML - with the CommonMark rules for edge cases and runnable Node examples.

Markdown is a plain-text writing format that converts to HTML. John Gruber created it in 2004 with a simple goal: a document should be readable as plain text, without looking like it is full of tags. Today Markdown is used for README files, documentation sites, blog engines, chat apps, note-taking tools, and the lessons on this very site. The original description was loose, so a group of authors wrote CommonMark, a precise specification with test cases, and most modern parsers follow it. This lesson teaches the core syntax defined by CommonMark; the next one, GitHub Flavored Markdown and Front Matter, covers the common extensions.

Headings

A line starting with one to six # characters and a space is a heading. The number of hashes is the level (<h1> to <h6>).

MARKDOWN
# Title
## Section
### Subsection

An older style underlines the text with === (level 1) or --- (level 2). Use ATX hashes: they work at every level. Put a blank line before and after a heading, and keep one # level-1 heading per page.

Paragraphs and line breaks

Text separated by blank lines forms paragraphs. A single newline inside a paragraph is just a space when rendered. For a hard line break, end a line with two spaces or a backslash:

MARKDOWN
First line with a break\
second line in the same paragraph.

Trailing spaces are invisible and often stripped by editors, so the backslash is more reliable.

Emphasis

MARKDOWN
*italic* or _italic_
**bold** or __bold__
***bold and italic***
`inline code`

Prefer asterisks inside words (un*believ*able), because underscores inside words are not treated as emphasis in CommonMark. To show a literal asterisk, escape it with a backslash: \*. Backslash escapes work for all the punctuation Markdown uses.

Lists

Unordered lists use -, * or +; ordered lists use a number and a period. Indent nested lists to line up with the text of the parent item.

MARKDOWN
- Fruit
  - Apple
  - Pear
- Vegetables

1. Prepare
2. Cook
3. Serve

The actual numbers in an ordered list do not matter except for the first one: 1. 1. 1. renders as 1, 2, 3, while 5. as the first number starts counting at 5. A list is "loose" (each item wrapped in a paragraph) when its items are separated by blank lines, and "tight" otherwise. To put a paragraph or code block inside an item, indent it as much as the item's text.

MARKDOWN
[A link](https://example.com "optional title")
[Reference style][docs]
<https://example.com>
![Alt text](/images/photo.png "Title")

[docs]: https://example.com/docs

Reference-style links keep long URLs out of the sentence. An image is a link preceded by !; the text in brackets becomes the alt text, which matters for accessibility. Relative URLs (/guide/start, ../img/a.png) are allowed and resolved against the page.

Code

Inline code uses backticks. For blocks, use a fenced code block with three backticks (or tildes) and an optional language name after the opening fence, which highlighters use:

MARKDOWN
```js
const total = items.reduce((sum, i) => sum + i.price, 0);
```

To show a fence inside a fence, make the outer one longer (four backticks, as above). An older form indents every line by four spaces; avoid it because it is easy to trigger by accident.

Block quotes and rules

MARKDOWN
> A quote can span several lines
> and contain *emphasis* and lists.

---

A line starting with > begins a block quote. A line of three or more -, * or _ creates a horizontal rule (<hr>).

Raw HTML

CommonMark allows inline and block HTML, which passes straight through: <kbd>Ctrl</kbd> or a <details> block. That is convenient and dangerous, because user-written Markdown could carry <script>. A renderer for untrusted input must sanitise the HTML or disable it (see Data Format Security).

How a parser reads Markdown

Markdown is parsed in two layers: blocks first (headings, paragraphs, lists, quotes, code), then inline content inside those blocks (emphasis, links, code spans). Knowing this explains many surprises.

flowchart LR
  A["Markdown text"] --> B["Block parser: headings, lists, quotes, code"]
  B --> C["Inline parser: emphasis, links, code spans"]
  C --> D["Syntax tree (AST)"]
  D --> E["HTML renderer"]

Block structure is decided first; inline syntax is parsed inside each block.

Node.js Classify lines into Markdown block types

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Note the last line: #NoSpace is plain text, because CommonMark requires a space after the hashes. That strictness is what separates CommonMark from older parsers.

Node.js Build a table of contents from headings

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Two practical lessons here: a # inside a fenced block is code, not a heading, and repeated headings need unique anchors (usage, usage-1), which is what most renderers do for heading links.

Writing habits that keep Markdown portable

  • Leave a blank line between different blocks (paragraph, list, heading, code).
  • Use one list marker style and consistent indentation (two or four spaces).
  • Always give fenced code blocks a language.
  • Write meaningful link text (not "click here") and always add alt text to images.
  • Keep lines reasonably short or one sentence per line for clean version-control diffs.
  • Check what your target renderer supports; extensions such as tables are not CommonMark.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which line is a level-2 heading in CommonMark?

    Hashes must be followed by a space, so the second line is the heading; the first is plain text.
  2. 2. How do you create a hard line break without trailing spaces?

    A backslash at the end of a line makes a hard break, and it survives editors that trim whitespace.
  3. 3. How do you show a three-backtick code block inside another fenced block?

    The closing fence must match the opening fence length, so a longer outer fence can contain shorter ones.
  4. 4. What does a Markdown parser decide first?

    Parsing is two-layered: block structure first, then inline syntax inside each block.
  5. 5. Why must a renderer for user-submitted Markdown sanitise HTML?

    Because raw HTML is allowed, untrusted Markdown can inject script tags unless the output is sanitised.

Summary

  • Markdown is plain text that converts to HTML; CommonMark is the precise specification.
  • Core syntax: # headings, emphasis, lists, links, images, backtick code, > quotes, rules.
  • Parsing is block first, inline second; a space after # is mandatory.
  • Fences, escapes and blank lines solve most surprises.
  • Raw HTML is allowed, so untrusted input must be sanitised.

Next: GitHub Flavored Markdown and Front Matter