Dylan Storey

Recovering academic, hacker, tinkerer, scientist.

Academic Writing With Markdown

A Primer on using Academic Markdown.

##What is Markdown?

Markdown is a minimalist markup language for formatting text. It was designed with a core philosophy of being easy to read and easy to write. It is commonly used as a substitute for other markup languages like HTML or LaTeX.

##What is Academic Markdown?

It’s Markdown , but with just a little extra sugar to make things like citations simpler and provides the ability to apply journal/website specific rendering to the document to ensure that your document has specific and consistent formatting.

##Great, but why? I already use Microsoft Word. But which version? Is it from a Mac or a PC ? Did your collaborator remember to upgrade to the latest version? Is the document you sent out backwards compatible?

Markdown only requires a text editor to write. Any text editor. At all. It uses a plain text format that can be opened in any editor on any computer without having to convert it. Additionally once you’re done with writing you can convert your markdown into almost any format you want for publication (pdf, doc, rtf, docx, ODT, html ).

Microsoft Word is ubiquitous but I’m reasonably sure no one has gone their life without running into issues with Microsoft mangling it’s own file formats while converting from one document format to another, or having to painstakingly re do all of the formatting on a document because a collaborator changed it to something they preferred over what was required for submission. Plus , I’ve often worked with people who refused to purchase Microsoft Word for economic or personal reasons. (I work with myself daily after all.)

##Software Requirements:

Required for writing:

Text Editor: I use Sublime 3, I like it so much I even bought a license. The trial version works forever with limited feature support though. If you’re strapped for cash and want a feature rich editor Notepad++ for Windows , geany on Linux, and Text Wrangler for Mac are all good choices.

Required for Compiling:

PanDoc: PanDoc is a program that can interchange almost any text format to another text format. Installation instructions here. Linux users - do not install pandoc using apt or yum!

Terminal:You’ll need to run a few command line tools in order to compile the document from Markdown to another format. You’ll do it here. Linux users should already know where there terminal is and how to get to it. Mac users, search “terminal” in spot light. Windows users, I’ve seen numerous suggestions for “PowerShell” never used it myself though.

Additional Software Recommended:

Citation Manager: Zotero, Endnote, or Mendeley are all good choice. You’ll specifically want to export your citations for a paper or article in the bibtex format for cross linking. (I personally use Mendeley.)

LaTeX: If you want to specifically create PDFs of your work , you’ll need this installed. I wouldn’t worry about this immediately.

Chrome Preview: Markdown Preview Plus Is a fantastic chrome extension for previewing your document on the go.

The Basics

Setting Up Your Directory:

I use this as the basic directory structure for all my documents. The AMd file is where the actual writing occurs. The bib file is my bibtex formatted citations. I keep images and figures in the Figures directory. The csl file provides the citation formatting rules for the journal I’m submitting to. The best part is all of these files are plain text so tracking versions and progress with git is straightforward.

|-- Manuscript.AMd
|-- citations.bib
|-- Figures/
+-- science.csl

Actually Writing:

The Header:

All AMd files are to start with a header. This is a YAML markup that just tells the compiler a few things, like what citations I’m using who authored it , when it was started, etc. The first three entries should be self explanatory. The bibliography is the relative or absolute path to the bibtex file that contains your citations. The csl file is the relative or absolute path to the csl file that contains styling.

---
title: Test Document
author: Dylan Storey 
date: November 23rd 2015
bibliography: bibliography.bib
csl: science.csl
---

The Body

Writing in markdown is simple. Paragraphs are denoted by a blank line.

Paragraphs:

This is a line. It is also a paragraph.

This is a second paragraph.

Headers:

  #Level 1 
  ## Level 2
  ### Level 3
  #### Level 4
  ##### Level 5
  ###### Level 6

Text Styling:

*This will be italic*
_This will be italic_

**This will be bold**
__This will be bold__

__ *This will be bold and italic * __

Lists:

  • Unordered:
  * Item 1
  * Item 2 
  * Item 3

  - Item Foo
  - Item Bar
  - Item Baz
  • Ordered:
  1. Item
  2. Item
  3. Item
  • Nested: Just add an extra indent!
  1. Item
      1. Sub Item
      2. Sub Item
  2. Also an Item

  * Unordered Item
      * Sub Item 
      * Sub Item

##Figures:## These are pretty simple.

If you simply want an image to show up.

  ![alt text](Figures/image.png)

##Inline Citations:##

A brief note on bibtex.

