What Is Markdown? A Plain-English Guide With Examples

Markdown in one example

Markdown lets you add structure to text with simple punctuation, while the file itself stays readable as plain text. On the left is what you type; on the right is what a Markdown viewer shows.

# Weekend plan

Visit the **farmers market**, then *maybe* a hike.

- Buy bread
- Buy tomatoes
- Pack water

Route notes are on [the trail site](https://example.com).

The RFC that registers Markdown as an internet media type describes it as “a family of plain-text formatting syntaxes that optionally can be converted to formal markup languages” such as HTML.

What is a .md file?

A .md (or .markdown) file is a Markdown document saved as plain text. RFC 7763 registers both extensions and states that “Markdown content is plain-text content.” That means any text editor can open it — you’ll just see the symbols instead of the formatting. The most famous .md file is README.md, the front page GitHub shows for a project.

To see an .md file formatted on your device, follow how to open an .md file.

Where Markdown came from

• 2004 — John Gruber creates Markdown. His project page says Aaron Swartz “deserves a tremendous amount of credit for his feedback on the design of Markdown’s formatting syntax.” The goal, in Gruber’s words: “The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible.” The page lists Markdown 1.0.1, dated 17 December 2004, as the download.
• Many flavors appear. CommonMark’s authors point out that Gruber’s description “does not specify the syntax unambiguously,” so different tools handled edge cases differently.
• 2014 — CommonMark. A group including John MacFarlane and Jeff Atwood set out to write “a standard, interoperable and testable version of Markdown.” Its spec’s latest listed version is 0.31.2, from January 2024.
• 2016 — Internet media type. RFC 7763 registers text/markdown; RFC 7764 registers variants including CommonMark and GitHub Flavored Markdown.
• 2017 — GitHub adopts CommonMark. GitHub enabled CommonMark rendering for comments, then for Markdown content stored in Git repositories, and published a formal GFM spec.

Flavors: CommonMark, GFM, and the rest

Everyday syntax — headings, bold, lists, links, code — works the same almost everywhere. Differences appear in extras like tables, task lists, and diagrams. That’s why a README can look slightly different on GitHub than in another tool; see our GitHub Markdown troubleshooting guide.

Where Markdown is used

It is also common in AI chat tools, which often reply with Markdown; Google’s October 2026 announcement of native Markdown support in Drive and Docs notes that Markdown is widely used with LLMs because it keeps structure such as tables, headers, and lists. If an AI answer is full of symbols, paste it into a Markdown viewer to read it formatted.

Markdown vs HTML

Markdown doesn’t try to replace HTML. Gruber’s syntax page puts it this way: “HTML is a publishing format; Markdown is a writing format,” and “Markdown’s formatting syntax only addresses issues that can be conveyed in plain text.” Most tools convert Markdown to HTML for display, and many allow raw HTML inside a Markdown file for anything Markdown can’t express.

The basics in 60 seconds

That’s enough to write a README or a note. For every other piece of syntax — tables, footnotes, alerts, and more — use the universal Markdown cheat sheet on MDConverter.

How to view and edit Markdown

• In your browser, with nothing to install: MarkdownPreview.net shows a live preview as you type, or opens a .md file you drop in.
• On GitHub: test a README before you push with the GitHub Markdown preview, or start one from the README generator.
• In your editor: see VS Code or 15 other editors.
• In Google Docs: Markdown in Google Docs and Drive.

Frequently asked questions

Sources

• Daring Fireball — Markdown (project page, John Gruber) — authorship, credit to Aaron Swartz, readability goal, version 1.0.1
• Daring Fireball — Markdown Syntax Documentation — readability emphasis and the relationship to HTML
• CommonMark — home page — why CommonMark exists
• CommonMark Spec (John MacFarlane) — version history; latest 0.31.2
• Coding Horror — Standard Markdown is now Common Markdown (Sept 2014)
• GitHub Flavored Markdown Spec — version 0.29-gfm; a strict superset of CommonMark
• GitHub Blog — A formal spec for GitHub Flavored Markdown (Mar 2017)
• RFC 7763 — The text/markdown Media Type
• RFC 7764 — Guidance on Markdown: Design Philosophies, Stability Strategies, and Select Registrations — registered variants
• GitHub Docs — About writing and formatting on GitHub
• GitHub Docs — About READMEs
• GitLab Docs — GitLab Flavored Markdown
• VS Code Docs — Markdown and Visual Studio Code
• Hugo Docs — Content formats
• Jekyll Docs — Writing posts
• Jupyter Docs — Working with Markdown cells
• Stack Overflow Blog — Inline comment and post Markdown help (2011)
• Obsidian Help — Basic formatting syntax