Plain Text Writing Lesson Seven: Markdown Resources and Editors

The first six lessons in my series on plain-text writing should be enough to get anyone–even the least techy–started with a complete plain-text writing workflow, using Gedit, markdown syntax, and Pandoc.

typora

Editing Markdown in Typora, an elegant editor for Linux, Windows, and MacOS

But I’m not done with the series look for more to come on editors, operating systems (and why you should seriously consider Linux), more advanced editing and markup with the amazing text editor emacs and orgmode, keeping a plain-text note system, and even ways to ditch the computer altogether but still take advantage of digital technologies in your writing. Also look for posts on other, more fun things you can do, like creating a whole-house music server with an old laptop, creating a writing computer you can take into direct sunlight using an old netbook and e-ink Kindle, the joys of the command line and terminal, and lots of other geeky fun tailored to the non-computer-geek user and writer. My goal is to make this incredibly useful technology accessible to everyone, especially those who don’t always feel comfortable with the kind of documentation that’s usually found online.

In the meantime, here are a few sets of additional resources: a breakdown of my own series so far, some important general resources for Markdown, and some recommendations for exploring the wide range of editors out there to find the one that’s perfect for how you work.

My Articles:

Here’s a complete index to my complete series so far on plain-text writing:

  • Lesson One: Writing in Plain Text: A Tutorial for the Non-Techy Writer: A general introduction to plain-text and explanation of its potential benefits for writers, especially over and above the traditional word processor.
  • Lesson Two: The Editor: How to download, install, and use a good all-around text editor called “Gedit”
  • Lesson Three: Markdown Elegance: An introduction to using Markdown syntax, geared toward the total beginner.
  • Lesson Four: Pandoc Magic: An introduction to Pandoc, a tool that allows you to convert your plain-text, markdown-enhanced documents to any other file format you want (Word, LibreOffice, PDF, html, etc.)
  • Lesson Five: Detangling Your Footnotes: How to create footnotes within a Markdown document, and why doing so makes them easier to manage than with a traditional word processor.
  • Lesson Six: Citation Wizardry: For the harder-core academics, this lesson covers how to do more complex citation and documentation management, pairing your markdown text with a citation manager such as Zotero, RefWorks, or Endnote. Most importantly, the lesson explains why and how managing citations this way can get rid of a lot of common citation headaches.

Markdown Resources:

  • The definitive resource on Markdown syntax, from its creator. A little more techy than my explanation, but important as the font from which springeth all things Markdown.
  • A very handy Markdown cheatsheet on github. Especially useful for beginners, for reference until you get used to the syntax you use most often (which won’t take long at all), and too keep handy for those times when you need to look up something that you don’t use as often. Put it in a text file you can pull up in your editor, or have a printout on your desk for reference. You’ll find that you don’t really need it after only a few writing sessions.
  • A nice little interactive markdown tutorial: Another very beginner-friendly tutorial that lets you try things out right in the browser as you go. If you’re still nervous about learning Markdown, start here.

Some Good Text Editors

Taste in text editors varies between writers and coders like taste in flavors of ice cream. There are a lot of choices out there, making it worth your while to explore and find one you really like. Some are more general purpose, some more specifically targeted. The general rule of thumb is that the editors that are the most graphical and simplest to use are often one-trick ponies–good for one thing but not much else. Editors that are more versatile and customizable tend to have a steeper learning curve, but the reward for the learning curve is a lot more ability to customize your editor to your particular needs and style of working. I suggest starting with an easy-to-use, simple editor first, but then experimenting with some of the more advanced editors to see what they can offer. I learned both vim and emacs very slowly, just experimenting with each a few minutes at a time, looking around at online documentation, and not worrying about doing anything with them right away. As a result, I’ve discovered ways to enhance my writing process that I’d never imagined.

Here’s a set of links to the editors I’ve found the most useful:

Gedit: I think Gedit offers about the best balance of features, simplicity, and ease of use. Definitely my recommended editor for beginners, and adequate for more advanced markdown users as well. – Also on the “easy but less versatile” spectrum, but also very useful for beginners, are specialized markdown editors that provide features like a dual-pane view that gives you an immediate preview of your markdown.

