Academic Writing in Markdown

Published:

Format and Print (with Marked 2 app)

TL;DR:

  1. Write in Markdown and use Marked 2 to style output files (pdf, docx, or html).
  2. Choose your citation style file (csl)
  3. Use a css template to style the texts (special attention to references)

I write in Markdown, usually with Ulysses or Bear. To share my writing with others, I convert the Markdown files into other formats, such as PDF or DOCX.

I use Marked 2 app (sorry, Mac only) to convert Markdown files and format the output files according to my needs. Long story short, Marked 2 converts a Markdown file into HTML document file, which in turn gets formatted according to a chosen CSS template.

CSS is a language that describes the style of an HTML document. CSS describes how HTML elements should be displayed.

Choose the Right Style

Marked 2 has a Style Gallery. I have contributed a template (Chicago Academic) based on the Chicago Manual of Style to this gallery.

Also, I have created additional templates for academic writing.

You can download these CSS templates here:

Formatting References

Check out the codes of Chicago Academic.css, which is based on The Chicago Manual of Style. There is a section for formatting output of pandoc-citeproc. In my case, I use hanging indent, which is also used by APA style. Feel free to adjust the style according to your needs.

As many academic researchers usually read papers in PDF format and write with Microsoft Word. To share my writing, I then convert my writing into PDF or DOCX format.

When you are ready, you can export your files in HTML format out of the Marked 2 app. Then you can print the HTML with your browser app.

Similarly, you can open the HTML files with Microsoft Word or other word processors. Then, you can save the HTML file in the DOCX format.

However, the page margins will likely be changed to the default setting for new documents. For example, I set the default margins of 1 inch for all new documents created in Microsoft Word.



Citation and References

TL;DR: Marked 2 App -> Preferences -> Advanced Set Path to: /usr/local/bin/pandoc Set Args to: -f markdown+smart -t html5 --filter=/usr/local/bin/pandoc-citeproc --bibliography ~/Zotero/Library.bib --csl ~/Documents/Zotero/Pandoc/CSL/amj.csl

Cite-while-you-write (CWYW)

Cite-while-you-write (CWYW) is the important step in academic writing. A good setup can make writing with Markdown and formatting with Marked 2 app much more rewarding.

The following posts have been essential for me to set up my CWYW workflow.

  1. davepwsmith - Academic writing with Scrivener, Zotero, Pandoc and Marked 2
  2. davepwsmith - Academic writing: Scrivener, Zotero, Pandoc, Marked 2
  3. Ralph Kabo - My workflow for transforming academic Markdown into beautiful Word documents

Ralph Kabo has developed DocDown, a native macOS app, to convert markdown files into Word documents. DocDown can use an existing Word document as the output template. It is a great solution for anyone looking to convert Markdown into Word documents on a regular basis.

Cite-while-you-write (CWYW) Solution 1: ZotHero via Alfred

  1. Discussion on Zotero Forum
  2. ZotHero Alfred Forum page
  3. Workflow on github
  4. Zotero plugins page

Generate “References/Bibliography” with Marked 2 app

You need:

  1. Zotero with BetterBibTex
  2. Pandoc and pandoc-citeproc
  3. Citation Style Language (CSL) file for the reference style of your choice. Preview and download at the Zotero Style Repository.

Marked 2 needs to be configured so that the “BibTex citekey” in the texts can be recognized. Also, this will create the corresponding references/bibliography section for your paper/manuscript.

To setup Marked 2 for processing the citations in your writing, you then navigate to the “Advanced” tab in “Preferences” and fill out the following:

  1. Check “Enable Custom Processor”
  2. Find the folder location of Pandoc on your machine (usually something like /usr/local/bin/pandoc) and make sure you have also installed pandoc-citeproc
  3. Paste the folder location in “Path”
  4. Find the path of Zotero library export (BibTex format)
  5. Find the path of the referencing style file (CSL format)
  6. Put the following in the “Args”:

-f markdown+smart -t html5 --filter=/usr/local/bin/pandoc-citeproc --bibliography [Zotero Library location from Step 4] --csl [CSL file location from step 5]

  1. On my machine, it looks like this:

-f markdown+smart -t html5 --filter=/usr/local/bin/pandoc-citeproc --bibliography /Users/xulelin/Documents/Zotero/Library.bib --csl /Users/xulelin/Documents/Zotero/Pandoc/CSL/amj.csl

Issues and Limitations

Export to Word documents with Marked 2

Marked 2 app seems to have issues with exporting files into Word documents. The formats defined by CSL files can be lost.

Solution 1: Export to HTML files and then open HTML file with Word. Then you can save to Word documents.

Solution 2: Use DocDown developed by Ralph Kabo. DocDown automates the conversion from Markdown to Word documents.