Markdown
Filename extensions
.md, .markdown[1][2]
Internet media typetext/markdown[2]
Uniform Type Identifier (UTI)net.daringfireball.markdown
Developed by
Initial releaseMarch 9, 2004 (19 years ago) (2004-03-09)[5][6]
Latest release
1.0.1
December 17, 2004 (19 years ago) (2004-12-17)[7]
Type of formatOpen file format[8]
Extended topandoc, MultiMarkdown, Markdown Extra, CommonMark,[9] RMarkdown[10]
Websitedaringfireball.net/projects/markdown/

Markdown[11] is a lightweight markup language for creating formatted text using a plain-text editor. John Gruber and Aaron Swartz[3][4] created Markdown in 2004 as a markup language that is intended to be easy to read in its source code form.[11] Markdown is widely used for blogging and instant messaging, and also used elsewhere in online forums, collaborative software, documentation pages, and readme files.

The initial description of Markdown[12] contained ambiguities and raised unanswered questions, causing implementations to both intentionally and accidentally diverge from the original version. This was addressed in 2014 when long-standing Markdown contributors released CommonMark, an unambiguous specification and test suite for Markdown.[13]

History

Markdown was inspired by pre-existing conventions for marking up plain text in email and usenet posts, such as the earlier markup languages setext (c. 1992), Textile (c. 2002), and reStructuredText (c. 2002).[11]

In 2002 Aaron Swartz created atx and referred to it as "the true structured text format". Gruber and Swartz[3][4] created the Markdown language in 2004, with the goal of enabling people "to write using an easy-to-read and easy-to-write plain text format, optionally convert it to structurally valid XHTML (or HTML)."[7]

Its key design goal was readability, that the language be readable as-is, without looking like it has been marked up with tags or formatting instructions,[11] unlike text formatted with 'heavier' markup languages, such as Rich Text Format (RTF), HTML, or even wikitext (each of which have obvious in-line tags and formatting instructions which can make the text more difficult for humans to read).

Gruber wrote a Perl script, Markdown.pl, which converts marked-up text input to valid, well-formed XHTML or HTML and replaces angle brackets (<, >) and ampersands (&) with their corresponding character entity references. It can take the role of a standalone script, a plugin for Blosxom or a Movable Type, or of a text filter for BBEdit.[7]

Rise and divergence

As Markdown's popularity grew rapidly, many Markdown implementations appeared, driven mostly by the need for additional features such as tables, footnotes, definition lists,[note 1] and Markdown inside HTML blocks.

The behavior of some of these diverged from the reference implementation, as Markdown was only characterised by an informal specification[16] and a Perl implementation for conversion to HTML.

At the same time, a number of ambiguities in the informal specification had attracted attention.[17] These issues spurred the creation of tools such as Babelmark[18][19] to compare the output of various implementations,[20] and an effort by some developers of Markdown parsers for standardisation. However, Gruber has argued that complete standardization would be a mistake: "Different sites (and people) have different needs. No one syntax would make all happy."[21]

Gruber avoided using curly braces in Markdown to unofficially reserve them for implementation-specific extensions.[22]

Standardization

CommonMark
Filename extensions.md, .markdown[2]
Internet media typetext/markdown; variant=CommonMark[9]
Uniform Type Identifier (UTI)uncertain[23]
UTI conformationpublic.plain-text
Developed byJohn MacFarlane, open source
Initial releaseOctober 25, 2014 (9 years ago) (2014-10-25)
Latest release
0.30
June 19, 2021 (2 years ago) (2021-06-19)[24]
Type of formatOpen file format
Extended fromMarkdown
Extended toGitHub Flavored Markdown
Websitecommonmark.org spec.commonmark.org

From 2012, a group of people, including Jeff Atwood and John MacFarlane, launched what Atwood characterised as a standardisation effort.[13] A community website now aims to "document various tools and resources available to document authors and developers, as well as implementors of the various Markdown implementations".[25] In September 2014, Gruber objected to the usage of "Markdown" in the name of this effort and it was rebranded as CommonMark.[26][27] CommonMark.org published several versions of a specification, reference implementation, test suite, and "[plans] to announce a finalized 1.0 spec and test suite in 2019."[28] No 1.0 spec has since been released as major issues still remain unsolved.[29] Nonetheless, the following websites and projects have adopted CommonMark: Discourse, GitHub, GitLab, Reddit, Qt, Stack Exchange (Stack Overflow), and Swift.