Typora is one of my favorites, offering live preview, and the ability to convert your markdown to various other document types right onboard. Especially good for those who want to use Markdown but who find the command-line interface of raw Pandoc intimidating.

For Windows users, Markdown Pad is one of more mature go-to-options. It also features a dual-pane view, where you write your markdown on the left side and see a live

markdownpad2

Using the live preview feature in MarkdownPad for Windows.

preview of the result on the right. There are both free and paid versions. The free one is very nice as an editor, and the paid version offers automatic conversion features, among other enhancements.

For those who desire a very distraction-free experience, WriteMonkey is a lean and elegant cross-platform writing app, with versions for Windows, Mac, and Linux alike. WM is designed to give you clean, minimal, full-screen interface, and supports Markdown. While it doesn’t give you a live preview like the previous two, it does feature syntax highlighting, which helps you keep track of your formatting.

Another great condender in this category is FocusWriter, a ‘zenware’ editor that really concentrates on a clean composition experience.

If you need or want to be able to work from anywhere within your browser (working on a borrowed computer, a public computer, or a Chromebook, for instance), I can’t recommend StackEdit highly enough. It gives you a real-time preview, seamless integration with cloud storage services like Dropbox, and–most useful for bloggers–the ability to publish directly from the app to your WordPress account. Stackedit is a chome app that runs in your browser, so you can work from any internet-connected device.

Other editors offer a more technical approach and are oriented toward writers of both code and prose.

My favorite of these is SublimeText. It’s probably the most elegant code and text editor out there, looks fantastic, and is extensible in ways few can imagine. It can provide tons of functionality, there’s a little bit of a learning curve, but it’s not that hard. One

download

Elegant editing in Sublime Text (here in Ubuntu Linux)

drawback is that ST is not technically free software. You can download a fully-functional evaluation copy to use for as long as you like (it’ll remind you occasionally about buying a license), but if you decide it’s the right editor for you and use it a lot, do the honest thing and pony up the (expensive but well-worth-it) $70 license.

For windows users, another contender in this category is the venerable Notepad ++, which has been a mainstay of coders and writers alike for many years.

A newer player in this category of editors is Atom, and is probably the best-looking editor in this list. It has similar functionality and complexity to Sublime Text, but is free and open-source, which makes it a preferable options for many. Like Sublime Text, it’s primarily geared toward coders, but has extensions that make it quite nice for writing if you’re willing to deal with a bit of a learning curve.

The Hardcore Options: Vim and Emacs

One thing I’ve learned about software since learning to program my first-ever computer (a Commodore 64!) in junior high: it’s always a trade-off. The easier an app is to use, the less versatile and powerful it will be. The higher the learning curve, the more powerful the app, and the more customizable to your own experience. The question to ask yourself is this: Do I want to work the way someone else thinks I should work, or do I want to work the way I want to work? If the answer is the latter, you owe it to yourself to look into one of the editors that takes a little while longer to learn, but gives you undreamed-of control, flexibility, customizability (is that a word?), and speed. There are really two major editors that fall into this category. While I started out with several of the editors listed above, I have to admit that these two have become my favorites, and my go-to editors for almost everything. They take a little more time and effort to learn–but once you learn them, wow–gangbusters! Each will get a post of its own here, but for the being short descriptions will have to suffice:

Vim is actually one of the oldest pieces of software still in continuous development, initially developed as an editor for the Commodore Amiga in the late 1980’s. It’s come a long way since then, but it’s a powerhouse that many coders and writers alike still swear by. It’s an app that runs without a GUI (that is, a “graphical user interface,”although there are GUI versions available), which means that it runs, regardless of platform, in a

VIM

Minimalist and lighting fast, but still powerful: Vim running on my desktop.

terminal window. One advantage of this is that it makes Vim the most blazingly fast editor on this list. Up and running in a keystroke. Its interface is keyboard-oriented, which means you never reach for the mouse, keeping your mind and hands on your writing. It doesn’t look like much, but the advantage is that it gets the heck out of your way and lets you compose and navigate easily through even long, complex documents. There’s a great beginner’s tutorial here if you’re interested in getting started. Look for a post from me on customizing it for writing.

