Markdown is a system for generating HTML from readable but lightly marked-up text. It is now very widely used in blogs, README files and other repository-content, and wikis. I use it for a great deal of my own note-taking, much of which ends up in repositories (public and private).
Resources for learning Markdown
- Syntax of the original Markdown project. It dates from 2004 and was the work of John Gruber and Aaron Swartz.
- GitHub Flavored Markdown (GFM) is now very widely used because of its association with GitHub. It supports tables and has several resources for better presentation of code within a non-code document, such as "fenced code blocks" and syntax highlighting.
-
GitHub publishes
- a basic presentation of original Markdown rules and
- a shinier presentation of both original and GFM flavors.
Tools for previewing the output of a Markdown file
Be aware that you may occasionally have to tweak your files to get them to appear as you want them to. Not only is there no single Markdown standard, but the various tools for converting to HTML seem to vary subtly in their results.
- The "dingus" for viewing original Markdown as formatted text or HTML.
- HarooPad is the most flexible desktop tool I've found, although the current version (0.13.0) has small flaws. It supports GFM and MathJax, and it can be used to display slides written in Markdown.
-
Pandoc can convert Markdown to HTML. For example, to convert a GFM file "file.md" to an HTML file "file.html", use:
pandoc -sf markdown_github -t html file.md > file.html
Here
-sindicates we want a "stand-alone" file, rather than a fragment for inclusion into a pre-existing header and footer frame-fspecifies the format of the input file-tspecifies the format of the output file
It seems to me that HarooPad and Pandoc sometimes give slightly different output. My Pelican-based blog uses Pandoc (via IPython's
markdown.py), but it sometimes produces results that look different from the output of HarooPad and GitHub.
[end]