Markdown Preview

What Markdown is and why it won

Markdown is a plain-text format that converts to HTML. It was created by John Gruber in 2004 as a way to write HTML without writing HTML — the syntax is built around conventions people already used in plain-text email: *asterisks for emphasis*, # for headings, - for bullet points. The output reads naturally on its own and renders as proper HTML when needed.

It won. GitHub README files, Reddit comments, Discord messages, almost every static site generator, and most modern note-taking apps (Obsidian, Notion-flavored, Bear) speak some dialect of Markdown. Once you know the basics, you can write content for almost any modern web tool without thinking about formatting buttons.

The syntax that covers 95% of what you need

# Heading 1
## Heading 2
### Heading 3

**bold** and *italic* and ~~strikethrough~~

> A blockquote.

- Bullet list
- Another bullet
  - Nested

1. Numbered
2. List

[Link text](https://example.com)
![Alt text](image.jpg)

`inline code`

```
fenced code block
```

---  (horizontal rule)

The dialect problem

Markdown has no single official spec. The original 2004 description was incomplete and ambiguous, so every renderer made its own decisions about edge cases. Today there are several flavors that mostly agree but differ at the margins:

• CommonMark — a 2014 effort to write a precise spec. The closest thing to a standard. Most modern renderers (including the one this preview uses) follow it.
• GitHub Flavored Markdown (GFM) — CommonMark plus tables, task lists (- [ ]), strikethrough, autolinking of URLs, and some other extensions. The dialect most people actually mean when they say "Markdown."
• MultiMarkdown / Pandoc — richer extensions for academic writing: footnotes, citations, math, definition lists.
• Notion / Slack / Discord — loosely Markdown-shaped but each does its own thing, especially around code blocks and links.

If you write a document that renders correctly in one place but breaks in another, dialect mismatch is usually why.

Things to know

Lists need blank lines around them

Most renderers require an empty line between a paragraph and a following list, or the list won't be recognized as one. Same goes for code blocks and blockquotes. When something renders as a single run-on paragraph, missing blank lines is the first thing to check.

Hard line breaks

A single newline is treated as a soft break and rendered as a space. To force a line break inside a paragraph, end the line with two spaces, or use a blank line to start a new paragraph. This trips up everyone the first time.

Code blocks: indent vs. fence

The original spec used four-space indentation for code blocks. Most renderers also support fenced blocks with triple backticks — easier to type, easier to preserve indentation inside, and you can specify a language for syntax highlighting (```python). Use fences. The indented form is mostly a legacy holdover.

Tables (GFM)

| Column 1 | Column 2 |
|----------|----------|
| Cell A   | Cell B   |

The pipes don't have to line up — the renderer doesn't care — but lining them up makes the source readable. Tables are the one place Markdown source actually looks worse than the rendered output; for anything more than a few columns, use a real HTML table or a tool that hides the syntax.

HTML escape hatch

Most Markdown renderers pass HTML through. If Markdown can't express what you need (a styled span, a video embed, anything fancy), you can drop raw HTML in the middle of a Markdown document and it will be preserved. This is sometimes useful and sometimes a security hazard — rendering Markdown from untrusted users with HTML pass-through enabled is how you get XSS. Renderers usually have an option to escape or sanitize HTML; turn it on for user input.