Markdown Referencing

One of the valuable lessons that I learned when migrating from WordPress to Nibbleblog just over a year ago now, is to never rely on a plugin for any key elements of your content.

For some of my more formal writing I used a referencing plugin which was simple and worked as required. After using Zotero (free and open source) to generate footnotes in the correct style, I simply added each footnote to the text. The plugin then automatically generated a superscript number and the full reference list at the bottom.

Unfortunately this turned into an ugly mess post-migration. The full references ended up in the middle of the text surrounded by the plugin tags, like so:

[acp footnote]Michael A. Arbib and Giacomo Rizzolatti, "6: Neural Expectations," in The Nature of Concepts: Evolution, Structure, and Representation, ed. Philip Van Loocke (London: Routledge, 1999).[/acp]

Now imagine that happening another twenty times in the same text. It simply makes the content ugly and unreadable.

So, what to do? One of the seemingly easiest ways to reference would be to use your text editor of choice along with its built-in footnote generator. Both LibreOffice Writer and Microsoft Word provide the capability to export your document as an HTML page. The problem with this approach is that it creates a grossly bloated web page when all you really need is the body text to be correctly formatted.

One alternative would be to use a referencing format that leaves references in the middle of your text. This comes down to personal choice and requirements, but I have always found that this approach vastly diminishes readability. From a graphic design perspective, it implies that the reference is on an equal footing with the text, and must be read, whether you like it or not. The reading experience should always be the core priority of any written content. Forcing people to read tedious references or engage in visual bracket hurdling, is often a terrible design choice and should be avoided in most cases.

The solution that I have settled on is the simplest and most minimalistic of all: markdown referencing. You have two options using this method. Both are effective and ensure maximum compatibility with any HTML compliant platform, including the ePub format.

Hard-coded references

Hard-coding your references means that you can use practically any text editor that you like (e.g. Vim). Unfortunately, the downside to this approach is that it becomes incredibly cumbersome to add new references or to make any further changes, especially if you happen to have many references. Any changes would require you to manually update each reference number.

The first step is to create a superscript hyperlinked number at a relevant point in your text, like so:

<p>So and so says such and such.<a href="#1"><sup>1</sup></a></p>

In our references section at the bottom we then add the relevant footnote generated by Zotero.

<p id="1">1. Steele, R. S., and Morawski, J. G., "Implicit cognition and the social unconscious," <em>Theory and Psychology</em> 12, no. 1 (2002): 37-54.</p>

That creates an internal link or anchor point straight to the relevant reference. Subsequent references will have to be correctly numbered in order to link to the right reference.

Wiki-generated markdown references

In this example I have used DokuWiki to automatically generate numbered references. DokuWiki is free and open source, runs without a database, and like most wikis provides a versioning capability so that you can revert to old changes. You will need a webhost to run DokuWiki, but this should be easy to do, as many provide a quick one-click installation of the software.

Once you have DokuWiki up and running, adding two brackets within the text of any page creates a reference. Just add your correctly formatted reference in between those double brackets:

So and so says such and such.((Steele, R. S., and Morawski, J. G., "Implicit cognition and the social unconscious," //Theory and Psychology// 12, no. 1 (2002): 37-54.))

Any subsequent references are correctly numbered and linked. Now all we need to do is to export the body as XHTML, by adding ?do=export_xhtmlbody to the end of the URL for the wiki page (DokuWiki also has a range of other export options, including export to an ODT document).

You should now have an XHTML compliant version of your wiki page. Save the page or view the source and copy its contents. It should look similar to this:

<h1 class="sectionedit1" id="important_research">Important Research</h1>
<div class="level1">
<p>
So and so says such and such.<sup><a href="#fn__1" id="fnt__1" class="fn_top">1)</a></sup>
</p>
<p>
A study says this and that.<sup><a href="#fn__2" id="fnt__2" class="fn_top">2)</a></sup>
</p>
</div>
<div class="footnotes">
<div class="fn"><sup><a href="#fnt__1" id="fn__1" class="fn_bot">1)</a></sup> 
Steele, R. S., and Morawski, J. G., “Implicit cognition and the social unconscious,” <em>Theory and Psychology</em> 12, no. 1 (2002): 37-54.</div>
<div class="fn"><sup><a href="#fnt__2" id="fn__2" class="fn_bot">2)</a></sup> 
Luis M. Augusto, Unconscious knowledge: A survey, <em>Advances In Cognitive Psychology</em> 6 (2010): 117.</div>
</div>

Pasting this output into a source code editor should leave you with a correctly formatted and referenced web page. That's it! You now have a page that should display correctly on every web browser and survive any number of platform migrations (view a finished example). The added bonus is that you also have a source of writing ready for all sorts of other publishing platforms, including ebooks.