WebBuilding

Languages and formats

Markdown

Summary

Markdown is a plain-text formatting syntax, and the original tool that converts it to HTML, created by John Gruber with help from Aaron Swartz and announced on March 15, 2004. Writers mark headings, emphasis, lists and links with ordinary characters such as # and *, and a converter turns the text into a web page. Many variants followed. The CommonMark specification (version 0.31.2, January 28, 2024) and GitHub Flavored Markdown were written to pin down its rules, and sites including GitHub, GitLab, Reddit and Stack Overflow have adopted CommonMark.

Web Building Encyclopedia · Languages and formats · Last reviewed October 22, 2026 · 10 min read

What Markdown is

Markdown is a way of writing formatted text using only plain characters that you can type on any keyboard. You put asterisks around a word to stress it, start a line with a hash sign to make a heading and start lines with hyphens to make a list. A program then turns that text into HTML, the code web pages are built from.1

The name covers two things. John Gruber, who created it, describes Markdown as both a formatting syntax for plain text and a software tool, written in Perl, that converts that text into structurally valid HTML.1 He calls the whole thing “a text-to-HTML conversion tool for web writers.”1

The design goal is that the text should read well before it is converted. Gruber’s syntax page puts readability ahead of every other aim, and names the plain text email as the biggest source of inspiration.2 A Markdown file opened in a basic text editor still looks like a tidy document, not like code.

Markdown files usually end in .md or .markdown.3 Since 2016 they have had a registered internet media type, text/markdown, which tells software what kind of file it is receiving.3

Origins: John Gruber and Aaron Swartz, 2004

Gruber announced Markdown on his website, Daring Fireball, on March 15, 2004. The first release worked as a plug-in for the Movable Type and Blosxom blogging tools, and as a standalone Perl script that could also run as a text filter inside the BBEdit text editor.4 It produced XHTML or HTML.4 XHTML is a stricter version of HTML written to the rules of XML.

Gruber credits Aaron Swartz for his help. His project page says Swartz “deserves a tremendous amount of credit for his feedback on the design of Markdown’s formatting syntax.”1 The page also thanks Nathaniel Irons, Dan Benjamin, Daniel Bogan and Jason Perkins for feedback.1 The CommonMark specification, written years later, likewise says Markdown was developed by Gruber with help from Swartz and released in 2004.5

Markdown borrowed from earlier plain-text formats. Gruber’s syntax page lists Setext, atx, Textile, reStructuredText, Grutatext and EtText as influences, and links atx to a page on Swartz’s website.2

The license changed in the first year. The March 2004 announcement released Markdown under the GNU General Public License (GPL).4 On December 17, 2004, Gruber wrote that versions 1.0 and earlier had been under the GPL and that Markdown was now under a less restrictive BSD-style license, a change that came with Markdown 1.0.1.6 A BSD-style license lets others reuse the code with few conditions. The license page carries a 2004 copyright notice in Gruber’s name.7

As of October 22, 2026, Gruber’s project page still offers Markdown 1.0.1, released on December 17, 2004, as the current version of his tool. It requires Perl 5.6.0 or later.1 The same page credits Michel Fortin with a port to PHP and recommends it to PHP users.1

How the syntax works

Gruber describes the split between the two languages this way: “HTML is a publishing format; Markdown is a writing format.”2 Markdown covers only a small set of everyday formatting. For anything else, a writer can type HTML directly into the Markdown text and it passes through.2

The core rules, as set out on Gruber’s syntax page:2

To getYou typeNotes
Heading# Heading (one to six # signs)This is the “atx” style. The number of # signs sets the level.
Heading (other style)A line underlined with = or – signsThe “Setext” style: = for level 1, – for level 2.
Italic and bold*word* and **word** (or underscores)The same character must open and close.
Bulleted listLines starting with *, + or –Numbered lists use 1. 2. 3., and the numbers you type do not change the output.
Link[link text](address)A reference style puts a label in brackets and defines the address elsewhere.
QuotationLines starting with >Borrowed from the way email quotes earlier messages.
Code blockLines indented four spaces or one tabThe contents are shown exactly as typed.

Links point at any URL. Images use a syntax meant to resemble links, with an exclamation mark placed before the brackets.2 To force a line break inside a paragraph, the writer ends a line with two or more spaces.2 A backslash before a special character, such as an asterisk, shows that character instead of treating it as formatting.2

Markdown also handles two characters that trip people up in HTML. Gruber’s page says writers can type the less-than sign and the ampersand normally, because Markdown does the escaping that HTML needs for them.2 Gruber also published a short beginner’s guide and a web form, the Dingus, where anyone could type Markdown and see the converted result.8

