markdown
This article is a stub. You can help the IndieWebCamp wiki by expanding it.
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 (e.g. HTML). Markdown is often used in README files and some online discussion forums.
Contents |
Principles
Readability
As readable as possible is the most important Markdown design goal.[1]The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible.
IndieWeb Examples
Indieweb participants using markdown on their personal site, for authoring text posts (e.g. notes, articles), editing text, and sometimes publishing / syndicating text.
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[2]
-
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.
- https://raw.githubusercontent.com/bcomnes/bcomnes.github.io/master/_posts/quill.p3k.io/2015-03-28-173-of-unreleased-ap.md
- https://raw.githubusercontent.com/bcomnes/bcomnes.github.io/master/_posts/notes/2015-03-17-kilauea.md
- https://raw.githubusercontent.com/bcomnes/bcomnes.github.io/master/_posts/notes/2015-04-03-clbp.md
-
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?)
Dialects
Markdown comes in many flavors...
- basic Gruber Markdown
- Github-Flavored Markdown
- StackOverflow Markdown
- MultiMarkdown
- Markaround
- kramdown (basic plus some extensions from PHP Markdown and Maruku)
- ...
And has many extensions to the basic syntax:
Criticism
Not pretty
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
Underspecified
- Under-specified, leads to many implementations, fragmentation. e.g.,
GitHub-Flavored Markdown
```php
code sample
```
vs. kramdown
~~~~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
considered harmful
ugly enough to consider separate text plain
See: https://indiewebcamp.com/irc/2016-06-03#t1464937740573
Tantek Çelik well if markdown adhered to its principles it would work *just fine* as the text/plain part
And: https://indiewebcamp.com/irc/2016-06-03#t1464938023495
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.
Tools
Firefox Addon
Sessions
IndieWebCamp sessions that discussed markdown:
Articles
Articles, blog posts, opinions about markdown (in particular from IndieWeb community members)
- Wiki page: Tantek Çelik: Thoughts on Markdown (wiki)
- 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.
- ...
