About the Markdown Previewer

Markdown is a lightweight markup language created by John Gruber in 2004. It uses plain text symbols to format content — asterisks for bold, hashes for headings, hyphens for lists — which are converted to HTML for display. GitHub, Reddit, Notion, Slack, and most documentation platforms support Markdown natively, making it one of the most widely used writing formats on the web.

Essential Markdown syntax

Headings — # H1, ## H2, ### H3
Bold / italic — **bold**, *italic*, ***both***
Links — [link text](https://url.com)
Images — ![alt text](image-url.jpg)
Code — `inline code` or triple backticks for fenced code blocks
Lists — hyphens for unordered, numbers for ordered
Tables — | Column | Column | with | --- | separating the header

CommonMark vs GitHub Flavoured Markdown

CommonMark is the standardised specification. GitHub Flavoured Markdown (GFM) adds task lists, strikethrough with ~~text~~, auto-linked URLs, and syntax-highlighted fenced code blocks. This previewer supports GFM-compatible syntax.

Markdown editors and tools

Many popular tools are built on Markdown. Choosing the right editor depends on your use case: writing, coding, note-taking, or publishing.

VS Code — built-in Markdown preview (Ctrl+Shift+V); supports Mermaid diagrams via extensions
Obsidian — local-first note-taking with linking, canvas, and plugin ecosystem
Typora — WYSIWYG Markdown editor; renders formatting inline as you type
HackMD/HedgeDoc — real-time collaborative Markdown editing in the browser

Markdown for technical documentation

Markdown has become the dominant format for software documentation, README files, and API references. Tools like Docusaurus, MkDocs, and GitBook build entire documentation sites from Markdown files. The combination of simple syntax, version control compatibility (Git diffs work cleanly on Markdown), and wide platform support makes it the practical choice for technical writing.

GitHub README — rendered automatically on repository landing pages; the first thing developers see
API documentation — OpenAPI/Swagger uses Markdown in description fields for formatted endpoint documentation
Changelog format — keepachangelog.com defines a Markdown-based convention for tracking version history
Pull request templates — .github/pull_request_template.md provides Markdown prompts for PR descriptions

Frequently Asked Questions

What is Markdown used for?

Markdown is used for writing documentation, README files, blog posts, forum comments, and notes. It lets you format text using simple symbols without writing HTML. GitHub renders Markdown in README files, wikis, and pull request comments automatically.

What is the difference between Markdown and HTML?

HTML uses verbose angle-bracket tags like <strong>bold</strong>. Markdown uses symbols like **bold** that are faster to type and easier to read in their raw form. Markdown is converted to HTML for display, so they produce the same output but Markdown is quicker to write.

How do I add a table in Markdown?

Separate columns with pipe characters and add a row of dashes under the header: | Name | Age | then | --- | --- | then | Alice | 30 |. Colons in the divider control alignment: :--- left, ---: right, :---: centre.

Can Markdown contain HTML?

Yes. Most Markdown parsers allow raw HTML inline. This is useful for elements Markdown does not support natively, such as <details> collapsible sections. However, HTML in Markdown may be stripped by some platforms for security reasons.

How do I escape Markdown characters?

Prefix the character with a backslash: \* shows a literal asterisk instead of triggering italic. This works for: \ ` * _ { } [ ] ( ) # + - . !