Markdown: What It Is and How to Use It

Markdown is a simple way to format plain text. You put ** around a word to make it bold, start a line with # to make it a heading, and start lines with - to make a list. A Markdown processor turns that into HTML, or into a PDF, a Word document, or a slide deck. The text is easy to read even if nobody ever converts it, and that’s the whole point.

Compare that to HTML, where the tags get in the way of the text: <strong>bold</strong> versus **bold**. Markdown is what you type in a GitHub README, in your notes app, in Discord, and in many blog editors. It’s also what AI chat tools write their answers in. On this site I explain it in plain English, with examples you can copy.

What Markdown looks like

Here’s a short piece of Markdown, exactly as you’d type it:

Markdown is **easy** to read and *quick* to write.

Things I use it for:

- README files on GitHub
- Notes and to-do lists
- Blog posts like this one

> Tip: a `>` at the start of a line makes a quote.

Learn the rest in the [cheat sheet](https://markdown.land/markdown-cheat-sheet).

And this is what it looks like after conversion:

The most common elements fit in one small table:

Element	You type	You get
Heading	## Heading	A level-2 heading
Bold	**bold**	bold
Italic	*italic*	italic
Link	[Markdown Land](https://markdown.land)	Markdown Land
Inline code	`code`	code
List item	- item	A bullet point
Image		An image

That’s honestly most of it. The Markdown cheat sheet covers everything else, from tables to footnotes.

Where Markdown is used

Markdown started as a way to write for the web, but in 2026 you run into it almost everywhere you type text:

• Code hosting: GitHub, GitLab, and Bitbucket render Markdown in README.md files, issues, pull requests, wikis, and comments.
• Documentation and websites: static site generators like Hugo, Jekyll, Eleventy, and Astro build entire websites from folders of Markdown files.
• Notes: Obsidian stores every note as a plain .md file on your disk, Bear is built around Markdown, and Notion and Google Docs can import and export it.
• Chat and communities: Discord and Reddit support Markdown formatting. Slack has its own Markdown-like syntax (one asterisk for bold instead of two).
• Blogging: the WordPress editor understands Markdown shortcuts and converts pasted Markdown into blocks.
• Data and code: Jupyter notebooks use Markdown cells for text between the code, and SQLite can even print query results as a Markdown table.
• AI tools: ChatGPT, Claude, Gemini, and similar chat tools answer in Markdown, which the app then renders. That’s why AI answers are full of headings and bullet points. Some websites now also publish an llms.txt file: a Markdown summary of the site meant for language models.

So it pays to know the syntax, and luckily it’s simple. Most people pick up the basics in an afternoon.

Start learning Markdown

This is the order I’d read the articles on this site in:

1. Markdown cheat sheet: all the basic syntax on one page, with examples. Start here.
2. Markdown tables: tables have enough quirks (alignment, pipes in cells, line breaks) to deserve their own article.
3. Markdown code blocks: inline code, fenced code blocks, and syntax highlighting. Essential if you write technical docs.
4. Centering in Markdown: how to center text, images, and tables, including what actually works on GitHub. One of the most common questions I get.
5. README.md files: what goes in a good README and how GitHub displays it.
6. Markdown in WordPress: the editor’s Markdown shortcuts, pasting Markdown, and plugins.
7. SQLite Markdown output: turn query results into Markdown tables straight from the command line.
8. Markdown images: insert, resize, and align images, plus captions, GIFs, and videos.
9. Markdown line breaks: why pressing Enter does nothing, and the three ways to fix it.
10. Markdown alerts: note, tip, and warning boxes on GitHub, and callouts elsewhere.
11. Comments in Markdown: hide notes in your files that don’t show up on the page.

Markdown flavors

There isn’t one Markdown. The original description left a lot of details open, so different tools filled in the gaps differently. These are the flavors you’ll actually run into:

Flavor	What it is	Where you’ll meet it
CommonMark	A precise specification of the core syntax, with a test suite, so every parser gives the same result	The base for most modern Markdown parsers
GitHub Flavored Markdown (GFM)	CommonMark plus tables, task lists, strikethrough, and automatic links	GitHub, and many tools that copy its behavior
MultiMarkdown	Adds footnotes, tables, citations, and document metadata	Writing apps and longer documents
Pandoc Markdown	The most extended flavor, built for converting to Word, PDF, LaTeX, EPUB, and more	Academic writing, books, document conversion
MDX	Markdown that can include JSX components	Documentation sites built with React

My advice: learn CommonMark and the GFM extensions. That covers GitHub, GitLab, most note apps, and most static site generators. GitHub itself adds a few extras on top of GFM, like footnotes, alerts (> [!NOTE]), and Mermaid diagrams. I cover those in the README.md article.

A short history of Markdown

John Gruber created Markdown in 2004, with Aaron Swartz as his main collaborator on the syntax. It came as two things: a description of the syntax, and a Perl script that converted it to HTML.

The idea was to write the way people already formatted plain-text email: asterisks around a word for emphasis, a > in front of a quoted line, dashes for a list. The source should look fine as it is, and convert to HTML without surprises.

Markdown spread fast, but the original description was informal and left many edge cases undefined. How do you nest a list? What happens to a blank line inside a list item? Every implementation answered those questions a bit differently, so the same text could render differently on two sites.

In 2014 a group of developers published CommonMark to fix that: a strict specification with hundreds of examples to test parsers against. It was first announced as “Standard Markdown” and renamed after Gruber objected to the name. In 2017, GitHub published its own spec, GitHub Flavored Markdown, as a set of extensions on top of CommonMark. Today almost every serious Markdown parser follows CommonMark.

Markdown file extension and MIME type

Markdown files use the extension .md, and sometimes .markdown. The file you’ll see most is README.md at the top of a code repository. If you want to know what goes in one, read my guide to README.md files.

The official media type (MIME type) is text/markdown, registered in 2016 in RFC 7763. The charset parameter is required, and an optional variant parameter tells the receiver which flavor you meant:

Content-Type: text/markdown; charset=UTF-8; variant=GFM

FAQ

What is Markdown used for?

Mostly for writing formatted text without a word processor: README files and documentation, notes, blog posts, comments on sites like GitHub and Reddit, and chat messages. Static site generators turn folders of Markdown files into complete websites.

Is Markdown a programming language?

No. Markdown is a markup language, like HTML. It describes how text should be formatted, but it has no logic, variables, or loops.

What’s the difference between Markdown and HTML?

Markdown is a shorthand that gets converted into HTML. It covers the common things (headings, emphasis, links, lists, images) with far less typing. HTML can do everything, and most Markdown flavors let you mix in HTML tags for the parts Markdown can’t express.

How do I open a .md file?

Any text editor opens it, because it’s plain text. To see it formatted, use an editor with a Markdown preview (VS Code has one built in), a note app like Obsidian, or push it to GitHub, which renders .md files automatically. I explain every option, per device, in how to open an .md file.

Which Markdown flavor should I learn?

Start with CommonMark plus the GitHub Flavored Markdown extensions (tables, task lists, strikethrough). The cheat sheet tells you when something only works on GitHub or on specific platforms.