Markdown

Links

References

• Mastering MarkDown (GitHub flavor)
• Hyperpolyglot - Markdown, reStructuredText, AsciiDoc, Mediawiki, Org-mode

Tools

• GRIP — an offline MarkDown viewer (see tip further down also)
• Markdown viewer and editor (GitHub flavor)

Review

• Why You Shouldn’t Use “Markdown” for Documentation

This author advocates instead AsciiDoc (using Asciidoctor), or reStructuredText (using Sphinx).

Reference

Flavors

There are at least 3 main Markdown flavors:

• Original flavor from John Gruber.
• GitHub flavor (with eg. syntax highlighting extension).
• Pandoc flavor.

Tips

Preview standard MarkDown

Use markdown package.

sudo apt install markdown

Then, for instance, using entr:

echo README.md | entr sh -c 'markdown README.md > README.html'

This will generate a new README.html every time README.md is modified.

Preview Markdown before pushing to GitHub

Use the wonderful tool GRIP — GitHub README Instant Preview.

sudo apt install grip
cd /my/repo
grip                      # Now, open up browser to http://localhost:6419/

Comments in Markdown

We abuse link tags [1]:

[//]: # (This may be the most platform independent comment)

Align images

To center image on GitHub [2]:

<p align="center">
  <img width="460" height="300" src="http://www.fillmurray.com/460/300">
</p>

To left/right align:

<img align="left" width="100" height="100" src="http://www.fillmurray.com/100/100">
<img align="right" width="100" height="100" src="http://www.fillmurray.com/100/100">