Markdown Syntax: The Developer's Writing Language

A Brief History

John Gruber created Markdown in 2004 with a single goal: produce HTML from plain text that is readable as-is, without markup clutter. The original Perl script, Markdown.pl, generated HTML from a set of simple conventions borrowed from email formatting.

The format took off because it hit a sweet spot: expressive enough to cover most documentation needs, simple enough to read and write in a plain text editor, and trivially convertible to HTML.

Today, Markdown is the standard for GitHub READMEs, documentation sites (Docusaurus, MkDocs, GitBook), blog posts (Hugo, Jekyll), and in-editor notes tools (Obsidian, Notion, Bear). It has spawned several extensions: CommonMark (a strict specification), GitHub Flavored Markdown (GFM), and MDX (Markdown with JSX).

Core Syntax Reference

Headings. Created with # characters:

# H1 — document title
## H2 — major section
### H3 — subsection

Emphasis.

*italic* or _italic_
**bold** or __bold__
~~strikethrough~~

Lists.

- Unordered item
- Another item
  - Nested item (indent with 2 spaces)

1. Ordered item
2. Second item

Links and images.

[Link text](https://example.com)
[Link with title](https://example.com "Title")
![Alt text](image.png)

Code.

Inline code with backticks. Fenced code blocks use triple backticks with an optional language hint for syntax highlighting.

Blockquotes.

> This is a blockquote.
> It can span multiple lines.

Horizontal rule.

---

GitHub Flavored Markdown Extensions

GFM adds several features on top of CommonMark:

Tables — pipe-separated columns with a header row
Task lists — - [ ] item and - [x] completed item
Strikethrough — ~~text~~
Autolinks — bare URLs are automatically linked
Code block language hints — syntax highlighting in fenced blocks

Common Pitfalls

Blank lines matter. A blank line separates paragraphs. Without it, two lines of text are treated as a single paragraph. List items separated by blank lines become "loose" lists with paragraph spacing.

Spaces before block elements. A code block created by indentation requires exactly four spaces. Two or three spaces will not trigger it.

Escaping special characters. If you need a literal * or _ in text, escape it with a backslash: \*.

HTML inside Markdown. Raw HTML is allowed in most Markdown processors. This can be useful for elements Markdown doesn't support (like <kbd> or <details>), but it can also break if the processor is running in safe mode.

The Preview Loop

Markdown is written as plain text but displayed as rendered HTML. The tightest workflow is an editor with a live preview pane that updates as you type — the same way the Markdown Previewer on Syntaxly works. Write on the left, see the result on the right in real time.

Try It

The Markdown Previewer on Syntaxly renders GitHub Flavored Markdown with live preview. Paste or write your Markdown in the left pane and see the rendered HTML on the right.