What Is Markdown?

Plain text that becomes a document

Markdown is a lightweight markup language. You write plain text: characters only, with no hidden formatting codes, fonts or colors stored in the file, the kind of file any text editor can open. A few punctuation marks carry meaning: a line that starts with # is a heading, words between ** are bold, lines that start with - form a list.

Compare that with the two alternatives most people know. A word processor such as Word stores formatting in a binary or XML format that you cannot read without the program. HTML is plain text too, but its tags (<h1>, <strong>, <li>) get in the way of reading. Markdown sits in between: the file stays readable as it is, and a program can still turn it into a properly formatted page.

Its creator, John Gruber, put the design goal like this:

"The overriding design goal for Markdown's formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it's been marked up with tags or formatting instructions."

Many of the conventions were borrowed from how people already formatted plain-text email: asterisks around a word for stress, a hyphen at the start of a line for a list, > for a quoted reply. A short reply in that style is already valid Markdown:

> Is the portal down for everyone?

Not for everyone: only customers in the *north* region.
Workaround:

- log in via the app
- or call the service desk

<blockquote>
<p>Is the portal down for everyone?</p>
</blockquote>
<p>Not for everyone: only customers in the <em>north</em> region.
Workaround:</p>
<ul>
<li>log in via the app</li>
<li>or call the service desk</li>
</ul>

A first example

Here is the start of an outage update as Mei Chen, the service desk lead at Kestrel Energy, might write it. Every example in this topic shows three things: the Markdown you type, the HTML a renderer produces from it, and the result as a browser shows that HTML.

# Outage update

Power is **back** in *Deventer* since 14:20.

## What we know

- Cause: a faulty cable joint
- Affected: about 1,200 addresses
- Next update: 16:00

