Academic writing extensions to Markdown
Mandown provides simple extensions to the Markdown syntax that are useful for academic writing.
Writing a paper using Mandown is simple: write your paper using standard Markdown syntax and the Mandown extensions where necessary, then process your file using the Mandown tools. These will generate a standard Markdown file containing your citations, bibliography etc. Then process the resulting file using a suitable Markdown processor (I recommend using Pandoc, which will generate RTF files that can be opened using Microsoft Word).
‘Mandown’ is a portmanteau of ‘Markdown’ and ‘manuscript’ which I found appropriately amusing (“Man down!!”).
Mandown is at an early stage of development and is not quite ready for use on real work. However, it still might be useful to you and I’d appreciate early feedback. It is easy to install, upgrade and uninstall Mandown, so if you’re interested, please give it a try.
Academics typically write papers using either LaTeX or Microsoft Word. Word is often favoured by the less technically inclined (or those who are simply ignorant of the existence of alternatives). LaTeX is used for some combination of the following reasons: it’s free software; it can produce typographically excellent output; LaTeX documents are plain text files which can be edited using powerful text editors (vi, Emacs, TextMate etc.). Those who would otherwise choose LaTeX are often forced to use Word by their co-authors or the publishers of their work, and would like a way to maintain the benefits of their LaTeX environment while being able to produce Word documents. Mandown provides tools to allow this.
Mandown is not attempting to be a document preparation system like LaTeX; if you can use LaTeX you probably should—it’s far more powerful than Mandown. For example, Mandown will have no support for controlling page layout or inserting and controlling graphics (though it will support the concept of figures).
Mandown is implemented as a set of command line tools that can be chained together into a pipeline. In future, further extensions to Markdown will be developed and implemented (e.g. figdown will support figures, another tool will support sectioning, labels and referring, etc.). Mandown is distributed as a gem for ease of installation (see the next section).
Mandown is distributed as a Ruby gem (so you’ll need Ruby and RubyGems installed already). To install, type something like:
sudo gem install mandown
(If you are confused already, read the Really Quick Start guide from the RubyGems user guide and note that you may or may not need the sudo command: it’s necessary on Mac OS X, but on other systems you might need to become the super user first by running the
su command and entering the super user’s password, and then running
gem install mandown.)
This will add the Mandown programs (executable Ruby scripts).
You will also need to install a suitable Markdown processor. I recommend Pandoc which can convert Markdown to multiple output formats, including RTF which can be opened using Microsoft Word.
The following Mandown tools are provided in the latest release:
bibdownCite publications and build a bibliography.
secdownAutomatically insert section numbers.
mandown-sampleOutput a sample Mandown source document.
First you need to write a manuscript using a combination of the Markdown and Mandown syntaxes, but to get you started Mandown includes a sample Mandown document (see the example, below). Markdown and Mandown are very simple and all you need is a plain text editor (don’t save your Mandown files as Word documents, they must be plain text files).
Each Mandown tool adds one or two simple extensions to Markdown; for example
bibdown adds the
cite: syntax to cite references and allows you to specify your bibliography in YAML format.
Each tool provides its own documentation via a
--help option, for example type
to learn how to use the bibdown tool and see its syntax.
Because each Mandown tool does one thing and adds only one or two syntax extensions, you can easily learn just the ones you need and ignore the rest (or perhaps contribute your own).
Let’s read an example Mandown manuscript using the
mandown-sample | less
mandown-sample program simply outputs the sample manuscript.
(Note how papers are cited using the
cite: command. Also scroll to the bottom and have a quick look at the YAML-format bibliography.)
We want to process this document using Mandown (and then Pandoc), so first save the sample to a file:
mandown-sample > sample-manuscript.txt
Now let’s process this sample manuscript using
cat sample-manuscript.txt | bibdown > sample-markdown.txt
This uses the
cat program to send the
sample-manuscript.txt file to
bibdown using a pipe (via the
| character), and then saves the result to a file called
sample-markdown.txt (via the
bibdowninterprets the bibliographic aspects of the Mandown syntax and renders them using Markdown. The result can then be processed using a Markdown processor such as Pandoc:
pandoc --smart -s sample-markdown.txt -o manuscript.rtf
You could now open the
manuscript.rtf file using an application like Microsoft Word or OpenOffice.org.
The Mandown tools are designed to be chained together into a pipeline, so for example you might do:
cat my-manu.txt | bibdown | secdown > my-manu-out.txt
Mandown is undergoing steady development and currently has a 0.0.x release number. I’m hoping to get first versions of the most important tools finished soon. At this point Mandown will be given the 0.1.0 version number, to indicate that it is suitable for people to start using it (even if just in an experimental context).
If you use the early versions of Mandown and want to keep up-to-date, simply run
sudo gem update mandown
You may also optionally remove previous versions using:
sudo gem uninstall mandown --version x.y.z
sudo gem uninstall mandown
and then install Mandown as usual.
Help, gotchas and FAQ
Q1: How do I …
Email me; there isn’t much implemented yet, but the bare bones are there. No guarantees, but I’ll try and take your feature requests into consideration. Or better yet, send me code!
Q2: I have a problem running bibdown.
Check that you are not using hard tabs; AFAIK, Ruby’s YAML parser requires that soft tabs (i.e. emulated using spaces) be used. Also check the alignment of the various fields.
Q3: bibdown chokes on titles etc. that contain colons.
Surround the title in quotes; these will be ignored, but fix the problem. I think this is a bug in Ruby’s YAML parser (as of Ruby 1.8.6).
Q4: The tools don’t run.
Mandown requires Ruby version 1.8.6 or higher, and the ruby interpreter program should probably be on your $PATH. If you installed Mandown from the gem, then the tools should be on your system’s $PATH and you should be able to run them. To verify that the tools are on your system’s $PATH, type
If a path is reported to the bibdown program, then it is on your $PATH and should be executable; try running
Otherwise please get in touch with me.
If you would like to contribute to Mandown, please email Chris Rose
The trunk repository is
svn://rubyforge.org/var/svn/mandown/trunk for anonymous access.
Mandown would not be possible without the excellent tools provided by the Ruby community. In particular, the Ruby standard library YAML parser, Nic Williams’ newgem and the Ruby Forge project have made Mandown much easier to develop and distribute. Thanks!
This code is distributed according to the terms of the GNU General Public License; see the file
COPYING for full details.