markdown

From IndieWeb

Two pane comic buttons with different link/text syntax and a sweating person pondering which to choose

This article is a stub. You can help the IndieWeb wiki by expanding it.

Markdown is a format for writing plain text with special punctuation that can be converted to more explicitly meaningful or richly styled text like HTML, and is used by many IndieWeb tools and sites for authoring posts.

Markdown is often used in GitHub, e.g. README files, and some online discussion forums.

Markdown is a lightweight markup language that is roughly in the middle of a spectrum between auto-linked plain text and more full-featured markup languages like HTML.

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

Alternatives

Lightweight markup alternatives to Markdown being used or considered by IndieWeb community members:

Dialects

Markdown comes in many flavors...

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.

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

Not escapable

Markdown has no way specified way of escaping characters when used in a Markdown context.

For example, the Gitlab Slack integration uses Markdown to mark up messages, which breaks when the commit-message contains Markdown characters.

Example: Someone pushed *'remove all bla_* methods'*

Becomes: Someone pushed 'remove all bla_ methods'*

considered harmful

Markdown considered harmful

ugly enough to consider separate text plain

See: https://indiewebcamp.com/irc/2016-06-03#t1464937740573

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

And: https://indiewebcamp.com/irc/2016-06-03#t1464938023495

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.

Tools

Firefox Addon

Articles

Articles, blog posts, opinions about markdown (in particular from IndieWeb community members)

Sessions

IndieWebCamp sessions that discussed markdown:

Tools

  • Pandoc is a format converter which understands most dialects of Markdown
  • Babelmark 2 is a behaviour/output tester for numerous implementations of Markdown parsers

Other Alternatives

Using a minimum amount of features to make your markup cross-compatible:

Comparison table of a few, relatively well-known alternatives:

See Wikipedia for more (no need to duplicate Wikipedia thoroughness here)

See Also

Retrieved from "https://indieweb.org/wiki/index.php?title=markdown&oldid=94540"