Markdown

ROAM_REFS: https://en.wikipedia.org/wiki/Markdown

Markdown is a lightweight markup language for creating formatted text using a plain-text editor. John Gruber created Markdown in 2004 as an easy-to-read markup language. 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 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.

ROAM_REFS: https://daringfireball.net/projects/markdown/

** Introduction

Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).

Thus, “Markdown” is two things: (1) a plain text formatting syntax; and (2) a software tool, written in Perl, that converts the plain text formatting to HTML. See the Syntax page for details pertaining to Markdown's formatting syntax. You can try it out, right now, using the online Dingus.

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. While Markdown's syntax has been influenced by several existing text-to-HTML filters, the single biggest source of inspiration for Markdown's syntax is the format of plain text email.

The best way to get a feel for Markdown's formatting syntax is simply to look at a Markdown-formatted document. For example, you can view the Markdown source for the article text on this page here: http://daringfireball.net/projects/markdown/index.text

(You can use this ‘.text' suffix trick to view the Markdown source for the content of each of the pages in this section, e.g. the Syntax and License pages.)

Markdown is free software, available under a BSD-style open source license. See the License page for more information.

ROAM_REFS: https://commonmark.org/

• CommonMark

** A strongly defined, highly compatible specification of Markdown

** What is Markdown?

It's a plain text format for writing structured documents, based on formatting conventions from email and usenet.

Learn Markdown in 60 Seconds

** Who created Markdown?

It was developed in 2004 by John Gruber in collaboration with Aaron Swartz. Gruber wrote the first markdown-to-html converter in Perl, and it soon became widely used in websites. By 2014 there were dozens of implementations in many languages.

** Why is CommonMark needed?

John Gruber's canonical description of Markdown's syntax does not specify the syntax unambiguously.

In the absence of a spec, early implementers consulted the original

Markdown.pl

code to resolve these ambiguities. But

Markdown.pl

was quite buggy, and gave manifestly bad results in many cases, so it was not a satisfactory replacement for a spec.

Markdown.pl

was last updated December 17th, 2004.

Because there is no unambiguous spec, implementations have diverged considerably over the last 10 years. As a result, users are often surprised to find that a document that renders one way on one system (say, a GitHub wiki) renders differently on another (say, converting to docbook using Pandoc). To make matters worse, because nothing in Markdown counts as a “syntax error,” the divergence often isn't discovered right away.

There's no standard test suite for Markdown; MDTest is the closest thing we had, and is now obsolete. The best current way to resolve Markdown ambiguities and inconsistencies is Babelmark 3, which compares the output of 20+ implementations of Markdown against each other to see if a consensus emerges.

We propose a standard, unambiguous syntax specification for Markdown, along with a suite of comprehensive tests to validate Markdown implementations against this specification. We believe this is necessary, even essential, for the future of Markdown.

That's what we call CommonMark.

** Who are you today?

We're a group of Markdown fans continually working toward the vision of CommonMark — a standard, interoperable and testable version of Markdown.

• John MacFarlane, jgm@berkeley.edu
• Martin Woodward, martinwoodward@github.com
• Jeff Atwood, jatwood@codinghorror.com

** Who were you in 2014, when this started?

We're a group of Markdown fans who either work at companies with industrial scale deployments of Markdown, have written Markdown parsers, have extensive experience supporting Markdown with end users – or all of the above.

• John MacFarlane, of Pandoc
• David Greenspan, of Meteor
• Vicent Marti, of GitHub
• Neil Williams, of Reddit
• Benjamin Dumke-von der Ehe, of Stack Overflow / Stack Exchange
• Jeff Atwood, of Discourse

** How can I help?

Exercise our reference implementations, or find a community implementation in your preferred environment or language. Provide feedback!

If a CommonMark implementation does not already exist in your preferred environment or language, try implementing your own CommonMark parser. One of our major goals is to strongly specify Markdown, and to eliminate the many old inconsistencies and ambiguities that made using Markdown so difficult. Did we succeed?

** Where can I find it?

* spec.commonmark.org

The CommonMark specification.

* code.commonmark.org

Reference implementation and validation test suite on GitHub.

* talk.commonmark.org

Public discussion area and mailing list via Discourse.

* commonmark.org/help

Quick reference card and interactive tutorial for learning Markdown.

* spec.commonmark.org/dingus

Live testing tool powered by the reference implementation.

** When is the spec final?

The current version of the CommonMark spec is quite robust after many years of public feedback.

There are currently CommonMark implementations for dozens of programming languages, and the following sites and projects have adopted CommonMark:

• Discourse
• GitHub
• GitLab
• Reddit
• Qt
• Stack Overflow / Stack Exchange
• Swift

ROAM_REFS: https://spec.commonmark.org/

ROAM_REFS: http://www.aaronsw.com/weblog/001189

• Markdown

For months I've been working with John Gruber on a new project. The idea was to make writing simple web pages, and especially weblog entries, as easy as writing an email, by allowing you to use much the same syntax and converting it automatically into HTML.

Together we pored over the syntax details from top to bottom, trying to develop the perfect format, and I think we've got something pretty darn great. We've tested it extensively: on our blogs, in my comments form, in our emails. It's all worked amazingly well.

The format, and John Gruber's perl implementation of it, is called Markdown. I highly recommend it. It plugs right into Movable Type and makes writing entries so much easier and fun.

• Official Website
• Gruber Manifesto

As John was getting ready to release, I did another couple-hour project and wrote the software to go in reverse: to take HTML and turn it back into Markdown. It's just a first alpha draft, but it seems to handle everything I've thrown at it. (If you run into problems, please let me know.)

• html2text

Both projects are free software, available under the GNU GPL. Share and enjoy!