Emacs is the other biggie in this category. Like vim, there’s a steeper learning curve associated with emacs, but I can tell you this: when I finally committed myself to learning emacs and discovering what it could really do, my reaction was “where have you been all my life?” I’m a little angry with computer scientists and programmers, truth be told, because they’ve been keeping all the best writing tools for themselves without letting

spacemacs

This blog post in Spacemacs, a variant of Emacs.

we writers know about them! Emacs definitely has a learning curve, but, in conjunction with a plugin called orgmode, it is hands down the most powerful tool for both note-taking and composition I’ve ever found. In fact, I wrote this post in a variant of Emacs called Spacemacs. I’m going to dedicate a whole series to Emacs later on, but, for now, there’s a good introduction for beginners here.

That’s it for now–have fun playing with the various editors and discovering more. And, as always, happy writing!

Advertisements

Plain-Text Writing Lesson Six: Citation Wizardry

Note: if you’re new to this series or to plain-text writing in general, please refer to Lesson One of this series to get started.

libraryAs I mentioned in the previous lesson, one of the biggest pains for me in academic writing is dealing with what happens to footnotes and citations in Word documents over the course of my writing process. Every piece I write goes through many stages of life: it starts as random jottings, becomes a general “idea draft,” then becomes a conference paper or a blog post, then an article or chapter, then a presentation, etc. Each of these versions goes through several revisions and I don’t know how much editing and refining. This means that citations get dropped, added and moved around; whole sections of one version get cut and pasted into another, sections get moved around, etc. And, of course, as I adapt a certain course of research to various publications and audiences, the style and formatting of the citations changes: one venue wants Chicago style footnotes, one wants endnotes, one wants MLA, ad nauseam.

One of the main issues that drew me to a plain-text workflow was what kept happening to my footnotes in word processors (Word and LibreOffice, for the most part), as my writing went through all these convolutions: it seemed that every time I moved things around or changed formatting, something would get messed up. When I converted from footnotes to endnotes or back again, the process never seemed to work as advertised, and I’d spend hours cleaning up formatting and manually fixing citations, even when using a citation manager like EndNote or Zotero (and sometimes because of the ways in which auto-inserted citations can get screwy when edited manually). If I needed to change style from MLA or Chicago or back, I’d wind up needing to go through an entire document and redo all the notes from scratch. All of this is not to mention the “cascade” effect, which I suspect you’ve experienced, of changing something in one note only to somehow throw off the formatting of the rest of them, or having note formatting fail to behave as expected, or even having notes change position or show up in the wrong place. There’s nothing more frustrating than pushing a deadline for an article only to find one’s self wrangling unruly citations.

There’s a better way.

Enter Pandoc once again, with some special extensions.

As with other elements of markdown writing, the idea here is that you insert citations as plain text right in line with the rest of your plain-text document. This means, for one thing, that citations always stay where they’re supposed to, even when you’re moving blocks of text around. The actual formatting of citations into different documentation and note styles (in-text citations, footnotes, endnotes, MLA, Chicago, APA, etc.) is something that only happens after your document is finished and ready to be prepared for publication. Just as you can transform any markdown document, via pandoc, into any digital format (Word, PDF, html, etc.), you can convert the plain-text, inline citations in any markdown document into any desired documentation style, without changing the original text. If you output to Word format at one point and then, say, make major edits and move sections around in your original plain-text document, you simply convert the plain-text document again and everything stays where it should and looks like it should with very little, if any, fuss.

Making this work might seem a little bit complicated at first, but I’ll try to detangle the process for you here. It’s really quite quick and efficient once you get the concept.

One thing I’ll assume in this post is that you’re already familiar with or using a citation manager such as Endnote, Zotero, or Refworks (I prefer Zotero). If you’re not, you’re really missing out on a handy tool, so I’d certainly recommend doing a little research and installing a citation manager that works for you. Zotero is clean, effective, versatile, as well as free and open-source, which is why it’s my manager of choice. In what follows, I’ll demonstrate the process with instructions for Zotero where needed, but everything I do with Zotero should be easily adaptable to the citation manager of your choice.

Step One: Enhance the Magic Wand:

To make citations work with pandoc, you need one additional tool, an extension to pandoc called pandoc-citeproc.

In any Debian-based version of linux, you can install this simply be opening a terminal and typing:

sudo apt-get install pandoc-citeproc

