What Is Markdown? Syntax, Uses & Why Writers Love It

Markdown is a lightweight markup language for formatting plain text with simple symbols: # for a heading, **text** for bold, - for a list item. A Markdown file stays readable as plain text, and tools convert it to HTML, PDF and other formats. It is the default writing format on GitHub, in documentation sites, note apps and many chat tools.

One of my friends told me about Markdown a few years ago. At first I thought it would be boring, but once I started writing in it, I didn’t want to go back. This guide covers what Markdown is, how it differs from HTML, the syntax you will use every day, the main “flavours”, and why it is such a good choice for notes, documentation and blog drafts. It also covers one security point that many introductions get wrong.

What Is Markdown?

John Gruber created Markdown in 2004, with feedback from Aaron Swartz, as “a text-to-HTML conversion tool for web writers”. The goal was a format that is easy to read and write as it is, without looking like it has been marked up with tags. You write:

## Shopping list

Buy **fresh** coffee and *maybe* milk.

- Coffee beans
- Milk
- [Recipe link](https://example.com/cold-brew)

and a Markdown processor turns it into HTML:

<h2>Shopping list</h2>
<p>Buy <strong>fresh</strong> coffee and <em>maybe</em> milk.</p>
<ul>
<li>Coffee beans</li>
<li>Milk</li>
<li><a href="https://example.com/cold-brew">Recipe link</a></li>
</ul>

Markup vs Markdown: Are They the Same?

Not quite, although they do the same job. Markup is the general idea of annotating text to describe its structure; HTML is the best-known markup language, using tags like <h1>, <p> and <div>. Markdown is itself a (lightweight) markup language whose name is a pun on “markup”. It covers the most common formatting with plain-text symbols and is usually converted to HTML for display.

If you want a refresher on the HTML side, see what HTML5 is and how a page is structured.

Markdown Syntax Cheat Sheet

A fenced code block looks like this:

```js
console.log('Hello, Markdown');
```

For the full syntax, the Markdown Guide cheat sheet is a good reference.

Markdown Flavours: CommonMark and GitHub Flavored Markdown

Gruber’s original description left some cases ambiguous, so different tools rendered the same text differently. Two specifications fixed most of that:

• CommonMark is a precise, tested specification of core Markdown (version 0.31.2 at the time of writing).
• GitHub Flavored Markdown (GFM) builds on CommonMark and adds tables, task lists, strikethrough and automatic links. It is what you write in README files, issues and pull requests.

Many tools add their own extensions on top, such as Obsidian’s [[wiki links]], footnotes, or math with $...$. If a document has to work in several tools, stick to CommonMark and GFM features.

Why Choose Markdown?

• It’s fast to write. Your hands stay on the keyboard; there are no toolbar buttons or tags to close.
• It’s readable as is. Even unrendered, a Markdown file is easy to read, which also makes changes easy to review in Git.
• It’s portable and future-proof. Markdown files are plain text. Any editor on any operating system can open them, today and in 20 years, and you can move between apps without being locked into a proprietary format like a word processor document.
• It works with version control. Plain text diffs cleanly, which is why documentation teams write “docs as code” in Markdown and review it in pull requests.
• It converts to almost anything. Tools like Pandoc turn Markdown into HTML, PDF, Word, EPUB and slides.
• It’s everywhere. GitHub, GitLab, Reddit, Discord, Slack (in a simplified form), Jupyter notebooks, static site generators, and most note-taking and documentation tools support it.
• It’s distraction-free. You focus on the words and structure, and leave the styling to whatever renders it.

That combination is why Markdown is the default for technical writing. If you write documentation, see how to structure developer docs with the Diátaxis framework.

Where You Can Use Markdown

Markdown Editors

You can write Markdown in any text editor. Dedicated editors add live preview, shortcuts and export:

• Visual Studio Code: built-in Markdown preview (Ctrl+Shift+V, or Cmd+Shift+V on a Mac).
• Obsidian: a free note-taking app built on local Markdown files, with links between notes. Its formatting syntax guide is a clear introduction.
• Typora and iA Writer: focused writing apps that render formatting as you type.
• Online: GitHub’s editor has a preview tab, and tools like StackEdit and Dillinger run in the browser.

Does Markdown Protect You from XSS?

One reason sites adopted Markdown for comments and user posts was to avoid letting users write raw HTML, because raw HTML can carry cross-site scripting (XSS): an attacker injects script into a page, and it runs in other visitors’ browsers. OWASP describes how XSS can steal session cookies, change page content or send users to malicious sites.

But Markdown on its own does not prevent XSS. Standard Markdown allows raw HTML inside it, and most parsers output links as written. I tested this with marked 18.1, a popular JavaScript Markdown parser, by feeding it a malicious comment:

import { marked } from 'marked';
import DOMPurify from 'dompurify';
import { JSDOM } from 'jsdom';

const purify = DOMPurify(new JSDOM('').window);

const comment = `Nice post! **Thanks** for sharing.

<img src="x" onerror="alert('stolen cookies')">

[Click me](javascript:alert('xss'))`;

const unsafe = marked.parse(comment);
const safe = purify.sanitize(unsafe);

The output of marked.parse still contained the onerror script and the javascript: link:

<p>Nice post! <strong>Thanks</strong> for sharing.</p>
<img src="x" onerror="alert('stolen cookies')"><p><a href="javascript:alert(&#39;xss&#39;)">Click me</a></p>

After passing it through DOMPurify 3.4, the dangerous parts were removed and the formatting kept:

<p>Nice post! <strong>Thanks</strong> for sharing.</p>
<img src="x"><p><a>Click me</a></p>

So if your site renders Markdown that other people write, always sanitize the resulting HTML (or use a renderer configured to strip raw HTML and unsafe URLs). For Markdown you write yourself, this isn’t a concern.

How to Start Writing Markdown

1. Create a file ending in .md in any editor.
2. Write a heading with #, a few paragraphs separated by blank lines, and a list.
3. Open the preview in your editor, or paste it into a GitHub issue or gist and click Preview.
4. Learn the rest as you need it: links, images, code blocks and tables cover almost everything.

Conclusion

Markdown gives you formatted documents while you type plain text. It is quick to learn, readable without rendering, works with Git, converts to almost any format and is supported almost everywhere developers and writers work. Learn the dozen symbols in the cheat sheet above, stick to CommonMark and GFM for portability, and sanitize the output whenever you render Markdown from other people.

FAQs