In March 2016 two relevant informational Internet RFCs were published:

Variants

Websites like Bitbucket, Diaspora, GitHub,[31] OpenStreetMap, Reddit,[32] SourceForge,[33] and Stack Exchange[34] use variants of Markdown to make discussions between users easier.

Depending on implementation, basic inline HTML tags may be supported.[35] Italic text may be implemented by _underscores_ or *single-asterisks*.[36]

GitHub Flavored Markdown

GitHub had been using its own variant of Markdown since as early as 2009,[37] which added support for additional formatting such as tables and nesting block content inside list elements, as well as GitHub-specific features such as auto-linking references to commits, issues, usernames, etc. In 2017, GitHub released a formal specification of its GitHub Flavored Markdown (GFM) that is based on CommonMark.[31] It is a strict superset of CommonMark, following its specification exactly except for tables, strikethrough, autolinks and task lists, which GFM adds as extensions.[38] Accordingly, GitHub also changed the parser used on their sites, which required that some documents be changed. For instance, GFM now requires that the hash symbol that creates a heading be separated from the heading text by a space character.

Markdown Extra

Markdown Extra is a lightweight markup language based on Markdown implemented in PHP (originally), Python and Ruby.[39] It adds the following features that are not available with regular Markdown:

Markdown Extra is supported in some content management systems such as Drupal,[41] Grav (CMS) and TYPO3.[42]

LiaScript

LiaScript[43] is a Markdown dialect that was designed to create interactive educational content. It is implemented in Elm and TypeScript and adds additional syntax elements to define features like:

Examples

Text using Markdown syntax Corresponding HTML produced by a Markdown processor Text viewed in a browser
Heading
=======

Sub-heading
-----------

# Alternative heading

## Alternative sub-heading

Paragraphs are separated 
by a blank line.

Two spaces at the end of a line  
produce a line break.
<h1>Heading</h1>

<h2>Sub-heading</h2>

<h1>Alternative heading</h1>

<h2>Alternative sub-heading</h2>

<p>Paragraphs are separated
by a blank line.</p>

<p>Two spaces at the end of a line<br />
produce a line break.</p>
Heading
Sub-heading
Alternative heading
Alternative sub-heading

Paragraphs are separated by a blank line.

Two spaces at the end of a line
produce a line break.

Text attributes _italic_, **bold**, `monospace`.

Horizontal rule:

---
<p>Text attributes <em>italic</em>, <strong>bold</strong>, <code>monospace</code>.</p>

<p>Horizontal rule:</p>

<hr />
Text attributes italic, bold, monospace.

Horizontal rule:


Bullet lists nested within numbered list:

  1. fruits
     * apple
     * banana
  2. vegetables
     - carrot
     - broccoli
<p>Bullet lists nested within numbered list:</p>

<ol>
  <li>fruits <ul>
      <li>apple</li>
      <li>banana</li>
  </ul></li>
  <li>vegetables <ul>
      <li>carrot</li>
      <li>broccoli</li>
  </ul></li>
</ol>
Bullet lists nested within numbered list:
  1. fruits
    • apple
    • banana
  2. vegetables
    • carrot
    • broccoli
