Markdown: The Writer's Format That Works Everywhere

# Markdown: The Writer's Format That Works Everywhere

Markdown is a plain text format that converts to HTML. It's what README files, documentation sites, blog platforms, and chat apps use. If you write anything for the web, you probably need to know Markdown.

The 10 Marks That Cover 95% of Use

# Heading 1

bold and *italic*

link text

!alt text

• bullet list
• another item

1. numbered list
2. second item

inline code

\\\` code block \\\`

> blockquote `

That's it. Most Markdown documents use just these elements.

Why Markdown Beat Rich Text

I've worked in teams that used Google Docs, Confluence, Notion, and Markdown. Markdown always wins for technical content because:

1. It's plain text — Works in any editor, diffs cleanly in git, no binary format issues.
2. It's portable — The same .md file renders on GitHub, GitLab, Notion, Obsidian, and any static site generator.
3. It's fast — No mouse needed. You type bold faster than reaching for Cmd+B.
4. It doesn't break — Rich text editors have formatting bugs. Markdown is predictable.

GitHub-Flavored Markdown (GFM)

GitHub extended standard Markdown with:

• Tables — | Column | Column |
• Task lists — - [x] done / - [ ] todo
• Strikethrough — ~~deleted~~
• Fenced code blocks — Triple backticks with language hint

Most Markdown renderers support GFM now. It's the de facto standard.

Previewing Markdown

Writing Markdown is easy. Seeing what it looks like rendered requires a previewer. Our Markdown Previewer shows a live HTML preview as you type. Free, runs in your browser, no signup.

## Markdown Flavors Explained

Markdown has fragmented into several dialects. The original specification by John Gruber (2004) is minimal, and different platforms have extended it in incompatible ways:

• CommonMark: A standardized, well-specified dialect. Used by GitHub, Reddit, Discourse, and many others. The closest thing to a universal Markdown standard.
• GitHub Flavored Markdown (GFM): CommonMark plus tables, task lists, strikethrough, and auto-linking URLs. The most widely used extension.
• MultiMarkdown: Adds footnotes, citations, definition lists, and math support. Popular in academic writing.
• MDX: Markdown with embedded JSX components. Used in React-based documentation sites and blogs.

Before writing Markdown for a specific platform, check which features it supports. A table that renders on GitHub may not render on a different platform.

Common Markdown Mistakes

1. Nested lists need indentation: In CommonMark, nested list items must be indented by at least 2 spaces (some parsers require 4).
2. Code blocks vs inline code: Use single backticks for inline code and triple backticks for code blocks. Mixing them causes rendering errors.
3. Headers need a space: #Header is not a header. # Header is. The space is required by CommonMark.
4. Links and images: text for links, !alt for images. Forgetting the ! turns an image into a link.
5. Escaping special characters: Use backslash to escape *, _, #, [, ], \ when you want them literally.