Markdown is the writing format that quietly took over the modern web. GitHub README files, Reddit posts, Discord messages, Notion documents, Obsidian notes, almost every static site generator, half the documentation sites you have ever read: all Markdown. Two decades after John Gruber and Aaron Swartz designed it, Markdown has become the universal format for writing structured text on the internet. This guide covers the syntax, the GitHub Flavored extensions you actually need, common mistakes, and when to reach for HTML instead.
Why Markdown won
Before Markdown, structured writing on the web had two bad options: write HTML by hand (verbose and ugly to read) or use a rich text editor that produced unreadable, inconsistent HTML behind the scenes. Markdown introduced a third option: write plain text with a few simple conventions that look like normal punctuation, then let a converter generate clean HTML at publish time.
The design constraint was that the source had to be comfortable to read even before conversion. Compare:
HTML: <p>This is <strong>important</strong> text.</p>
Markdown: This is **important** text.
Markdown reads naturally as prose. HTML does not. Once the format started showing up in places programmers spent a lot of time (early blogging tools, then GitHub), it spread fast.
The core Markdown syntax
Headings
One to six hash signs at the start of a line, followed by a space and the heading text:
# H1## H2### H3
Use one H1 per page (the title). Use H2 for major sections, H3 for subsections. Skip levels and accessibility tools get confused.
Bold, italic, and combinations
**bold**or__bold__for strong*italic*or_italic_for emphasis***both***for bold italic~~strikethrough~~in GFM
Links and images
Inline link: [link text](https://example.com). Image: . The exclamation mark is the only difference.
Reference-style link (cleaner for long URLs that appear multiple times):
[link text][1][1]: https://example.com
Lists
Unordered with -, *, or + at the start of each line. Ordered with 1., 2., etc. (the actual numbers do not matter; renderers count for you).
Indent four spaces or one tab to nest lists. Indent the same way to continue a paragraph inside a list item.
Code
Inline: backticks around the text, like `code`. Block: three backticks on their own line, content, three backticks on their own line again. Add a language identifier after the opening backticks (```js) for syntax highlighting in tools that support it.
Blockquotes
Start a line with > followed by a space. Multiple paragraphs in a quote: prefix each line with >. Nest with > >.
Horizontal rules
Three or more dashes, asterisks, or underscores on a line by themselves: ---, ***, or ___. Use sparingly; lots of horizontal rules signal poor heading structure.
GitHub Flavored Markdown (GFM)
Standard Markdown is small. GitHub Flavored Markdown adds the features modern writers actually need. GFM is now the de facto standard everywhere, used by GitHub, GitLab, Reddit, Stack Overflow, and most blog platforms.
Tables
Pipe-separated columns with a header divider:
| Tool | Type | Free || --- | --- | --- || ToolHub | Web | Yes |
Alignment with colons in the divider row: :--- for left, ---: for right, :---: for center.
Task lists
List items with [ ] for unchecked or [x] for checked:
- [x] Build Markdown converter- [ ] Write blog post
GitHub renders these as actual checkboxes. Useful for TODOs, project status, and checklists in README files.
Fenced code blocks with language
Specify the language after the opening fence to enable syntax highlighting: ```python, ```js, ```rust. The set of supported languages depends on the highlighter the renderer uses.
Auto-linking
Plain URLs in text get auto-converted to clickable links in GFM. No square brackets needed: writing https://example.com just works.
Markdown vs HTML
| Markdown | HTML | |
|---|---|---|
| Readability of source | Excellent (looks like prose) | Cluttered with tags |
| Speed to write | Fast | Slow |
| Feature ceiling | Limited to text formatting | Unlimited |
| Custom styling | None | Full CSS control |
| Inline media (video, embeds) | Requires HTML escape hatch | Native |
| Best use | Source content for writing | Final rendering and complex layouts |
The right pattern is usually: write in Markdown, render to HTML at publish time. Add HTML directly only when you need something Markdown cannot express (centered images, video embeds, complex tables). Most Markdown processors allow inline HTML for exactly this reason.
Common Markdown mistakes
Forgetting blank lines
Most Markdown processors require a blank line before a list, code block, or heading. Without it, the previous paragraph might absorb your list. When in doubt, add a blank line.
Mixing list markers
Pick one of -, *, or + for unordered lists and stick with it. Mixing makes Markdown linters complain and looks inconsistent in source review.
Hard-wrapping inside paragraphs
Some editors auto-wrap at 80 columns. Most Markdown processors treat single newlines as soft (continuation of the same paragraph). A few treat them as hard breaks. To ensure portable behavior, write each paragraph on a single line or use two trailing spaces to force a line break.
Ambiguous emphasis
_my_var_can be parsed as “my” emphasized then “var_”, or as the literal text. For variable names with underscores, escape with backslash (\_) or wrap in backticks.
Tables without headers
GFM tables require a header row plus a divider row, even if you do not actually want a header. Workaround: use empty header cells.
Markdown variants you might encounter
- CommonMark: a strict, formal specification of standard Markdown. The base most modern processors implement.
- GitHub Flavored Markdown (GFM): CommonMark plus tables, task lists, strikethrough, autolinks. The de facto modern standard.
- MultiMarkdown: an early extended dialect with footnotes, citations, math. Less common today.
- Pandoc Markdown: a superset used by the Pandoc converter with academic features (footnotes, citations, math via LaTeX).
- MDX: Markdown plus JSX. Lets you embed React components in Markdown source. Common in modern dev docs (Next.js, Docusaurus).
Tools and workflow
Where you actually write Markdown depends on what you are writing for.
For writing prose: Obsidian, Bear, iA Writer
Dedicated Markdown editors with live preview, vault organization, and keyboard shortcuts. Best for personal notes, journaling, drafts.
For technical docs: VS Code or any editor with a Markdown extension
Lets you keep docs alongside code. Live preview is a click away. Most teams already have VS Code installed.
For converting to HTML: ToolHub Markdown Converter
For quick one-off conversions when you need HTML to paste into a CMS or email, our Markdown to HTML converter handles it in your browser. No upload, no signup, full GFM support.
Free tool
Try the Markdown ↔ HTML Converter now
Convert between Markdown and HTML with live preview
Common questions
Can I use HTML inside Markdown?
Yes. Most Markdown processors pass inline HTML through unchanged. This is the standard escape hatch for things Markdown cannot express. Just be careful with user-supplied Markdown, since inline HTML is also an XSS vector.
Why does my Markdown look different on different sites?
Different processors implement different feature sets. GitHub, Reddit, Discord, and Notion all have minor variations. To write portable Markdown, stick to CommonMark plus the widely-supported GFM extensions (tables, task lists, fenced code).
What about math?
Standard Markdown does not support math. GitHub added LaTeX math rendering recently using $inline$ and $$block$$ syntax. Most other Markdown processors require a plugin (KaTeX, MathJax) for math.
Is Markdown an open standard?
The original Markdown spec by Gruber is informal and ambiguous. CommonMark is a community-driven formal specification of the core syntax. GFM is GitHub's extended spec built on CommonMark. Most modern processors aim for CommonMark compliance with optional GFM extensions.
Should I learn Markdown if I am not a developer?
Yes, if you write online. Markdown takes 15 minutes to learn and saves you from fighting rich text editors forever after. Notion, Reddit, Discord, GitHub, Slack, and most modern writing platforms all support Markdown. The skill is broadly useful.
Summary
Markdown is plain text plus a small set of conventions that convert to clean HTML. Standard Markdown handles headings, emphasis, lists, links, code, and blockquotes. GitHub Flavored Markdown adds tables, task lists, strikethrough, and auto-linking. Use Markdown for source content, render to HTML at publish time, and reach for inline HTML only when Markdown cannot express what you need. It is one of the highest leverage skills any digital writer can pick up in a single afternoon.