⌂ Home / Markdown Guide

Markdown Guide

Write clean, portable documents — headings, emphasis, lists, links, images, code blocks, tables, blockquotes, GitHub Flavored Markdown, front matter and ready-to-use README recipes. Every code block has a Copy button.

Copy button on each code block  ·  ● Beginner ● Intermediate ● Advanced

01 Introduction — Plain Text That Renders

Markdown is a lightweight markup language that lets you write formatted documents in plain text. You add a few symbols — # for a heading, ** for bold, - for a list — and any Markdown-aware tool renders it into clean HTML, a PDF, a slide deck, or a documentation site.

The point is readability: a Markdown file is perfectly understandable even before it is rendered. Compare that to HTML, where a paragraph is buried in <p> tags, and the value becomes obvious.

Where you will meet Markdown

Analogy: Markdown is the outline you scribble on a napkin; the renderer is the designer who turns it into a printed page. You write structure and intent, the tool handles the pixels.

The two dialects you need to know

💡 Tip: Learn the common core first. Ninety percent of real documents need only headings, emphasis, lists, links, images and code blocks. Everything else is a bonus.

02 Setup & Editors Beginner

Your first file — no build step needed

Create a file ending in .md (or .markdown) and start typing. That is the entire setup.

# My First Markdown File

This is a paragraph. Markdown turns it into a `<p>` on render.

## Why it works

