Markdown Guide — Everything You Need to Know
Markdown — The Writing Format That Developers, Writers, and Everyone Should Know
Markdown is a lightweight markup language created in 2004 by John Gruber with the explicit goal of being “as easy to read and write as possible.” Unlike HTML, which surrounds content with verbose tags (<strong>bold text</strong>), Markdown uses simple punctuation characters that are intuitive even to people who have never heard of Markdown (**bold text**).
What started as a niche formatting tool for tech bloggers has become the default writing format for technical documentation (GitHub READMEs, API docs), note-taking applications (Notion, Obsidian, Bear), messaging platforms (Slack, Discord, Reddit), content management systems (Ghost, Jekyll, Hugo), and developer communication (pull request descriptions, issue comments, commit messages).
The Core Syntax You Need to Know
Headings: Use # symbols. One # for the largest heading (H1), two ## for H2, up to six ###### for H6. Always put a space after the # symbols.
Emphasis: *italic text* or _italic text_. **bold text** or __bold text__. ***bold italic*** for both.
Lists: Start lines with – or * for unordered lists. Start with 1., 2., 3. for ordered lists. Indent with two or four spaces for nested lists.
Links: [link text](URL). Example: [Google](https://google.com) renders as a clickable link.
Images: . Same as links but with an exclamation mark prefix.
Code: Backticks for inline code: `variable_name`. Triple backticks for code blocks with optional language specification for syntax highlighting.
Blockquotes: Start lines with > for quoted text. Useful for highlighting important notes or quoting external sources.
Why Markdown Won
Several lightweight markup languages existed before Markdown (textile, reStructuredText, wiki markup), and several have appeared since (AsciiDoc, Org Mode). Markdown won the adoption race for three reasons:
First, readability without rendering. A Markdown document is readable as plain text — the formatting characters are unobtrusive enough that the text makes sense even without a Markdown renderer. This is not true of HTML, LaTeX, or most other markup languages.
Second, GitHub adopted it. When GitHub made Markdown the default format for README files, every open-source project in the world started writing Markdown. Developer adoption snowballed from there.
Third, it is easy to learn. The core syntax (headings, bold, italic, links, lists, code) can be learned in five minutes. There are no closing tags to forget, no attributes to configure, and no nesting rules to violate.
Markdown Flavors
One of Markdown’s weaknesses is the lack of a comprehensive specification. The original Markdown specification is ambiguous about many edge cases, leading to “flavors” — extensions that add features and resolve ambiguities differently. GitHub Flavored Markdown (GFM) adds tables, task lists, strikethrough, and autolinked URLs. CommonMark is a strict specification that resolves all ambiguity in the original spec. Most modern tools support GFM or CommonMark.
Convert Markdown to HTML and preview the rendered output with our tools — write in Markdown and see the formatted result in real time.
Markdown Best Practices for Documentation
Good documentation follows consistent formatting conventions. Use heading levels hierarchically — never skip from H2 to H4. Keep paragraphs short and focused on a single idea. Use code blocks with language identifiers for syntax highlighting. Use tables for structured comparisons. Use blockquotes for important callouts and warnings.
For project README files, include these sections in order: project name and one-line description, badges (build status, version, license), installation instructions, quick start or usage examples, configuration options, contributing guidelines, and license information. A well-structured README is often the difference between a project that gets adopted and one that gets ignored, even when the underlying code is identical in quality.