Markdown Resources

Markdown (John Gruber & Aaron Swartz, 2004) is a lightweight markup language, similar to Setext (Ian Feldman, 1992), AFT (Todd Coram, 1999), Grutatxt (Ángel Ortega, 2000), atx (Aaron Swartz, 2002), AsciiDoc (Stuart Rackham, 2002), MediaWiki (Magnus Manske & Lee Daniel Crocker, 2002), reStructuredText (David Goodger, 2002), Org-mode (Carsten Dominik, 2003), Textile (Dean Allen, 2004), and many others (listed here, here and here).¹

Lightweight markup languages are abundant. Markdown seems to have have won the race, but its popularity comes at a cost. Whereas original Markdown in its early days, ca 2004, had to compete with many alternatives, today it is clearly king, but its realm is falling apart into many baronnies. Markdown dialects, forks, and supersets, are competing amongst each other. While they all remain true to the original Markdown syntax subset, new initiatives arise, which abandon the Markdown syntax. Noteworthy are SkrivML, Strictdown and z.m.l. Rumor has it that there is even a “Markdown Operating System” in the make…

About Markdown (and the purpose of this collection)

Markdown is said to be “invented” by John Gruber, who, in any case, worked on it together with Aaron Swartz (1986–2013). Since the release of “original” Markdown in 2004, the language has been “forked” many times over. Today, there are several “extensions” and dialects in circulation. Many more apps have been created (for the Web, OSX, iOS, Android, Windows).

Depending on the specific Markdown implementation (parser) those apps use under the hood, they support one or more Markdown dialects or “flavors”. It is not always obvious to end users which apps (and backend scripts) can do what exactly. This collection of resources tries to clear up some of that confusion.

This repo

At the moment the repository has structured lists for Markdown editors (apps with a graphical user interface), dialects/extensions, implementations, stylesheets (themes in css), and a simple list for various other Markdown related tools:

• Markdown Editors: native apps
• Markdown Editors: browser-based
• Markdown Dialects
• Markdown Implementations
• Markdown People
• Markdown Stylesheets
• Various Markdown Tools

Feel free to grab the .yml files, convert them into .json, .xml or whatever suits your needs, and import them into a searchable data store. Enjoy!

On the use of YAML

The structured lists in this repo are formatted using YAML. Not unlike Markdown, YAML is a lightweight markup language with a syntax that is intended to be easily readable by humans, all while formally structured for machine processing. But unlike Markdown, YAML is more suited to author, edit, and store non-sequential data.

YAML and Markdown only seem to be competing languages, but they are not mutually exclusive. Indeed, some Markdown editors and implementations even support YAML: while the document’s body is formatted in Markdown syntax, its front matter (metadata) is structured using YAML syntax. Just like documents can exist without front matter, and be formatted in Markdown exclusively, so can documents consist out of nothing else than ~~(meta)~~data and be completely formatted in YAML.

One might put it like this: Markdown is for text (i.e. text that is meant for continuous reading), while YAML is for structured data (not sequentially read, but randomly accessed/queried).

While both languages are concise enough to be easily read in raw format by a human editor, the intended output of a text file formatted in Markdown is a (typographically) styled document, whereas a text file formatted in YAML is expected to be eventually read into a datastore.

Contributions

Markdown is gaining enormous popularity and dozens of implementations and applications are pumped out almost every single week, it seems. Maybe one could set up some sort of automated tracking, but as it stans now, the present collection is curated manually. It cannot be exhaustive without some help, and contributions are gratefully welcomed!

Please fork, edit, commit, and send pull requests, or just file an issue.

Alternatively, if you want to quickly add a Markdown resource (that is not on a list already), and you don’t like how the YAML format is presented by Github, you can do so on the Wiki.

Discussion

There’s not much room for discussion here on Github, and the present repo is just a shared store of resources. If you want to take part in the vibrant discussions on the future of Markdown, there’s no exact place to point to.

There’s a Markdown Community Page on GitHub, but it seems it never got further than some initial enthusiasm. There’s also an official W3C Markdown Community Group, but that too seems abandoned. The actual discussion on Markdown takes place at the Markdown mailing list, and on private blogs.

Other useful Markdown resources

While this entire repository is made up of links to useful Markdown resources, the following stand apart as they too are curated collections of links to other Markdown resources, and/or provide more context.

• http://whatismarkdown.com/
• http://markdowntutorial.com/
• http://johnmacfarlane.net/babelmark2/faq.html – Testing and comparison suite for Markdown implementations, by John MacFarlane.
• https://www.penflip.com/MmmmJoel/writing-some-things

---

Footnotes

1. This document (README.md) is itself formatted using the GitHub Flavored Markdown dialect. The specs are here. The repo is kept at https://github.com/rhythmus/markdown-resources. ↩