This is a bibtex formatted citation:

  @article{Meier-Kolthoff2013,
  author = {Meier-Kolthoff, Jan P and Auch, Alexander F and Klenk, Hans-Peter and G{\"{o}}ker, Markus},
  doi = {10.1186/1471-2105-14-60},
  file = {::},
  issn = {1471-2105},
  journal = {BMC bioinformatics},
  keywords = {Archaea,Archaea: classification,Archaea: genetics,Bacteria,Bacteria: classification,Bacteria: genetics,Confidence Intervals,DNA,DNA: chemistry,Genomics,Genomics: methods,Models, Statistical,Nucleic Acid Hybridization,Nucleic Acid Hybridization: methods,Phylogeny,Regression Analysis,Sequence Analysis, DNA},
  mendeley-groups = {Informatics Tools},
  month = {jan},
  number = {1},
  pages = {60},
  pmid = {23432962},
  title = ,
  url = {http://www.biomedcentral.com/1471-2105/14/60},
  volume = {14},
  year = {2013}
  }

It holds all of the information you’ll need. There is one very special field though. After @article you’ll see an identifier. This is the unique identifier for this article. It MUST be unique. Your reference manager takes care of that for you.

Citing an article simply requires the following.

  This is a fact that has evidence [@Meier-Kolthoff2013].

That is all.

##Citations List:## Simply type the following:

  #References

Many citation style available here

#Compiling your Document#

To create a Word Document:

  pandoc -o document.docx test.AMd

To create an Open Office Document:

  pandoc -o document.odt test.AMd

To create a pdf:

  pandoc -o document.pdf test.AMd

To include citations:

  pandoc -S -o document.docx --filter pandoc-citeproc test.AMd 

To use extensions (talked about below a little):

  pandoc test.AMd --from markdown+implicit_figures+pip_tables+table_captions -o myReport.pdf

#Advanced-ish Markdown#

##Figures:##

Implicit figures(implicit_figures):

We usually want captions with all figures so we use implicit figures to compile the document.

  ![The caption goes in here](FigUres/image.png)

To revert back to normal syntax simply add a trailing slash.

  ![This is alt text](FigUres/image.png)\

##Tables:##

These examples were all taken from the pandoc documentation directly.

There are a few ways to write tables in Markdown. These are all supported by specific extensions in pandoc. (We’ll talk more later about that.)

Simple table (simple_table and table_captions):

        Right     Left     Center     Default
      -------     ------ ----------   -------
           12     12        12            12
          123     123       123          123
            1     1          1             1

      Table:  Demonstration of simple table syntax.

The table MUST have a blank line after it. The Table: tag marks the caption for that table.

Rules for justified text in the table (via pandoc documentation):

  • If the dashed line is flush with the header text on the right side but extends beyond it on the left, the column is right-aligned.
  • If the dashed line is flush with the header text on the left side but extends beyond it on the right, the column is left-aligned.
  • If the dashed line extends beyond the header text on both sides, the column is centered.
  • If the dashed line is flush with the header text on both sides, the default alignment is used (in most cases, this will be left).

Multi Lane Table (multiline_table and table_captions):

The exact same as simple tables, but with the following caveats:

  • Must begin with a row of dashes
  • Must end with a row of dashes
  • Rows must be seperated by blank lines
      -------------------------------------------------------------
       Centered   Default           Right Left
        Header    Aligned         Aligned Aligned
      ----------- ------- --------------- -------------------------
         First    row                12.0 Example of a row that
                                          spans multiple lines.

        Second    row                 5.0 Here's another one. Note
                                          the blank line between
                                          rows.
      -------------------------------------------------------------

      Table: Here's the caption. It, too, may span
      multiple lines.

Grid tables (grid_tables and table_captions):

  • The row of = seperates the header from cells
  • Cells may contain arbitrary elements (paragraphs,code,lists,images,etc.)
  • No alignment of text
  • Cells may not span multiple rows or columns
   +---------------+---------------+--------------------+
      | Fruit         | Price         | Advantages         |
      +===============+===============+====================+
      | Bananas       | $1.34         | - built-in wrapper |
      |               |               | - bright color     |
      +---------------+---------------+--------------------+
      | Oranges       | $2.10         | - cures scurvy     |
      |               |               | - tasty            |
      +---------------+---------------+--------------------+

      Table: This is a grid table

Pipe tables ( pipe_tables and table_captions) :

  • Pipes required between all columns
  • Colons used to denote column alignment
      | Right | Left | Default | Center |
      |------:|:-----|---------|:------:|
      |   12  |  12  |    12   |    12  |
      |  123  |  123 |   123   |   123  |
      |    1  |    1 |     1   |     1  |

       Table : Demonstration of pipe table syntax.
blog comments powered by Disqus