Markdown is plain text that uses punctuation as formatting. A hash sign makes a heading. Asterisks around a word make it bold. A hyphen starts a list item. A parser turns those marks into HTML. The source file stays ordinary text: a few kilobytes, readable in any editor, on any operating system.
That double life is why it escaped the software world it was born in. READMEs, issue trackers, blogs, documentation portals, note apps such as Obsidian, chat clients and AI assistants all speak it. About a dozen symbols are worth learning. You can practise every one of them in the free editor, with the rendered result updating beside you as you type.
At a glance
| Created | 2004, by John Gruber with Aaron Swartz |
|---|---|
| What it is | A formatting syntax for plain text |
| File extension | .md, or the longer .markdown |
| Converts to | HTML, in the browser or on a server |
| Time to learn | About 30 minutes for everyday syntax |
Where Markdown came from, and why it won
- You type marks like
#,**and-, and a parser turns them into headings, bold text and lists. - The syntax has barely moved since 2004, so a file written then still parses now.
- The core travels everywhere. Tables and checkboxes depend on where you paste them.
- Almost every beginner problem is a missing space or a missing blank line.
John Gruber created Markdown in 2004 with Aaron Swartz. They were attacking one problem: HTML suits browsers, not people. Typing <strong>important</strong> interrupts your train of thought every single time.
Their design rule was strict. A document had to read well as plain text, before any conversion. So the marks came from plain-text email: asterisks for emphasis, hyphens for lists, > for a quote. There was almost nothing new to learn. That familiarity is why it won.
A 30-second worked example
Here is a tiny but complete Markdown document. The raw text is what you type. The formatted page is what your reader sees.
# Trip notes
Packing list for **Taipei**:
- Passport
- EasyCard
- Camera
Weather forecast is [here](https://example.com).
What each mark turns into
- The
#line becomes an<h1>, the top-level heading of the page. - The double asterisks become
<strong>, so Taipei arrives in bold. - The three hyphen lines collapse into one
<ul>holding three<li>items. The browser draws the bullets and the indent. - The square brackets and parentheses become a link. Readers see the word "here", and the address stays tucked away in the source.
Structure, not styling
Notice what did not happen. Nothing was styled. Markdown describes structure, not appearance. The size of that heading and the colour of that link come from the destination's stylesheet, never from your file.
Tip: Paste the snippet into the editor and change one character at a time. Delete the space after the # and watch the heading fall back to ordinary text. Ten seconds of that teaches more than a page of rules.
Where Markdown actually renders today
The core is safe almost anywhere
Markdown became a standard by popularity, not by committee, so support is wide but uneven. Headings, emphasis, links, lists, quotes and code behave the same almost everywhere you paste them. The extensions each platform added later are where behaviour splits. Twenty years on, the core is the default writing layer of the technical world.
Support, platform by platform
| Platform | Headings & lists | Tables | Task lists | Notes |
|---|---|---|---|---|
| GitHub / GitLab | Yes | Yes | Yes | The reference behaviour most people compare against |
| Stack Overflow | Yes | Yes | No | Fenced code blocks are the most used feature |
| Yes | Yes | No | Older and newer interfaces differ in places | |
| Discord | Yes | No | No | Inline marks plus headings, no block layout |
| Slack | No | No | No | Bold, italic, strikethrough, quotes and code only |
| Notion | Yes | Partial | Yes | Typing the marks converts text into native blocks |
| Obsidian | Yes | Yes | Yes | Your notes are stored as real .md files on disk |
| VS Code preview | Yes | Yes | Yes | Built in, no extension required |
Tip: Stick to the core and your text moves between all eight of those platforms untouched. Reach for a table or a checkbox and you have chosen a destination. Which Markdown flavor the editor supports names the dialect rendered on this site.
The three mistakes every beginner makes
Almost every "my Markdown did not work" moment has one cause. The syntax cares about spaces and blank lines, and a word processor never does. This short file makes all three classic mistakes at once:
#Trip notes
Packing list:
- Passport
- EasyCard
Leaving Monday.
Back Friday.
Why nothing rendered
- No heading. A
#needs a space after it. Without the space, the whole line stays literal text. - The list gets swallowed. A bullet list needs a blank line above it, or it joins the paragraph before it.
- Two sentences, one line. A single newline inside a paragraph counts as a space, not as a break.
The same file, corrected
# Trip notes
Packing list:
- Passport
- EasyCard
Leaving Monday.
Back Friday.
Watch out: Blank lines are how Markdown marks the end of one block and the start of the next. When a page renders as one grey slab, add a blank line before you try different punctuation. To break a line inside a paragraph, end it with two spaces or write <br>.
How it compares to Word and raw HTML
Against a word processor
Markdown trades buttons for portability. A .docx file needs particular software, and it can mangle its own formatting between versions. A .md file is plain text. It opens on anything, it diffs cleanly in version control, and it does not corrupt.
Against raw HTML
These two are not rivals, because Markdown's output is HTML. Markdown is simply faster to write and far easier to read back. Anything the syntax cannot express falls through to raw HTML, which you can type straight into the file. That escape hatch is why the language stayed small. Our Markdown vs HTML comparison covers when each one fits.
What Markdown will not do
- No page layout, no columns, no text boxes
- No tracked changes and no comment threads
- No fonts, colours or type sizes chosen by you
A designed brochure belongs in other software. A document you still want to open in ten years belongs here.
Where to go from here
Most people learn the whole everyday syntax in under thirty minutes. This route works:
- Read the plain-language introduction for the full story.
- Work through the complete Markdown guide, one element at a time.
- Keep the cheat sheet open in a tab while you write.
- Retype the trip-notes example above, then break it on purpose and watch what happens.
Tables are usually the next thing people want, and the tables guide covers alignment and the traps in depth. Everything on this site is free, which the pricing answer explains without a catch.
Related questions
Try the Editor
Open Editor