What is Markdown? A Practical Introduction

Markdown was created by John Gruber in 2004 with a single, elegant goal: write plain text that reads naturally, then convert it to clean HTML. Two decades later it's everywhere — GitHub README files, pull request descriptions, Slack messages, Notion docs, blog posts, AI chat responses. It's one of those tools you'll use every day for the rest of your career, whether you think about it consciously or not.

What Markdown Actually Is

Markdown is plain text with lightweight, readable syntax layered on top. A # at the start of a line becomes an <h1>. Wrapping a word in **double asterisks** makes it bold. Backticks produce inline code. The central design philosophy is that Markdown source should be readable as-is — even before it's rendered. If you've ever written an email with *asterisks around emphasis* or used dashes for a bullet list, you were already writing something very close to Markdown.

Here's a quick before-and-after. The Markdown on the left produces the HTML on the right:

## Getting Started

Install the package with **npm**:

`npm install my-library`

Then import it in your project — see the [docs](https://example.com) for details.

<h2>Getting Started</h2>
<p>Install the package with <strong>npm</strong>:</p>
<p><code>npm install my-library</code></p>
<p>Then import it in your project — see the <a href="https://example.com">docs</a> for details.</p>

You write the top half; a Markdown processor produces the bottom half. That translation step is invisible once it's in your editor or CI pipeline.

Core Syntax — The Part Every Flavor Shares

Whatever Markdown variant you're using, these building blocks work everywhere:

• Headings — # H1, ## H2, ### H3 (up to six levels)
• Bold and italic — **bold**, *italic*, ***both***
• Links — [link text](https://url.com)
• Images — ![alt text](image.png)
• Inline code — `backtick` wraps a snippet; triple backticks open a fenced code block
• Blockquotes — start a line with >
• Unordered lists — lines starting with - or *
• Ordered lists — lines starting with 1., 2., etc.
• Horizontal rule — three or more dashes: ---

Here's a realistic README snippet that uses all of the above together:

# json-transform

> A zero-dependency library for transforming JSON structures.

## Installation

```bash
npm install json-transform
```

## Usage

```js
import { transform } from 'json-transform';

const result = transform(input, schema);
```

## Features

- **Fast** — processes 10k objects/sec on average hardware
- *Typed* — ships with full TypeScript definitions
- Zero runtime dependencies

See the [full documentation](https://json-transform.dev/docs) for advanced options.

---

MIT License

The Flavor Problem — CommonMark, GFM, and Others

Here's the catch: "Markdown" isn't one thing. Gruber's original 2004 spec was intentionally loose, which led to years of incompatible implementations. Different parsers handled edge cases — nested lists, blank lines inside blockquotes, precedence between emphasis and links — in different ways. The same source file would render differently in different tools.

CommonMark (launched in 2014) fixed this. A group of developers — including people from GitHub, Stack Overflow, and Reddit — wrote a rigorous, unambiguous specification that covered every edge case with a test suite of 652 examples. Most modern tools now use CommonMark as their baseline.

GitHub then extended CommonMark with their own additions and published GitHub Flavored Markdown (GFM). GFM is what you write in GitHub READMEs, issues, and pull requests. Many other tools have adopted GFM extensions too, but not all of them — so what renders on GitHub might not render the same way in your static site generator or note-taking app. Knowing which flavor your tool supports saves a lot of head-scratching.

GitHub Flavored Markdown Extensions

GFM adds five features on top of CommonMark that you'll use constantly on GitHub and any tool that supports the GFM superset:

Tables — pipe-delimited columns with a separator row of dashes:

| Method  | Returns       | Mutates? |
|---------|---------------|----------|
| map()   | new array     | No       |
| filter()| new array     | No       |
| sort()  | same array    | Yes      |

Task lists — checkboxes in issues and pull requests:

- [x] Write unit tests
- [x] Update CHANGELOG
- [ ] Add migration guide
- [ ] Tag release

Strikethrough — wrap text in double tildes:

~~deprecated API~~ — use `newMethod()` instead

Fenced code blocks with language hints — the language identifier after the opening backticks triggers syntax highlighting:

```python
def parse_config(path: str) -> dict:
    with open(path) as f:
        return json.load(f)
```

Autolinks — bare URLs like https://example.com are automatically made clickable without needing [text](url) syntax. This is convenient in issue comments but can be surprising if you paste a URL you don't want linked.

Where You'll Use Markdown in Practice

Markdown turns up in more places than most developers expect when they first encounter it:

• GitHub and GitLab — README files, issues, pull request descriptions, wikis, and even commit message bodies. Every repository you touch will have at least a README.md.
• Static site generators — Jekyll, Hugo, Eleventy, Astro, and Next.js all accept Markdown content files. You write posts in .md files and the generator converts them to HTML pages at build time.
• Documentation tools — MkDocs, Docusaurus, and GitBook are built entirely around Markdown source. Open-source libraries almost universally use one of these.
• Note-taking apps — Obsidian, Notion, Bear, and Typora all use Markdown as their native format (with varying extensions). Your notes are portable plain text files, not a proprietary database.
• CMS platforms — Ghost uses Markdown natively. Contentful and Strapi both support Markdown fields. Headless CMS setups typically store long-form content as Markdown strings.
• AI tools — ChatGPT and Claude both output Markdown by default. Code snippets, bold terms, and bullet lists in AI responses are Markdown — the chat UI renders them, but the underlying text is **bold** and ```python.

Markdown vs HTML — When to Use Which

Markdown converts to HTML, but it can't express everything HTML can. There's no equivalent for <div class="card">, data-* attributes, or aria-* attributes. For simple prose content — documentation, READMEs, blog posts, changelogs — Markdown is faster to write and far more readable in its raw form. For complex UI components, custom layouts, or accessibility annotations that require specific attributes, you need HTML.

The good news: most Markdown processors allow raw HTML inline. You can mix the two. If you need a <figure> with a <figcaption>, or a <details> disclosure widget, just write the HTML directly in your .md file. The processor passes it through untouched. Use this escape hatch sparingly — if more than a third of your file is raw HTML, you might as well write HTML directly and use our HTML Formatter to keep it clean.

• Use Markdown for: documentation, READMEs, changelogs, blog posts, knowledge-base articles, API description fields
• Use HTML for: precise layout, custom components, forms, elements requiring specific attributes
• Mix both when: mostly prose content with a handful of structural exceptions (a responsive table, a video embed)

Wrapping Up

Markdown is deceptively simple — it looks like just a handful of punctuation rules, but it powers documentation for virtually every major open-source project. Understanding the core syntax takes about ten minutes. Understanding the flavor differences (CommonMark vs GFM vs whatever your SSG uses) is what separates developers who occasionally fight their docs tooling from those who don't.

The authoritative references: CommonMark for the standardised spec, GitHub Flavored Markdown for the GitHub extensions, and Markdown Guide for a practical cheat-sheet reference. For day-to-day writing, our Markdown Preview lets you see rendered output instantly, and the Markdown Formatter keeps your source files consistent.