If you already installed pandoc in Windows, you should already have the pandoc-citeproc package, since it’s included in the Windows MSI installer, which you can find here.

Step Two: Gather the Elements:

In order to fully process citations in markdown, you need three elements:

  1. A bibliography file in bibtex format that will live in the same directory as your main markdown document. This is the file from which pandoc will draw the actual bibliographic data.
  2. Your markdown document itself, with correctly formatted citation placeholders (concerning which more below).
  3. A .csl file containing the formatting information for whatever documentation style you need or prefer.

Let’s set up these elements one by one:

A Bibliography File in Bibtex Format

This is quite easy to do. Assuming you’ve been keeping your bibliographic data in your citation manager, all citation managers have the ability to export a collection of citations into Bibtex format. In the case of Zotero, the procedure is:

  1. Open your Zotero app
  2. Right-click on the collection you want to export and select “Export Collection”
  3. In the ensuing dialog box, select “Bibtex” as your format, and click OK
  4. Specify a location for your bibliography file–this should be the same folder in which your draft document resides.
  5. Name the file whatever you like, and make sure it has a “.bib” extension.

This file will simply live alongside your text file in the same folder, so the citation information it needs is always handy. If, in the source of revising, you wind up adding sources to the original collection in your citation manager, simply delete the old .bib file and re-export the updated collection.

Format Your Citations As You Write and Revise

Dropping in-line citations into your document as you go could not be easier. Start by opening up your exported Bibtex file. As with the other components of this process, it’s also essentially a plain-text file, with no hidden formatting. You’ll see that each of your bibliography items is recorded as a record with several fields, like this:

 @book{gransden_historical_1974,
    location = {Ithaca, N.Y.},
    title = {Historical writing in England},
    isbn = {0-8014-0770-2 978-0-8014-0770-3 0-8014-1264-1 978-0-8014-1264-6},
    number = {Book, Whole},
    publisher = {Cornell University Press},
    author = {Gransden, Antonia},
    date = {1974},
    keywords = {chronicle, laercost}
}