Gruber’s original syntax has no rule for tables.2 Tables, footnotes and other features came later through extensions, described below.

Raw HTML and safety

Because Markdown passes HTML through, a converter that accepts text from strangers can also pass through harmful code. RFC 7763 warns that when Markdown is turned into HTML it carries the risks of HTML, which can contain instructions to run scripts or send the reader to other pages.3 For that reason cmark, the CommonMark reference program, removes raw HTML and links that start with javascript:, vbscript:, data: or file: by default. Its documentation recommends an HTML sanitizer, a filter that strips dangerous code, if that protection is turned off.9 GitHub’s own specification includes an extension called disallowed raw HTML for the same kind of protection.10

Many flavors and the push for a standard

Gruber’s syntax page explains the rules with examples but leaves many edge cases open. The CommonMark specification says his canonical description “does not specify the syntax unambiguously,” and that the original Markdown.pl script was buggy and often gave plainly wrong results.5 Programmers who wrote their own converters made different choices, so the same text could look different on different sites.5

RFC 7763 sums up the result: the name Markdown now stands for a whole family of related plain-text syntaxes and the programs that implement them.3 The same document notes that Markdown has no notion of an error: there is no such thing as invalid Markdown.3

On October 25, 2012, Jeff Atwood published on his blog, Coding Horror, a call for companies with a strong interest in Markdown to agree on an official specification and shared test suites. He named Stack Exchange, GitHub, Meteor and Reddit, said the existing description was not a real specification, and asked Gruber to bless the effort.11

Atwood later wrote that the work began in late 2012, when David Greenspan of Meteor proposed the effort. A small private group with people from GitHub, Reddit, Stack Exchange and the open-source community then worked on the details for months. John MacFarlane wrote the whole specification and two implementations, one in the C language and one in JavaScript.12

The group released its work for public review on September 3, 2014, under the name Standard Markdown.12 The name did not last. In a post dated September 4, 2014, Atwood wrote that Gruber had emailed to object strongly to the name and had asked for a new name, for the standardmarkdown.com domain to be shut down without a redirect and for an apology. The team agreed to all three.13 A first rename to Common Markdown was also rejected, because no form of the word Markdown was acceptable to Gruber for the project, and it became CommonMark.13

CommonMark

CommonMark presents itself as a standard and unambiguous specification of Markdown syntax.14 As of October 22, 2026, its site lists John MacFarlane, Martin Woodward and Jeff Atwood as the team, and names Discourse, GitHub, GitLab, Reddit, Qt, Stack Overflow and Stack Exchange, and Swift among its users.14

The specification is published with numbered examples that a converter can be tested against.5 Its earliest listed version, 0.5, is dated October 25, 2014. The current version, 0.31.2, is dated January 28, 2024, and is released under a Creative Commons Attribution-ShareAlike 4.0 license.155 As of October 22, 2026, no version 1.0 has been issued.15

CommonMark settles details that Gruber left open. Beyond indented code, it defines fenced code blocks, which start and end with a row of at least three backticks or tildes. The first word after the opening fence usually names the programming language, so a site can color the code.5 It does not define tables.5

The documentation of cmark, the C reference program, claims it is 10,000 times faster than the original Markdown.pl.9

GitHub Flavored Markdown and other variants

GitHub, a site that hosts software code, uses Markdown across its service. On March 14, 2017, it published a formal specification for its own version, GitHub Flavored Markdown (GFM), built on the CommonMark specification. The same day, GitHub switched to CommonMark-based rendering for all Markdown stored in Git repositories, using its own fork of the CommonMark reference code. GitHub said its tests showed that less than 1% of existing content would be affected.16

The GFM specification, at version 0.29-gfm of April 6, 2019, calls itself “a strict superset of CommonMark.”10 It adds five extensions: tables, task list items (checkboxes), strikethrough, extended autolinks that turn bare web addresses into links, and a list of disallowed raw HTML.10

Other variants added features earlier or in other directions:

  • PHP Markdown Extra. Michel Fortin’s extension of his PHP port adds tables, footnotes, definition lists, abbreviations, fenced code blocks and a way to add IDs and classes to elements.17
  • Pandoc. Pandoc describes itself as a universal document converter. It consists of a Haskell library and a command-line program, its copyright notice names John MacFarlane, and it reads and writes Markdown, including CommonMark and GFM, alongside HTML and Word files.18
  • Python-Markdown. This Python library aims to follow the behavior of Gruber’s original Markdown.pl as closely as is reasonable, and states that it is not a CommonMark implementation.19

