I love Markdown

Markdown is lightweight convention for text documents.

I love Markdown.

Markdown (md) format is simple, portable across platforms, has some semantic meaning, and can be shared easily. It combines the flexibility of pure text documents with formatting inside viewers that support it. Editing Markdown is easy: just use any text editor. The viewing / rendering support is easy to implement as well.

Here is an example content:

this is a header

This is normal text, some words are in italics, bold, or monospaced

Here is the Markdown source for the two lines above:

## this is a header

This is normal text, some words are in *italics*, **bold**, or `monospaced`

You can even move long links to the bottom of the page like this

instead of [this link](http://google.com)
you can move actual link to [google][1] to the bottom
[1]: http://google.com

Markdown applications

The tiny list of places where Markdown took hold:

  • github renders .md files by default. Placing a README.md in the project's root folder shows a rendered view by default, see this example. Note how the build badges are rendered as images. I think github did more to promote the organical growth of Markdown than any other factor.
  • HTML5 presentation frameworks, for example reveal.js or remark transform markdown content into HMTL5 presentation on load. My own slides-now allows to simply drag and drop a .md file to a browser to play the presentation, no viewer installation software required.
  • blogging platforms, for example ghost or calepin that use Markdown by default dramatically simplify the writing process.
  • node package manager looks for README.md file inside the package folder, and complains if there is none. It forces the developer to describe the package, even at some rudimentary level.
  • You can even use markdown as a templating language

The growing support and acceptance of Markdown is eating the market share of two content formats: unstructured text files and HTML pages. Why spend time writing repeatative tags, worrying about a webserver or browser to render the HTML, when all you need is arrange the text content a little?

Bonus - using Markdown from your JavaScript (browser + node)

A cool project Logdown allows you to log to terminal or browser console from JavaScript using markdown. Just use the following from your code

1
2
3
var Logdown = require('logdown');
var log = new Logdown({ prefix: 'foo' }); // allows to enable / disable (hide) all messages
log.info('this *HAS* markdown `here`!');

Output: this HAS markdown here!

Good Markdown summary in Adam Pritchard: Markdown Cheatsheet

Bonus 2 - summary and details

If you have optional content not to show by default, you can use HTML elements to hide it.

<details>
    <summary>Text to be displayed when collapsed</summary>

    <p>Additional details to show when the <i>user clicks</i> on the summary...</p>
</details>

Note, the details content cannot use Markdown, but can use HTML. Here is the above example in action:

Text to be displayed when collapsed
<p>Additional details to show when the <i>user clicks</i> on the summary...</p>