Markdown is a way of writing and interpreting plain text so that it can optionally be converted to more explicitly meaningful or richly styled text like HTML. Markdown is often used in README files and some online discussion forums.
ReadabilityAs readable as possible is the most important Markdown design goal.
The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible.
See and incorporate from storage#Markdown_plus_extensions
- User:Sandeep.io writes in markdown and publishes it directly in a hidden div. It is intended as lossless, plaintext content for comments and replies since 2013-06-11
- Amy Guy uses markdown for post authoring and storage since 2013-10-13. E.g.
- Bret Comnes uses markdown for post authoring and storage since ????-??-?? E.g.
- bear uses markdown for articles, small notes and webmention's to keep his markdown "clean" each type of article is handled by a specific Jinja2 template. Since ????-??-?? (URL to MD source?)
- Aaron Parecki uses markdown for post authoring and storage since ????-??-?? (URL to MD source?)
- Peter Molnar uses markdown extra since somewhere in 2014 and a [pandoc] compatible Markdown since 2016.
Lightweight markup alternatives to Markdown being used or considered by IndieWeb community members:
- MediaWiki syntax - just to edit our wiki
- Tantek Çelik Thoughts on Markdown - analysis, alternate syntax proposals, and some implementation
- needs a name
Markdown comes in many flavors...
- basic Gruber Markdown
- Github-Flavored Markdown
- StackOverflow Markdown
- kramdown (basic plus some extensions from PHP Markdown and Maruku)
- Markdown Extra ( also the base of many other flavor )
And has many extensions to the basic syntax:
Summaries of Markdown flavors and specifications:
There is a joint work on documenting expected behaviour and specification for extended features in an attempt called Commonmark. While at first it looks like yet another flavour, due to the extensive documentation, it may as well become a common ground.
readable but not pretty - aaronpk in IRC
sometimes looks funny - bret in IRC
if it looks funny, it's failed as markdown [per its own overriding readability principle] - tantek in IRC
- Under-specified, leads to many implementations, fragmentation. e.g.,
```php code sample ```
~~~~php code sample ~~~~
vs. Python-Markdown with CodeHilite (though you can enable the
fenced_code extension to support all three syntaxes in Python-Markdown)
:::php code sample
ugly enough to consider separate text plain
Aaron Parecki it said i have to write the email in markdown. it didn't say it was going to send the markdown as the text/plain part of the email. the preview only showed it to me as html
Tantek Çelik well if markdown adhered to its principles it would work *just fine* as the text/plain part
Aaron Parecki wait does that mean my hyperlinks came through in markdown format too?
Thus pointing out the particularly ugly / plain text unfriendly format of links in Markdown, that it would cause surprise/consternation that such formatting might be shown to other users.
Articles, blog posts, opinions about markdown (in particular from IndieWeb community members)
- 2016-04-27 You Should Probably Blog in Markdown
- 2014-11-09 hReview Microformats in Markdown. Please note that this article uses the older hReview microformat, it's listed here as an example of how a template language like Jinja2 can aid in generating html when using Mardown.
- 2010-10-16 Thoughts on Markdown by Dr. Drang (has some particular thoughts on tables, definition lists, footnotes)
IndieWebCamp sessions that discussed markdown:
- Pandoc is a format converter which understands most dialects of Markdown
- Babelmark 2 is a behaviour/output tester for numerous implementations of Markdown parsers
Using a minimum amount of features to make your markup cross-compatible:
Comparison table of a few, relatively well-known alternatives:
- http://hyperpolyglot.org/lightweight-markup (comparison table)
See Wikipedia for more (no need to duplicate Wikipedia thoroughness here)
- text-first design
- link syntax
- "markdown urls are the usb connectors of syntax" @0xabad1dea August 9, 2018
- Opinionated thread & discussion: https://twitter.com/taravancil/status/1119380292459028480
- "It's too soon to say for sure, but I think I'm anti-markdown" @taravancil April 19, 2019
ᴹᵃʳᵏᵈᵒʷⁿ ᶦˢ ᵒᵛᵉʳʳᵃᵗᵉᵈ ᵇᵉᶜᵃᵘˢᵉ ᶦᵗ ᵐᵃᵏᵉˢ ᶜᵒⁿᵗᵉⁿᵗ ᶦⁿᵃᶜᶜᵉˢˢᶦᵇˡᵉ ᵗᵒ ᵃⁿʸᵒⁿᵉ ᵇᵘᵗ ᵈᵉᵛᵉˡᵒᵖᵉʳˢ" @ow February 25, 2020
- Purpose per the creator: https://twitter.com/gruber/status/1232187113011056640
- "To be honest, I only designed it as a front-end for writers who already know HTML. I think for most people, something WYSIWYG is far more natural than Markdown. The problem is WYSIWYG widgets for HTML usually suck." @gruber February 25, 2020
- almost as bad at nested lists as RDF https://twitter.com/WebReflection/status/1270820434020372482?s=20
- "markdown UX shenanigans
1. this is parent
1. this is child 1
* this is parent
* this is child 1
one works, one doesn't ... the ordered list requires an extra space on the new line ... but *why* ???" @WebReflection June 10, 2020
- "markdown UX shenanigans