The variants are now on record with internet standards bodies. In March 2016 the Internet Engineering Task Force published RFC 7763, by Sean Leonard, which registers the text/markdown media type. It requires a charset parameter, naming the text encoding, and offers an optional variant parameter that hints which flavor the author meant.3 A companion document, RFC 7764, set up a registry of variants and placed eight in it: MultiMarkdown, GitHub Flavored Markdown, Pandoc, Fountain, CommonMark, Markdown for RFCs (kramdown-rfc2629), Pandoc2rfc (rfc7328) and PHP Markdown Extra.20 Both are informational documents, not internet standards.320

The Internet Assigned Numbers Authority keeps that registry. As of its last update on September 24, 2026, it lists 13 entries, including Gruber’s original Markdown, Quarto and MyST Markdown.21

Markdown on the web today

Markdown is now built into many of the tools used to write for the web.

  • Software projects. GitHub accepts Markdown in its web interface, where every comment field has a text formatting toolbar.22 It automatically shows a project’s README file to visitors, and renders Markdown files with a generated table of contents.23
  • Static site generators. These programs turn a folder of text files into a finished website of plain HTML files. GitHub describes Jekyll as a tool that builds a complete static website from Markdown and HTML files, with built-in support for GitHub Pages.24 Jekyll runs on Ruby 2.7.0 or later, and its default Markdown converter, kramdown, uses the GFM processor by default.2526 Hugo makes Markdown its default content format, rendered by a converter called Goldmark that its documentation says conforms to the CommonMark and GFM specifications.27
  • Front matter. Static site files usually begin with a short block of settings, such as the title and date, called front matter. Hugo accepts it in YAML, TOML or JSON, and tells them apart by the lines that wrap the block.2827
  • Content management systems. On WordPress, the Jetpack plugin offers a Markdown block for the block editor. It uses the markdown-it parser, which supports the CommonMark specification.29 Ghost parses Markdown typed straight into its editor and also has a Markdown card for whole posts.30
  • Website builders. Some hosted website builders support Markdown with limits. Squarespace’s Markdown block handles headings, lists, links, images and quotes, but its help page says backtick code fences are not supported and tables appear without borders or spacing.31

Markdown for AI tools

Markdown has also become a format for feeding web content to AI language models. On September 3, 2024, Jeremy Howard proposed llms.txt, a Markdown file placed at a site’s /llms.txt address that gives these models a short guide to the site, with links to the main pages.32 The proposal calls Markdown “the most widely and easily understood format for language models,” and suggests offering a clean Markdown copy of each page at the same address with .md added. It is a proposal open for comment, not a formal standard.32

On February 12, 2026, Cloudflare introduced Markdown for Agents. When a program asks a site that uses the feature for a page and says, in the HTTP Accept header, that it accepts text/markdown, Cloudflare converts the page’s HTML to Markdown before sending it.33 Cloudflare said its own announcement took 16,180 tokens (the units AI models count text in) as HTML and 3,150 as Markdown, an 80% reduction. The feature launched as a free beta on its Pro, Business and Enterprise plans.33

Timeline

  1. Cloudflare introduces Markdown for Agents, converting HTML pages to Markdown for AI programs33
  2. Jeremy Howard proposes llms.txt, a Markdown guide to a website for language models32
  3. CommonMark specification version 0.31.2 is published15
  4. GitHub Flavored Markdown specification version 0.29-gfm is published10
  5. GitHub publishes a formal GFM specification and switches to CommonMark-based rendering16
  6. RFC 7763 registers the text/markdown media type and RFC 7764 starts a registry of variants3
  7. CommonMark specification version 0.5, the earliest listed, is dated15
  8. After objections from Gruber, Standard Markdown is renamed, becoming CommonMark13
  9. Jeff Atwood announces Standard Markdown, a written specification, for public review12
  10. Jeff Atwood calls for an official Markdown specification and test suites11
  11. Markdown 1.0.1 is released and the license changes from the GPL to a BSD-style license6
  12. John Gruber announces Markdown on Daring Fireball4

What it means for your website

