or, What the heck is this .md file you sent me?
This page is primarily aimed at people I am working with who have received a bizarre .md file from me and are wondering how to read it. But I hope those who are interested in working with digital documents may also find it useful as an introduction to the excellent markdown format. Below I have some notes on more “advanced” markdown usage as well.
A .md file is plain text: that is, anything that can open a .txt file (like TextEdit on the Mac or Notepad on Windows, or even Microsoft Word) can open a .md file, and you will be able to read its contexts. Plain text means that there is no special formatting information: it’s just a string of regular characters: letters, numbers, spaces, and a few extra sigils like # and *. So go ahead and just open and read (and edit at will).
How it works
But markdown is more than plain text, because those extra sigils are used to indicate some structure and formatting: headings and subheadings, boldface and italics, and a few other things. Markdown is actually a minimal markup language, like HTML; in fact it is designed to be automatically converted to HTML by a conversion program. (Some websites even run these programs silently for you: you can write a tumblr post in markdown and it will automatically generate the HTML for the formatted page when you post.)
But unlike HTML, markdown is meant to be read by human readers and not just webpage designers: if I send you a markdown file you don’t need a special program to read it.
Here are the formatting sigils: I use # and ## and ### for headings and subheadings and subsubheadings, *italics* for italics and **bold** for boldface. Links are written in two parts: the actual URL and the text of the link:
[this is a link to my home page](http://andrewgoldstone.com)
Which comes out like this on a webpage: this is a link to my home page. And block quotations are notated thus:
> A block quotation. Markdown is the gateway drug of
> markup langauges. Soon I will have you LaTeXing away.
which comes out like this on a webpage:
A block quotation. Markdown is the gateway drug of markup langauges. Soon I will have you LaTeXing away.
Lists have each line beginning with a hyphen and a space, - ; or with a number and period, 1. .
Now you can read my markdown—and edit it too!
References
For the full run-down on markdown, there is an exhaustive markdown specification. That is accompanied by a “dingus” which lets you see the HTML equivalent, rendered or source code, of markdown as you type it. (Markdown has ramified into quite a few “flavors,” whose fine distinctions reasonable people can for the most part ignore. The specification is for “CommonMark.”)
Advanced usage: conversion programs
I use markdown extensively in my own writing, in conjunction with other formats and programs: see my page on digital documents. My notes from a DH@RU text-processing workshop include discussion of markdown in relation to HTML and LaTeX.
In order to turn markdown into HTML and other formats, I use the outstanding markdown-converter pandoc. Pandoc is actually much more than a markdown-to-html processor. In particular it can also generate LaTeX from markdown, which can be processed into a PDF using pdflatex or xelatex. (Or it can do these two steps together for you, in a seamless markdown-to-pdf conversion.) For some of my course websites (e.g. the 2012 version of Twentieth-Century Fiction I), I used pandoc to generate both the HTML for the site and the LaTeX that leads to the printable PDF syllabus.) Pandoc runs in the reverse direction as well (e.g., from LaTeX to markdown).
There are also “static site generation” programs that specialize in converting markdown files into a whole site’s worth of webpages. This website is generated in Hugo. Jekyll is widely used, and it underlies Github Pages. Normally jekyll does not use pandoc but other markdown converters like kramdown, maruku, or rdiscount. These work fine for specification-compliant markdown. To use pandoc’s fancier features one needs a little plugin for jekyll. Here’s a github gist with a very minimal one that seems to do the job. It requires the pandoc-ruby gem.
Pandoc also makes it possible to generate slides for presentations from Markdown. I have written about the…subtleties involved in Easy Lecture Slides Made Difficult with Pandoc and Beamer; Ben Schmidt demonstrates his approach in Markdown, Historical Writing, and Killer Apps and sequel blog posts.
Finally, the practice of mixing discursive text and programs to process data (“literate programming”) is currently trendy. R Markdown allows you to mix markdown text and R code. Use the powerful knitr package to run the R, generating ordinary markdown, which you can then process in pandoc. Or let the RStudio IDE, which has strong R Markdown integration, do all that for you.