The Markdown text format makes it easy for people—not only software developers but anyone with a keyboard—to write text that can be converted readily into HTML or another rich format. What’s special about Markdown is it uses plain-text syntax for formatting, so it’s easy to tell at a glance what Markdown-formatted text might look like when it’s rendered.
Markdown’s overall ease of use and simplicity have led to broad adoption in many spaces. Bloggers were the original use case, using it to write their posts and adorn them with links or markup without needing a WYSIWYG editor. Many developers use Markdown or another variant to write their documentation. All anyone needs to get started is a text editor.
The history of Markdown
Technology blogger John Gruber, keeper of the Apple-centric blog daringfireball.net, created Markdown in 2004 in collaboration with Aaron Swartz.
Email and USENET posts written in plain text had long had their own culture of ad hoc formatting, such as using *asterisks* or _underscores_ for emphasis. But those textual hints weren’t rendered as HTML; they just provided a visual suggestion of what the markup might look like. Gruber and Swartz took things a step further by using that kind of plain-text markup to generate formatted output. The collaborators also took inspiration from the reStructuredText language, which was released in 2002 or so.
Markdown’s first incarnation was a Perl script that could be used standalone or integrated into other software, such as a blog’s publishing pipeline or a text filter for a message board like BBEdit. It still exists in this format, but countless other languages now have Markdown libraries.
Basic Markdown syntax
Markdown documents are essentially plain text. They can be ASCII or UTF-8, as all the important formatting is ASCII. To generate formatted output, you simply feed the Markdown document into a processor script, like the Perl script I mentioned above.
Plain text renders as-is, but certain character sequences cause text to be formatted either as block or inline elements.
This is plain text.
Single line breaks are treated as normal whitespace, while double line breaks indicate a paragraph break:
These two lines
would be considered a single paragraph.
This double-linebreak separated section would be its own paragraph.
For text emphasis, you can use asterisks and underscores, or other symbols:
- Italics:
*Italics* - Bold:
**Bold** - Strikethrough:
~~Strikethrough~~
(Note that the strikethrough syntax is not universally supported.)
Headers in a document (the HTML equivalent of H1 through H5) can be rendered by placing hash marks at the start of a line:
# Main heading
Text
## Subheading
More text
These would render the following HTML:
Main heading
Text
Subheading
More text
To create a horizontal rule, you’d simply type --- or === on a line by itself.
Inline links use a []() construction to separate the link’s text and URL, like so:
[the InfoWorld homepage](https://infoworld.com).
Many Markdown variants also support an angle-bracket URL format—e.g., —but without a separately formatted text label.
Inserting an image inline works similarly, with a “bang”-prefixed version of a link: . For just the image with no title metadata, use: .
For indented blocks or blockquotes, place a > at the start of a paragraph:
Regular text
> Indented block
>> Double-indented block
More regular text
Code-formatted text uses blocks fenced off with three backticks:
```
test
```
Unordered lists use *, +, or - to start a line, with indents used to indicate levels:
* Key concept
* Sub-concept
* Another sub-concept
* Another key concept.
For numbering, you can use any digit followed by a period, as the Markdown renderer will automatically renumber everything:
0. First item
0. Second item
0. Third item
Finally, you can insert HTML manually if you want. However, the Markdown renderer may consider an area with manually provided HTML to be exempt from its own rendering. For instance:
This may *not* render as intended.
Some Markdown renderers may try to apply Markdown formatting between HTML tags, but others may ignore it. So in some cases, you’d get italics for the above source, whereas in others you’d get literal asterisks.
Regardless of what you are trying to do with Markdown, even a glance at the original, unformatted text provides a sense of how the formatted product is intended to look.
Use cases for Markdown
The original use case for Markdown was blogging. It was an alternative for bloggers or message board users who wanted to render rich text but avoid writing HTML by hand (including HTML-esque variants like BBCode) or using a WYSIWYG editor to generate markup.
Blogging and text posting in general remain popular applications for Markdown. Messaging systems like Discord and Slack use Markdown (with some gratuitous changes) to allow users to post rich, annotated text or include links or images.
A common use case for Markdown is project documentation. A simple README.md is easy to assemble with Markdown, and the standard supports more than enough formatting syntax for such a job. For larger, more complex documentation jobs, Markdown can also suffice, and while there’s criticism about how well it scales, many documentation tools, such as Mkdocs, use Markdown as a core format. Various Markdown-inspired variants (described below) add custom features to the Markdown standard to make it more useful for generating documentation.
Markdown is also a suitable base format for a wiki. Wiki formatting generally follows the same philosophy as Markdown: a plaintext format with annotations that can be visually parsed. Most wiki implementations of Markdown also extend the standard—for instance, to allow transclusion of documents, or by using a template for formatting.
Limitations of Markdown
The core Markdown standard (which for a long time was just a de facto standard) supports only a small handful of formatting options. That’s in large part a reflection of its original use cases. It wasn’t intended to be a one-to-one HTML-generation tool, but a way to quickly write things that used the most common and broadly supported HTML elements.
Markdown is a focused and concise standard, with the tradeoff of many things being completely missing. Here are some of the things you can’t render with the core Markdown standard:
- Tables: Various gratuitous extensions for Markdown support table formatting, typically by using the pipe symbol (
|) to define table columns. However, the implementations aren’t consistent, and the core Markdown implementation has no table syntax. - Footnotes or endnotes: Even on a simple webpage, some automatic way to define footnotes or endnotes in text can be useful. Markdown offers no native way to do this.
- Metadata or variables: Markdown has no native mechanism for defining document-level metadata or even inline comments. A manually inserted HTML comment block could hold data, but by itself, Markdown has no way to do anything useful with it; it would just get converted to HTML along with everything else, and not necessarily stripped from the output.
- Control over CSS classes or styles: If you have a block of text you want to apply a style to, the only way to do it is to enclose it in HTML tags; e.g.,
Markdown variants to explore
Because Markdown is at heart fairly minimal, variations on the original syntax have sprung up over the years. They weren’t intended to eclipse or replace Markdown, but to flank it. These variants offer a syntax that starts with Markdown and builds useful features on top of it.
CommonMark
CommonMark is meant to be a “strongly defined, highly compatible specification of Markdown.” It takes the core Markdown syntax and formalizes it to create a specification, reference implementations, a test suite, and a number of other tools. It doesn’t define any extensions on the standard, only an unambiguous description of it, and ways to create tools that conform to the standard.
GitHub-Flavored Markdown
A broadly adopted variant of Markdown is GitHub-flavored Markdown, so named both because GitHub developed it and because many of its features complement use cases on GitHub. The specification expands on CommonMark to add tables, task-list items (for example, for creating to-do lists), and a mechanism for disabling raw HTML tags that might be problematic (such as ).
MultiMarkdown
Like GitHub-Flavored Markdown, the MultiMarkdown project expands on the base Markdown syntax but adds features commonly used in documents like scientific papers or books, such as tables, footnotes, citations, cross-references, and LaTeX math formulae.