Most site owners meet Markdown without choosing it: in a blog editor, a project README or a page builder’s text block. A few practical points follow from how it works.

  • Use it to keep your writing portable. A Markdown file is plain text, so it opens in any editor and can be converted to HTML by many tools.118 Drafting posts in Markdown keeps a copy of your words that does not depend on one platform, which helps during a website migration.
  • Check which flavor your platform speaks. The same text can render differently in different converters.5 Squarespace’s Markdown block does not support backtick code fences and shows tables without borders.31 Jetpack’s block for WordPress follows CommonMark.29 Test a sample post before you paste in a whole archive.
  • Do not accept raw HTML from visitors. If your site turns comments or form entries into HTML with a Markdown converter, make sure raw HTML and script links are stripped. That is the default in cmark, and its maintainers recommend a sanitizer if you allow HTML.9
  • Consider Markdown for static sites. Generators such as Jekyll and Hugo build a fast static site from Markdown files.2427 Ghost also writes in Markdown, and our Ghost review covers its editor.30
  • Know the AI side, but keep expectations modest. An llms.txt file is a short Markdown summary of your site for AI tools. It is a proposal, not a standard that search engines are bound to read.32 If your site sits behind Cloudflare on a paid plan, Markdown for Agents can serve Markdown copies of your pages to AI programs that ask for them.33 Our guide to websites and AI search explains what these files do and do not change.

See also

References

  1. Markdown. John Gruber, Daring Fireball. accessed October 22, 2026.
  2. Markdown: Syntax. John Gruber, Daring Fireball. accessed October 22, 2026.
  3. RFC 7763: The text/markdown Media Type. Sean Leonard, Internet Engineering Task Force, RFC Editor. 2016-03. accessed October 22, 2026.
  4. Introducing Markdown. John Gruber, Daring Fireball. 2004-03-15. accessed October 22, 2026.
  5. CommonMark Spec, version 0.31.2. John MacFarlane, CommonMark. 2024-01-28. accessed October 22, 2026.
  6. Markdown Licensing. John Gruber, Daring Fireball. 2004-12-17. accessed October 22, 2026.
  7. Markdown License. John Gruber, Daring Fireball. accessed October 22, 2026.
  8. Markdown: Basics. John Gruber, Daring Fireball. accessed October 22, 2026.
  9. cmark: CommonMark parsing and rendering library and program in C. CommonMark project, GitHub. accessed October 22, 2026.
  10. GitHub Flavored Markdown Spec, version 0.29-gfm. GitHub. 2019-04-06. accessed October 22, 2026.
  11. The Future of Markdown. Jeff Atwood, Coding Horror. 2012-10-25. accessed October 22, 2026.
  12. Standard Flavored Markdown. Jeff Atwood, Coding Horror. 2014-09-03. accessed October 22, 2026.
  13. Standard Markdown is now Common Markdown. Jeff Atwood, Coding Horror. 2014-09-04. accessed October 22, 2026.
  14. CommonMark. CommonMark. accessed October 22, 2026.
  15. CommonMark Spec: versions. CommonMark. accessed October 22, 2026.
  16. A formal spec for GitHub Flavored Markdown. Vicent Martí and Ashe Connor, GitHub Engineering, The GitHub Blog. 2017-03-14. accessed October 22, 2026.
  17. PHP Markdown Extra. Michel Fortin. accessed October 22, 2026.
  18. Pandoc: a universal document converter. John MacFarlane, pandoc.org. accessed October 22, 2026.
  19. Python-Markdown. The Python-Markdown Project. accessed October 22, 2026.
  20. RFC 7764: Guidance on Markdown: Design Philosophies, Stability Strategies, and Select Registrations. Sean Leonard, Internet Engineering Task Force, RFC Editor. 2016-03. accessed October 22, 2026.
  21. Markdown Variants. Internet Assigned Numbers Authority (IANA). 2026-09-24. accessed October 22, 2026.
  22. About writing and formatting on GitHub. GitHub Docs. accessed October 22, 2026.
  23. About the repository README file. GitHub Docs. accessed October 22, 2026.
  24. About GitHub Pages and Jekyll. GitHub Docs. accessed October 22, 2026.
  25. Quickstart. Jekyll documentation. accessed October 22, 2026.
  26. Markdown Options. Jekyll documentation. accessed October 22, 2026.
  27. Content formats. Hugo documentation. accessed October 22, 2026.
  28. Front matter. Hugo documentation. accessed October 22, 2026.
  29. Markdown. Jetpack Support. accessed October 22, 2026.
  30. Cards. Ghost Help. accessed October 22, 2026.
  31. Markdown blocks. Squarespace Help Center. accessed October 22, 2026.
  32. The /llms.txt file. Jeremy Howard, llmstxt.org. 2024-09-03. accessed October 22, 2026.
  33. Introducing Markdown for Agents. Celso Martinho and Will Allen, The Cloudflare Blog. 2026-02-12. accessed October 22, 2026.

Web Building Encyclopedia. First published October 22, 2026. Last reviewed October 22, 2026. Every fact on this page is linked to a source we opened. Spotted an error? Write to [email protected].