A [link](http://example.com).

![Image](Icon-pictures.png "icon")

> Markdown uses email-style
characters for blockquoting.
>
> Multiple paragraphs need to be prepended individually.

Most inline <abbr title="Hypertext Markup Language">HTML</abbr> tags are supported.
<p>A <a href="http://example.com">link</a>.</p>

<p><img alt="Image" title="icon" src="Icon-pictures.png" /></p>

<blockquote>
<p>Markdown uses email-style characters for blockquoting.</p>
<p>Multiple paragraphs need to be prepended individually.</p>
</blockquote>

<p>Most inline <abbr title="Hypertext Markup Language">HTML</abbr> tags are supported.</p>
A link.

Image

Markdown uses email-style characters for blockquoting.

Multiple paragraphs need to be prepended individually.

Most inline HTML tags are supported.

Implementations

Implementations of Markdown are available for over a dozen programming languages; in addition, many applications, platforms and frameworks support Markdown.[44] For example, Markdown plugins exist for every major blogging platform.[45]

While Markdown is a minimal markup language and is read and edited with a normal text editor, there are specially designed editors that preview the files with styles, which are available for all major platforms. Many general-purpose text and code editors have syntax highlighting plugins for Markdown built into them or available as optional download. Editors may feature a side-by-side preview window or render the code directly in a WYSIWYG fashion.

Some apps, services and editors support Markdown as an editing format, including:

See also

Explanatory notes

  1. ^ Technically HTML description lists

References

  1. ^ Gruber, John (8 January 2014). "The Markdown File Extension". The Daring Fireball Company, LLC. Archived from the original on 12 July 2020. Retrieved 27 March 2022. Too late now, I suppose, but the only file extension I would endorse is ".markdown", for the same reason offered by Hilton Lipschitz: We no longer live in a 8.3 world, so we should be using the most descriptive file extensions. It's sad that all our operating systems rely on this stupid convention instead of the better creator code or a metadata model, but great that they now support longer file extensions.
  2. ^ a b c Leonard, Sean (March 2016). "The text/markdown Media Type". Request for Comments: 7763. Internet Engineering Task Force. Archived from the original on 22 March 2022. Retrieved 27 March 2022. This document registers the text/markdown media type for use with Markdown, a family of plain-text formatting syntaxes that optionally can be converted to formal markup languages such as HTML.
  3. ^ a b c Hendler, James (10 November 2022). "Foreword by James Hendler". Aaron Swartz's A Programmable Web: An Unfinished Work (PDF). Synthesis Lectures on Data, Semantics, and Knowledge. Springer Nature Switzerland. pp. ix. doi:10.1007/978-3-031-79444-5. ISBN 978-3-031-79444-5. Retrieved 12 January 2024 – via Wikisource. This document was originally produced in "markdown" format, a simplified HTML/Wiki format that Aaron co-designed with John Gruber ca. 2004.
  4. ^ a b c Krewinkel, Albert; Winkler, Robert (8 May 2017). "Formatting Open Science: agilely creating multiple document formats for academic manuscripts with Pandoc Scholar" (PDF). PeerJ Computer Science. 3: 6. doi:10.7717/peerj-cs.112. Retrieved 12 January 2024. Markdown was originally developed by John Gruber in collaboration with Aaron Swartz, with the goal to simplify the writing of HTML documents
  5. ^ Swartz, Aaron (2004-03-19). "Markdown". Aaron Swartz: The Weblog. Archived from the original on 2017-12-24. Retrieved 2013-09-01.
  6. ^ Gruber, John. "Markdown". Daring Fireball. Archived from the original on 2004-03-11. Retrieved 2022-08-20.
  7. ^ a b c Markdown 1.0.1 readme source code "Daring Fireball – Markdown". 2004-12-17. Archived from the original on 2004-04-02.
  8. ^ "Markdown: License". Daring Fireball. Archived from the original on 2020-02-18. Retrieved 2014-04-25.
  9. ^ a b Leonard, Sean (March 2016). "Guidance on Markdown: Design Philosophies, Stability Strategies, and Select Registrations". Request for Comments: 7764. Internet Engineering Task Force. Archived from the original on 17 April 2022. Retrieved 27 March 2022. This document elaborates upon the text/markdown media type for use with Markdown, a family of plain-text formatting syntaxes that optionally can be converted to formal markup languages such as HTML. Background information, local storage strategies, and additional syntax registrations are supplied.
  10. ^ "RMarkdown Reference site". Archived from the original on 2020-03-03. Retrieved 2019-11-21.
  11. ^ a b c d Markdown Syntax "Daring Fireball – Markdown – Syntax". 2013-06-13. "Readability, however, is emphasized above all else. 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. While Markdown's syntax has been influenced by several existing text-to-HTML filters — including Setext, atx, Textile, reStructuredText, Grutatext[14], and EtText[15] — the single biggest source of inspiration for Markdown's syntax is the format of plain text email."
  12. ^ "Daring Fireball: Introducing Markdown". daringfireball.net. Archived from the original on 2020-09-20. Retrieved 2020-09-23.
  13. ^ a b Atwood, Jeff (2012-10-25). "The Future of Markdown". CodingHorror.com. Archived from the original on 2014-02-11. Retrieved 2014-04-25.
  14. ^ "Un naufragio personal: The Grutatxt markup". triptico.com. Retrieved 2022-06-30.
  15. ^ "EtText: Documentation: Using EtText". ettext.taint.org. Retrieved 2022-06-30.
  16. ^ "Markdown Syntax Documentation". Daring Fireball. Archived from the original on 2019-09-09. Retrieved 2018-03-09.
  17. ^ "GitHub Flavored Markdown Spec – Why is a spec needed?". github.github.com. Archived from the original on 2020-02-03. Retrieved 2018-05-17.
  18. ^ "Babelmark 2 – Compare markdown implementations". Johnmacfarlane.net. Archived from the original on 2017-07-18. Retrieved 2014-04-25.
  19. ^ "Babelmark 3 – Compare Markdown Implementations". github.io. Archived from the original on 2020-11-12. Retrieved 2017-12-10.
  20. ^ "Babelmark 2 – FAQ". Johnmacfarlane.net. Archived from the original on 2017-07-28. Retrieved 2014-04-25.
  21. ^ Gruber, John [@gruber] (September 4, 2014). "@tobie @espadrine @comex @wycats Because different sites (and people) have different needs. No one syntax would make all happy" (Tweet) – via Twitter.
  22. ^ Gruber, John (19 May 2022). "Markdoc". Daring Fireball. Archived from the original on 19 May 2022. Retrieved May 19, 2022. I love their syntax extensions — very true to the spirit of Markdown. They use curly braces for their extensions; I'm not sure I ever made this clear, publicly, but I avoided using curly braces in Markdown itself — even though they are very tempting characters — to unofficially reserve them for implementation-specific extensions. Markdoc's extensive use of curly braces for its syntax is exactly the sort of thing I was thinking about.
  23. ^ "UTI of a CommonMark document". 12 April 2017. Archived from the original on 22 November 2018. Retrieved 29 September 2017.
  24. ^ "CommonMark specification". Archived from the original on 2017-08-07. Retrieved 2017-07-26.
  25. ^ "Markdown Community Page". GitHub. Archived from the original on 2020-10-26. Retrieved 2014-04-25.
  26. ^ "Standard Markdown is now Common Markdown". Jeff Atwood. 4 September 2014. Archived from the original on 2014-10-09. Retrieved 2014-10-07.
  27. ^ "Standard Markdown Becomes Common Markdown then CommonMark". InfoQ. Archived from the original on 2020-09-30. Retrieved 2014-10-07.
  28. ^ "CommonMark". Archived from the original on 12 April 2016. Retrieved 20 Jun 2018. The current version of the CommonMark spec is complete, and quite robust after a year of public feedback … but not quite final. With your help, we plan to announce a finalized 1.0 spec and test suite in 2019.
  29. ^ "Issues we MUST resolve before 1.0 release [6 remaining]". CommonMark Discussion. 2015-07-26. Archived from the original on 2021-04-14. Retrieved 2020-10-02.
  30. ^ "Markdown Variants". IANA. 2016-03-28. Archived from the original on 2020-10-27. Retrieved 2016-07-06.
  31. ^ a b c "GitHub Flavored Markdown Spec". GitHub. Archived from the original on 2020-02-03. Retrieved 2020-06-11.
  32. ^ "Reddit markdown primer. Or, how do you do all that fancy formatting in your comments, anyway?". Reddit. Archived from the original on 2019-06-11. Retrieved 2013-03-29.
  33. ^ "SourceForge: Markdown Syntax Guide". SourceForge. Archived from the original on 2019-06-13. Retrieved 2013-05-10.
  34. ^ "Markdown Editing Help". StackOverflow.com. Archived from the original on 2014-03-28. Retrieved 2014-04-11.
  35. ^ "Markdown Syntax Documentation". daringfireball.net. Archived from the original on 2019-09-09. Retrieved 2021-03-01.
  36. ^ "Basic Syntax: Italic". The Markdown Guide. Matt Cone. Archived from the original on 26 March 2022. Retrieved 27 March 2022. To italicize text, add one asterisk or underscore before and after a word or phrase. To italicize the middle of a word for emphasis, add one asterisk without spaces around the letters.
  37. ^ Tom Preston-Werner. "GitHub Flavored Markdown Examples". GitHub. Archived from the original on 2021-05-13. Retrieved 2021-04-02.
  38. ^ "A formal spec for GitHub Flavored Markdown". GitHub Engineering. 14 March 2017. Archived from the original on 3 February 2020. Retrieved 16 Mar 2017.
  39. ^ Fortin, Michel (2018). "PHP Markdown Extra". Michel Fortin website. Archived from the original on 2021-01-17. Retrieved 2018-12-26.
  40. ^ "PHP Markdown Extra". Michel Fortin. Archived from the original on 2021-01-17. Retrieved 2018-12-26.
  41. ^ "Markdown editor for BUEditor". 4 December 2008. Archived from the original on 17 September 2020. Retrieved 15 January 2017.
  42. ^ "Markdown for TYPO3 (markdown_content)". extensions.typo3.org. Archived from the original on 2021-02-01. Retrieved 2019-02-06.
  43. ^ Dietrich, André. "LiaScript". liascript.github.io. Archived from the original on 2022-01-19. Retrieved 2022-01-17.
  44. ^ "W3C Community Page of Markdown Implementations". W3C Markdown Wiki. Archived from the original on 17 September 2020. Retrieved 24 March 2016.
  45. ^ "Markdown THrowdown – What happens when FOSS software gets corporate backing". Ars Technica. 2014-10-05. Archived from the original on 2020-11-14. Retrieved 2017-06-14.
  46. ^ "Use Markdown formatting in Teams". Microsoft. Archived from the original on 2022-01-13. Retrieved 2022-01-13.
  47. ^ "Markdown Text 101 (Chat Formatting: Bold, Italic, Underline)". discord.com. Archived from the original on June 26, 2020.
  48. ^ "Why You Need a WYSIWYG Editor When Writing in Markdown and Fountain". JotterPad Blog. 2020-11-17. Archived from the original on 2020-11-27. Retrieved 2020-12-06.
  49. ^ "Doxygen Manual: Markdown support". Archived from the original on 2019-08-09. Retrieved 2019-08-09.
  50. ^ Allaire, J.J.; e.a. (2015-06-30). "Markdown.cpp". GitHub project RStudio. Archived from the original on 2017-07-26. Retrieved 2016-07-07.
  51. ^ "Writing on GitHub". help.github.com. GitHub, Inc. Archived from the original on 4 June 2018. Retrieved 9 July 2014.
  52. ^ R Markdown: The Definitive Guide. Archived from the original on 2021-04-13. Retrieved 2021-08-23.
  53. ^ "Nextcloud Notes * App". Nextcloud Apps. Archived from the original on 2022-02-18. Retrieved 2022-02-18.
  54. ^ "Markdown Guide". joplinapp.org. Archived from the original on 2022-09-23. Retrieved 2022-07-14.
  55. ^ "Help". Simplenote. 2015-07-30. Archived from the original on 2022-07-14. Retrieved 2022-07-14.
  56. ^ "Obsidian". obsidian.md. Archived from the original on 2022-07-12. Retrieved 2022-07-14.
  57. ^ @EvolutionGnome (March 23, 2022). "Evolution 3.44 is out and already available on #Flathub! Besides many smaller improvements and fixes it brings a markdown editor to compose messages. 👇" (Tweet) – via Twitter.
  58. ^ "Markdown Syntax — Kanboard documentation". docs.kanboard.org. Archived from the original on 2022-10-11. Retrieved 2022-10-11.
  59. ^ "330707 - Add optional support for MarkDown". bugzilla.mozilla.org. Archived from the original on 2022-10-11. Retrieved 2022-10-11.