You see that the record starts with an indication of the type of source (book, article, etc.). The next piece of information in each record is the most important for our purposes, the one that reads grandsen_historical_1974. This is called the citekey for this record–the unique ID that allows pandoc to differentiate it from every other record in the file. Dropping a citation into your document is very straightforward:

  1. Open a square bracket: [
  2. Type an @ symbol followed by the desired citekey
  3. Add any needed text or page numbers before and after the citekey.
  4. Close the bracket.

So, a normal citation would look like this:

Here is a brilliant sentence that requires a citation.[@grandsen_historical_1974]

That’s it. That citekey will follow that sentence wherever it goes.

If you want to add other information, such as discursive text, page numbers, etc., just add that text where you need it. Separate the page numbers from the citekey with a comma:

Here is a brilliant sentence that requires a citation.[If you need some discursive text, just add it inside the brackets before the citekey. See @grandsen_historical_1974, pp. 147-52]

If you need to include more than one citation, separate the citekeys with semicolons:

Here is a brilliant sentence that requires a citation.[Some discursive text. See @grandsen_historical_1974, pp. 7-9; also @anzaldua_borderlands:_2007, pp. 153-8]

Easy, yes? Once again, these citation placeholders will follow your text no matter what you do with it, just like any other kind of markdown formatting.

Grab The .csl File For Your Documentation Style

This might seem a little tricky at first, but it isn’t. The .csl file is simply a file that contains all the instructions for how final citations should be formatted according to a particular style (Chicago, APA, etc.). You can get a pre-made .csl file for most documentation styles from the Zotero Style Repository here. Simply find the style you want, click the link, and download the file into the same directory as your main text file and your bibtex file.

And Now, the Magic: Creating Fully-Cited Documents With One Swish:

Okay, now that we’ve got all the materials together, it’s time to tell Pandoc to do its thing. Let’s start with a sample markdown document with some citation placeholders included:

MD_Citations

 

Now we just need to tell Pandoc to put all the pieces together. At this point we should have three files in our document directory: Our text file, the .csl file for our chosen documentation style (I normally need the Chicago Full-Note and Bibliography style, so I’ve downloaded that one for this example), and the bibtex file containing our references, like so:

MyDocument.md
MyBibtexFile.bib
chicago-fullnote-bibliography.csl

Here comes Pandoc. Fire up a terminal and type:

pandoc MyDocument.md -s -S --bibliography MyBibtexFile.bib --filter pandoc-citeproc --csl chicago-fullnote-bibliography.csl -o MyFormattedDocument.odt

Let’s break down what each part of the command is doing:

  • pandoc simply invokes the pandoc app.
  • MyDocument.md tells pandoc which markdown document to process
  • -s -S These two tags tell pandoc to create a standalone document file, and to use smart quotes, respectively
  • --bibliography MyBibtexFile.bib Points pandoc to your bibliography file.
  • --filter pandoc-citeproc tells pandoc to use the pansdoc-citeproc tool to process your citation placeholders
  • --csl chicago-fullnote-bibliography.csl tells pandoc to format your citations according to the information in the chicago fullnote bibliography csl file, and points it to that file.
  • -o MyFormattedDocument.odt tells pandoc to output to an .odt (LibreOffice, OpenOffice) file named “MyFormattedDocument.odt” If you want a different file type, just change the extension (.docx for Word, .pdf for Portable Document Format, etc.)

And here’s the reveal, your fully formatted document:

Screenshot_Chicago

But let’s say (alas!) one publisher turns down that manuscript. You want to submit it elsewhere, but the new journal to which you’re submitting requires MLA rather than Chicago style. No problem–and no need to do anything with my original text document. I simply download the MLA 8th edition .csl file from the Zotero Style Repository, and change the pandoc command to use that stye:

pandoc MyDocument.md -s -S --bibliography MyBibtexFile.bib --filter pandoc-citeproc --csl modern-language-association-8th-edition.csl -o MyFormattedDocument_MLA.odt

And my output looks like:

Screenshot_MLA

There it is! While this tutorial takes a little longer to explain the process than some of the others, I hope it’s apparent how easy and muss-free this can be if you set it up as your workflow from the beginning. As always, I’m glad to field questions about the process. Happy writing!

Plain Text Writing Lesson Five: Detangling Your Footnotes

Note: This is the fifth instalment in a series of brief lessons on writing with plain text tools, such as basic text editors, Markdown syntax, and Pandoc. The lessons are designed with the nonmagic-wand-techy in mind, and are meant to
take about 5-10 minutes apiece to digest. If you’re unfamiliar with plain-text tools, I strongly recommend that you begin with the first lesson. This lesson deals with notes for which you’re hand-keying all the text. If you’d like to use footnotes or other documentation styles with a citation manager like Zotero, please refer to Lesson Six: Citation Wizardry.

Footnote Foofaraw

Now that we’ve got the basics of plain-text writing, using markdown syntax, and invoking pandoc for formatting, let’s tackle one of the more complex bugbears of writing, especially for academic writers: footnotes.

If you’re accustomed to using a traditional word processor such as Word or LibreOffice Writer, you’re aware that the initial steps for including footnotes are pretty easy: select “footnote” from an “insert” menu or hit a keyboard shortcut, an auto-numbered note shows up at the bottom of the page, and you type happily away (or insert a note or placeholder code from a citation manager like Zotero or Endnote). Easy peasy.

As you’ve likely experienced if you’ve done a lot of heavily-footnoted writing, however, the problem isn’t about adding the notes initially; it’s about maintaining their continuity and formatting down the line. This isn’t such a big deal for shorter-form writing (like blog posts), but it can be a very big deal indeed for longer, more in-depth work, such as articles and book chapters. The problem is that those longer pieces tend to travel a great deal before reaching their final (published) destinations: they go back and forth between writers, peers, peer-reviewers, editors, publishers, etc. As with all of the complex coding that underlies a word processor document, irregularities have a way of creeping in as the document is continually emailed, opened under different platforms or tools, edited and modified, etc. This process can turn those easily-added footnotes into a nightmare: if you’ve ever had the problem of suddenly finding that your notes are out of sequence, or that the formatting has suddenly changed and no change in settings seems to bring them back into order, you know what I’m talking about.

Markdown and Pandoc to the Rescue, Again

What’s handy about Markdown here is basically the same principle outlined in lesson three: You keep your original document in a kind of “raw” format in which everything is consistent, and then use Pandoc to turn that universal format into any other format an editor, publisher, or friend might require. In this way, your preferred formatting, and the position and style of your footnotes, is essentially always preserved in a consistent state in your original markdown document. Changes can be made easily in that Markdown document without any possibility of unintentionally adding code that will affect your formatting down the line. In other words, using Markdown and Pandoc together can mean that you’ll never again need to tear your hair out when your notes go haywire.

The How-To Bit

There are two different ways to create footnotes using Markdown. The first is entirely native to Markdown, and is ideal for shorter-form writing for the web (i.e. blog posts). The second requires Pandoc, but is ideal for longer-form writing where maintaining the consistency of many footnotes is important.

The Markdown Way

To create a basic Markdown footnote, place your cursor where you want the footnote to appear in your text and start with an open bracket, followed by a caret, a footnote name or number, and a close bracket, like this:

[^1]

Then, at the bottom of your main text, place the same sequence of characters again, followed by a colon, a space, and then the text of your note:

[^1]: Here is the text of the footnote.

In the final document, markdown will create a footnote at the bottom of your text that includes a link back to the in-text footnote marker, like this.1

This sort of footnote is excellent for web-oriented writing, since it assumes a contiguous text (i.e. no page breaks) and provides an easy way for readers to click back and forth between the superscript note indicators in the text and the notes themselves at the bottom.

However, it’s not difficult to see how these footnotes can become unwieldy with longer, more print-oriented documents with many footnotes. For one thing, creating them would mean constantly scrolling up and down your ever-expanding main text. For another, adding footnotes would mean manually re-numbering every note that comes after the newly added one. Talk about a pain!

Inline Footnotes in Pandoc

Luckily, we’re not stuck with native Markdown footnotes if we have Pandoc, which was introduced in Lesson Four.

Pandoc allows us to create inline footnotes, which are much more convenient for print-oriented writing that utilizes numerous notes and citations. To create an inline footnote, one simply places a caret at the point one wishes the superscript footnote indicator to appear, follow by the content of the note in brackets, thus:

##Using In-Line Footnotes with Pandoc

Here is my main text, rolling along and expressing its usual brilliance, followed by an inline footnote.^[Footnotes are cool.] As I continue to write, I can place additional footnotes using the same format.^[Cool like bow ties and fezzes]


When I run this through Pandoc, using the procedure outlined in Lesson Four, and open the resulting formatted text in a word processor (LibreOffice in this case), I get this result:

Output from Pandoc viewed in LibreOffice Writer.

Output from Pandoc viewed in LibreOffice Writer.

Note that Pandoc has automatically formatted and numbered the inline notes. It gets better. Let’s say I need to add a sentence to the above text that requires an additional note between the two initial ones, like this:

##Using In-line Footnotes with Pandoc

Here is my main text, rolling along and expressing its usual brilliance, followed by an inline footnote.^[Footnotes are cool.] I might even need to add a sentence that needs its own note later on.^[No, I'm not a *Doctor Who* fan. Why do you ask?] As I continue to write, I can place additional footnotes using the same format.^[Cool like bow ties and fezzes.]


Here’s the new output from Pandoc:

Pandoc output from edited original document.

Pandoc output from edited original document.

Notice that Pandoc has inserted the new note and automatically renumbered the other notes to accommodate my addition.

The value of creating notes this way for longer, more heavily-annotated documents should be apparent: instead of dealing with an “insert note” function at all, one simply creates all one’s footnotes right in line with the text, keeping the flow of thought contiguous and avoiding unnecessary keyboard commands. No matter how much the plain-text document is edited, and no matter how many notes are added or deleted in that process, running the plain-text document through Pandoc again will always renumber footnotes automatically, meaning that the output from Pandoc will always be a “fresh” word processor document, with all the formatting and numbering of notes perfectly consistent. No more fiddling around with footnotes that seem to have a mind of their own.

There can be even more flexibility when inline notes are used with a citation manager, which we’ll tackle in a future lesson.

For now, your five-minute assignment is to create a sample document with both native markdown and Pandoc inline footnotes (if you don’t remember how to use Pandoc, refer back to Lesson Four, linked above). Or, better yet, try out the note functionality in some of your normal writing.


  1. Click on the arrow at the end of this note to return to the note’s position in the main text.