←Back to Blog
Developer Tools

Markdown Mastery: From Zero to Documentation Expert

•11 min read•By KBC Grandcentral Research Team

Markdown powers GitHub's billions of README files, Stack Overflow's millions of posts, and documentation for virtually every open source project. It's not just a text format — it's a philosophy: content over formatting, portability over polish. Here's everything you need to know.

# Hello World**Bold text** and *italic*- Item one- Item two`code snippet`renderHello WorldBold text and italicItem oneItem twocode snippetPlain Text → Beautiful Output

Key Takeaways

  • John Gruber created Markdown in 2004 — originally for writing HTML without typing tags
  • GitHub Flavored Markdown (GFM) adds tables, task lists, and @mentions to CommonMark
  • Flavor fragmentation means GFM content may not render correctly in other parsers
  • Pandoc is the Swiss Army knife — converts Markdown to PDF, Word, slides, LaTeX
  • Markdown is version-control friendly — diffs are meaningful, merges work correctly

The Core Syntax: Everything in One Place

ElementMarkdown SyntaxResult
Heading 1# TitleLarge bold title
Bold**text** or __text__Bold
Italic*text* or _text_Italic
Link[text](url)Clickable link
Image![alt](url)Embedded image
Code (inline)`code`code
Code block```js ... ```Syntax-highlighted block
Blockquote> textIndented quote
Horizontal rule---Horizontal divider

Markdown Flavors: Why Your Content May Not Render Everywhere

John Gruber's original 2004 Markdown spec was intentionally minimal and deliberately left edge cases ambiguous. This led to a fragmented ecosystem of incompatible extensions. CommonMark (2014) was created to resolve this with a fully specified, unambiguous grammar. Most modern platforms now implement CommonMark as their base.

CommonMark

The formal specification. Resolves all edge cases. Used by: Discourse, Stack Overflow, GitHub (partially), Reddit (partially).

Best for portability

GitHub Flavored Markdown (GFM)

Extends CommonMark with tables, task lists, strikethrough (~~ ~~), autolinks, and @mentions / #issue references.

Best for GitHub repos

Pandoc Markdown

Most feature-rich: footnotes, citations, LaTeX math, definition lists, superscripts, metadata blocks. Used for academic writing and document conversion.

Best for documents/academic

R Markdown / Quarto

Embeds executable R, Python, or Julia code. Renders to HTML, PDF, or slides. Standard for reproducible research and data science notebooks.

Best for data science

GFM Extra Features Worth Knowing

Tables (GFM only)

| Name  | Age |
|-------|-----|
| Alice | 28  |
| Bob   | 32  |

Task Lists (GFM only)

- [x] Write the post
- [x] Add code examples
- [ ] Get peer review
- [ ] Publish

Common Markdown Pitfalls

Blank lines before lists and code blocks

Most parsers require a blank line before a list or fenced code block following a paragraph. Missing it breaks rendering silently.

Mixed tabs and spaces in indented lists

Mixing 2-space and 4-space indentation in nested lists produces inconsistent behavior across parsers. Pick one and stick with it.

Math rendering not universal

LaTeX math ($E=mc^2$) is supported by Pandoc, Typora, and GitHub (since 2022) but not in most other parsers or plain CommonMark.

Single newlines are not paragraph breaks

A single newline continues the same paragraph. You need two consecutive newlines (a blank line) to start a new paragraph. This surprises almost every new Markdown user.

Write and Preview Markdown Instantly

Markdown Editor with Live Preview

Write Markdown on the left, see the rendered output on the right in real-time. Supports GFM tables, task lists, and syntax highlighting.

Open Markdown Editor →