See the [status page](https://status.example.com) for details.

<h1>Outage update</h1>
<p>Power is <strong>back</strong> in <em>Deventer</em> since 14:20.</p>
<h2>What we know</h2>
<ul>
<li>Cause: a faulty cable joint</li>
<li>Affected: about 1,200 addresses</li>
<li>Next update: 16:00</li>
</ul>
<p>See the <a href="https://status.example.com">status page</a> for details.</p>

The HTML, and the formatted page the browser draws from it, is the rendered output: what the reader sees after the Markdown has been converted. The source and the rendered output carry the same structure: one level-1 heading, a paragraph with emphasis, a level-2 heading, a list and a link. Notice that even the raw Markdown is easy to read in an email or a terminal; that is the whole point.

From text to page: rendering

A Markdown file on its own is just text. A Markdown renderer is the program or library that reads Markdown and converts it into another format, usually HTML. GitHub has one built into every page that shows a README; your editor uses one for its preview; a static site generator uses one to build a documentation site. Internally the work happens in steps:

1. The parser reads the text and recognizes the structure: first the blocks (headings, paragraphs, lists, code blocks), then the inline parts inside them (emphasis, links, code).
2. The result is a tree that says, for example, "a document with a heading and a paragraph; the paragraph contains text and a bold part".
3. The renderer walks the tree and writes HTML. Another renderer can write a different format from the same tree, such as a Word file or a PDF.
4. The browser displays the HTML, styled by whatever CSS the site uses. That is why the same README looks different on GitHub, in your editor and on a documentation site: the HTML is similar, the styling is not.

One consequence is easy to miss: Markdown never produces an error. If you mistype a heading, you do not get a message; the renderer simply treats the line as ordinary text. You only notice by looking at the result, so always preview what you write. Here the space after # is missing on the first line, and the second line uses a symbol that this renderer does not know:

#Planned maintenance

==Saturday== 22:00–02:00

<p>#Planned maintenance</p>
<p>==Saturday== 22:00–02:00</p>

Both lines come out as ordinary paragraphs, with the symbols left in. (==highlight== does work in some note apps, which is exactly the kind of difference between tools you will keep meeting.) The details of parsers and conversion tools are on Converting Markdown.

Where it came from

Markdown was created by John Gruber in 2004, in collaboration with Aaron Swartz, who gave detailed feedback on the syntax. Gruber published two things under the name: a description of the syntax on his website, and Markdown.pl, a Perl script that converted it to HTML. The last version, 1.0.1, dates from 17 December 2004; it has not been updated since.

The idea spread quickly, but the description was written for people, not as a precise rule book. It left many cases open: how far must a nested list be indented? Does an underscore inside a word start italics? Every new implementation answered those questions its own way, and documents started to look different from one program to the next.

In 2014 a group of people from GitHub, Stack Overflow, Reddit, Discourse, Meteor and the Pandoc project started writing an exact specification with hundreds of test examples. It was first announced as "Standard Markdown"; Gruber objected to the name, and the project became CommonMark. As of 2026 the latest version of the CommonMark specification is 0.31.2, from January 2024; there is no version 1.0 yet, but GitHub, GitLab, Stack Overflow, Reddit, Discourse and many tools follow it.

Most platforms add their own extensions on top, such as tables and checklists. GitHub's version, GitHub Flavored Markdown, is the one you will meet most in IT. How the variants relate is explained on Markdown Flavors: CommonMark, GitHub Flavored Markdown and Others.

Where you will meet Markdown

Once you know the syntax, you will see it nearly everywhere in IT work:

For service desk and operations work this matters in a very practical way. A runbook in Markdown can live next to the scripts it describes, be reviewed like code and still be read in an emergency from a plain terminal. That way of working, documentation as files in version control, is described under docs-as-code.

Markdown files

A Markdown file is a plain text file that holds Markdown, normally with the extension .md; .markdown is the longer alternative, and some tools also accept .mdown or .mkdn. The extension is how GitHub, editors and site generators know that they should render the file instead of showing it as plain text. Files ending in .mdx are a different format (Markdown mixed with JavaScript components), not plain Markdown.

portal/
├── README.md              ← shown on the repository's home page
├── CHANGELOG.md
└── docs/
    ├── runbooks/
    │   └── restart-portal.md
    └── architecture.md

A few habits keep Markdown files trouble-free:

• Save as UTF-8. Markdown itself does not prescribe an encoding, but the registered media type text/markdown (RFC 7763) requires a charset to be stated, and in practice tools expect UTF-8. A different encoding can give garbled characters in names such as "Lucía".
• Use plain line endings. CommonMark accepts Windows (CRLF) and Unix (LF) line endings, but mixing them in one repository makes diffs noisy. Most teams settle on LF.
• End the file with a newline, as most editors do by default; linters check for it.

Because the format is plain text, version control works well with it. When Ravi Kumar changes one step in a runbook, the diff in Git shows exactly that one line, and a reviewer can comment on it. The same change in a Word document is a binary blob that Git cannot show.

Strengths and limits

Why so many teams choose Markdown:

• Readable everywhere. In a terminal, an email, a diff or a chat window, without any special software.
• Fast to write. No toolbar, no mouse: headings, lists and code are a few characters each.
• Portable and durable. A text file from 2004 still opens today, and no vendor owns the format.
• Convertible. The same source can become a web page, a PDF or a Word document.

And where it falls short:

• Little control over layout. Markdown describes structure, not appearance. There is no syntax for colors, font sizes, columns or text wrapped around an image.
• Flavors differ. Tables, checklists, footnotes and alert boxes are extensions that one tool supports and another does not.
• Complex content gets awkward. Tables with merged cells or multi-paragraph cells, and long documents with numbered figures and cross-references, need either raw HTML or a richer format.
• Not for every reader. Colleagues who never see the source may prefer a document editor; Markdown pays off when the text is edited by people who also work with code, tickets and version control.

Where Markdown has no syntax, the original idea was to fall back on HTML tags in the text. Whether that works depends on the renderer. Many renderers, including the one on this site by default, show the tags as text, because raw HTML from users is a security risk:

Status: <span style="color: red">down</span>

<p>Status: &lt;span style=&quot;color: red&quot;&gt;down&lt;/span&gt;</p>

Why that is, and how to allow HTML safely where you need it, is on HTML in Markdown and Safety.

What you need to start

Nothing beyond a text editor. To see the rendered result while you type, use one of these:

• Your code editor's preview. Visual Studio Code has a built-in Markdown preview (Ctrl+Shift+V, or Ctrl+K then V for a side-by-side view). It uses the same markdown-it library as the examples here.
• The "Preview" tab on GitHub and GitLab, next to every comment box and file editor.
• The CommonMark dingus at spec.commonmark.org/dingus, an online page that shows the HTML for any Markdown you type, according to the specification.

The next pages go through the syntax one building block at a time, starting with Headings, Paragraphs and Line Breaks.