- Plain text, so it survives every editor and every decade
- Portable — GitHub, VS Code and Pandoc all read the same file
- Optional: **bold**, *italic*, `code`, [links](https://example.com)

Editors & live preview

VS Code
Built-in preview: Ctrl+Shift+V (or ⌘+Shift+V)
Markdown All in One
Shortcuts, TOC generation, list editing, preview
Markdown Preview Enhanced
Rich preview, math, diagrams, export to PDF/HTML
markdownlint
Flags style issues and inconsistencies as you type
Typora / Obsidian
WYSIWYG writing with Markdown underneath
GitHub / StackEdit
Zero-install: paste Markdown and see it render instantly

The Markdown pipeline

Almost every tool follows the same three steps. Knowing them explains most “why didn't my formatting work?” moments.

⚠ Empty lines matter: Markdown uses blank lines to separate blocks. If a list, heading or code fence refuses to render, the missing (or extra) blank line is almost always the culprit.
💡 Tip: Install the Markdown All in One extension in VS Code and enable format-on-save. It keeps headings, lists and tables consistently styled without you thinking about it.

03 Headings & Paragraphs Beginner

ATX headings — the hash style

Prefix a line with # symbols. One hash is an H1, two is an H2, up to six for H6. Always put a space after the hashes.

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6
Rule of thumb: Use exactly one # H1 per document — it is the document's title. Use H2 for major sections and H3 for subsections. Never skip a level just to get a smaller font.

Setext headings — the underline style

A less common alternative for the first two levels. The number of = or - characters does not need to match the text length.

Heading 1
=========

Heading 2
---------
⚠ Watch out: A line of dashes under text (---) can be read as a Setext H2 or a horizontal rule, depending on context. Prefer the # style to avoid ambiguity.

Paragraphs & line breaks

A block of text with no blank line inside is a single paragraph. Separate paragraphs with one blank line.

This is the first paragraph.
It continues on the next line — still one paragraph.

This is a second paragraph, because of the blank line above.

To force a line break within a paragraph, end the line with two spaces or a backslash.

Line one with two trailing spaces··
Line two (new line, same paragraph)

Line one with a backslash\
Line two (same effect, easier to see)
💡 Tip: Because trailing spaces are invisible, many teams use the backslash \ for hard breaks and configure their editor's trim trailing whitespace setting — otherwise a formatter silently removes the spaces and the break disappears.

04 Emphasis, Strikethrough & Rules Beginner

Inline emphasis

*italic*   or   _italic_
**bold**   or   __bold__
***bold and italic***
~~strikethrough~~
`inline code`

Mix and nest them freely, but keep markers balanced: **_bold italic_** renders as bold italic.

⚠ Underscores inside words: snake_case_name will not italicise the middle — good. But _foo_bar_ can behave differently across parsers. When in doubt, use * for emphasis.

Horizontal rules

Three or more -, * or _ on their own line, optionally with spaces between, draw a divider.

---
***
___

What is not in the core spec

💡 Tip: If a feature is not in CommonMark or GFM, assume it only works in the specific app you are using. Portability is Markdown's superpower — do not trade it away lightly.

05 Lists & Task Lists Beginner

Unordered lists

Start each item with -, * or +. Pick one and stay consistent.

- Apples
- Oranges
- Bananas

Ordered lists

Numbered items. The first number sets the start; later numbers are cosmetic — Markdown renumbers automatically.

1. Wake up
2. Coffee
3. Write Markdown

Nested lists

Indent child items by two to four spaces under the parent.

- Frontend
  - HTML
  - CSS
  - JavaScript
- Backend
  1. Node.js
  2. Python

Task lists (GFM)

Use - [ ] for an open task and - [x] for a completed one. GitHub renders these as real checkboxes.

- [x] Write the outline
- [x] Draft the introduction
- [ ] Add code examples
- [ ] Request review
Tight vs loose lists: If every item is on one line with no blank lines between them, the list is “tight” (no <p> per item). Add blank lines and the list becomes “loose”, wrapping each item in a paragraph. Both are valid — loose lists just add vertical space.
💡 Tip: In VS Code, the Markdown All in One extension continues lists and re-numbers them automatically when you press Enter — no manual sequencing required.

07 Code & Syntax Highlighting Beginner

Inline code

Wrap short snippets in single backticks. Use double backticks to include a literal backtick inside.

Use `npm install` to install dependencies.
To show a backtick: `` `code` ``

Fenced code blocks

Surround a block with three backticks (or tildes). Add a language name after the opening fence to enable syntax highlighting.

```js
function greet(name) {
  return `Hello, ${name}!`;
}
```

Indented code blocks (legacy)

Indenting four spaces also creates a code block, but fenced blocks are clearer and support highlighting. Prefer fences.

    This is an indented code block.
    It still works, but has no language hint.

Highlighting inside a block

Once you name the language, the renderer colours keywords, strings and comments — no extra markup required.

```python
def add(a, b):
    """Return the sum of two numbers."""
    return a + b
```

Diff blocks

Use the diff language to show added and removed lines with colour.

```diff
- old line that was removed
+ new line that was added
  unchanged context line
```
💡 Tip: Common language tags are js, ts, py, html, css, bash, json, yaml, sql, diff and text. Use text when you want no highlighting at all.

08 Blockquotes & Callouts Intermediate

Blockquotes

Start a line with > to create a blockquote. Stack them to nest, and leave a > on a blank line to keep a single quote spanning multiple paragraphs.

> Markdown is a text-to-HTML conversion tool.
> It is written in plain text.

> Nested quotes:
>
> > A quote inside a quote.

GitHub alerts

GFM recognises five callout types when you start a blockquote with a special tag. GitHub renders each with its own colour and icon.

> [!NOTE]
> Useful information users should know.

> [!TIP]
> Helpful advice for doing things better.

> [!IMPORTANT]
> Key information users need to achieve their goal.

> [!WARNING]
> Urgent info that needs immediate attention.

> [!CAUTION]
> Advises about risks or negative outcomes.

Collapsible sections

Raw HTML <details> works on GitHub and most renderers — perfect for long logs or optional detail.

<details>
<summary>Click to expand</summary>

Hidden content goes here, including lists and code.

</details>
⚠ Alerts are GFM-only: The [!NOTE] syntax renders as an alert on GitHub but appears as an ordinary blockquote elsewhere. Other apps have their own callout syntax — check your renderer.

09 Tables Intermediate

Tables are a GFM extension. Separate columns with pipes |. The first row is the header; the second row of dashes sets the alignment of each column.

| Syntax      | Description           | Example       |
| :---------- | :-------------------: | ------------: |
| Bold        | Makes text bold       | `**text**`    |
| Italic      | Makes text italic     | `*text*`      |
| Strikethrough | Crosses out text    | `~~text~~`    |

Column alignment

:---
Left align (the default)
:---:
Center align
---:
Right align

Escaping pipes and adding line breaks

A literal pipe inside a cell must be escaped as \|. Tables cannot hold real multi-line cells — use <br> for a break.

| Expression | Result     |
| ---------- | ---------- |
| `a \| b`   | bitwise OR |
| Line one<br>Line two | two lines |
💡 Tip: You do not need to align the source pipes — a formatter will tidy the columns for you. In VS Code, the Markdown All in One “Format Document” command reformats tables in one keystroke.

10 Escaping & Raw HTML Intermediate

Escaping special characters

Put a backslash before a character you want to display literally instead of it being interpreted as Markdown.

\*not italic\*
\# not a heading
\- not a list item
\`not code\`

These are the escapable characters: \ ` * _ { } [ ] ( ) # + - . ! | >

Raw HTML

Most renderers pass through inline HTML, which is useful for the few things Markdown cannot express.

This is <u>underlined</u> and this is H<sub>2</sub>O.

<div align="center">A centred block</div>

Comments

<!-- This comment is invisible in the rendered output -->
⚠ Security note: GitHub and most hosting platforms sanitise raw HTML, stripping scripts and dangerous attributes. Never assume embedded HTML or JavaScript will run — and never paste untrusted HTML into a renderer that does not sanitise.
💡 Tip: To display a block of HTML literally, wrap it in a fenced code block with the html language tag so the parser treats it as text, not markup.

11 GitHub Flavored Markdown Advanced

GFM is CommonMark plus the features that make Markdown feel like a platform: tables, task lists, strikethrough, autolinks, footnotes and alerts. It is the dialect used across GitHub, and the one most people mean by “Markdown”.

Footnotes

Markdown is portable.[^1] It also scales to whole books.[^book]

[^1]: A reference is rendered as a superscript number.
[^book]: Pandoc can turn Markdown into EPUB and PDF.

Emoji

Ship it :rocket:  Nice work :tada:  Looks good :+1:

Mentions, issues & references

Thanks @octocat — this closes #42 and supersedes commit a1b2c3d.

On GitHub, @user notifies a person, #123 links to an issue or PR, and a commit SHA links to the commit.

Everything GFM adds at a glance

Tables
Pipe-delimited rows with alignment
Task lists
- [ ] and - [x] checkboxes
Strikethrough
~~text~~
Autolinks
Bare URLs become links
Footnotes
[^1] references and definitions
Alerts
> [!NOTE] callout blocks
Portability check: If a document must render identically everywhere (a book, a PDF, a wiki), stick to CommonMark plus tables and links. Save the GFM-only sugar for places you know support it.

12 Front Matter & Metadata Advanced

Front matter is a block of metadata at the very top of a file, fenced by three dashes. Static site generators, blog engines and documentation tools read it to set titles, dates, tags and layouts. It is not part of the rendered body.

YAML front matter (most common)

---
title: Getting Started
description: A short summary used for SEO and previews.
date: 2026-01-15
author: Laksh
tags: [guide, markdown, docs]
draft: false
---

TOML front matter

Hugo users often prefer TOML, fenced with +++.

+++
title = "Getting Started"
date = 2026-01-15
tags = ["guide", "markdown"]
+++

Who consumes it

⚠ One wrong character breaks the block: YAML is indentation- and punctuation-sensitive. A missing space after a colon, or a tab instead of spaces, can silently invalidate the whole header. Validate with your tool's build output.
💡 Tip: Only add front matter when a tool specifically asks for it. Plain GitHub READMEs do not need it — and on GitHub an unstyled --- block just shows up as a horizontal rule plus text.

13 README & Documentation Recipes Intermediate

A README is the front door of a project. This is a proven skeleton you can copy and fill in.

# Project Name

> One-line description of what this project does and who it is for.

[![Build](https://img.shields.io/badge/build-passing-brightgreen)](https://ci.example.com)
[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

## Features

- Fast and dependency-free
- Works with any Markdown renderer
- Accessible by default

## Installation

```bash
npm install project-name
```

## Usage

```js
import { project } from "project-name";
project();
```

## Contributing

Pull requests are welcome. Please open an issue first.

## License

MIT

A table of contents, generated by hand

Anchor links point at the lowercased, hyphenated heading text. Most editors (or Markdown All in One) can generate this list for you.

## Table of Contents

- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [Contributing](#contributing)
- [License](#license)

Collapsing the long parts

<details>
<summary>Roadmap</summary>

- [ ] v1.0 — core release
- [ ] v1.1 — theming
- [ ] v2.0 — plugins

</details>
💡 Tip: Lead with why, not what. A stranger gives a README about eight seconds. A one-line value statement plus a quick-start code block is worth more than a long architecture essay.

14 Cheat Sheet & Best Practices Beginner

Syntax at a glance

# H1
Heading (##, ###, …)
**bold**
Bold text
*italic*
Italic text
~~strike~~
Strikethrough (GFM)
`code`
Inline code
- item
Bulleted list
1. item
Numbered list
- [x] task
Task list (GFM)
[text](url)
Link
![alt](img)
Image
```lang
Fenced code block
> quote
Blockquote
---
Horizontal rule
\| col \|
Table row (GFM)
[^1]
Footnote (GFM)
\*escape\*
Literal special char

Best practices

Remember: Markdown is designed to be readable as written. If a raw .md file is scannable and clean, it will render well almost everywhere.
💡 Tip: Keep line lengths reasonable (about 80–100 characters) and let your editor soft-wrap. It makes diffs on GitHub far easier to review.