Writing in Markdown
Published:
Cite-while-you-write (CWYW) with Zotero
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.
Steps:
- Write with Zettlr
- Write with other editors (macOS)
Zotpick.applescript by davepwsmith
Add the script file to ~/Library/Scripts folder, then find it via System Preferences/Keyboard/Services and create a hotkey combination
Or copy and paste the codes below into Alfred/Keyboard Maestro & run the script upon hotkey
tell application "System Events" try set appName to (the name of every process whose frontmost is true) as string on error errMsg display alert "Problem" message "Could not get the name of the frontmost application." error number -128 end try end tell set zotRunning to do shell script "/usr/bin/curl 'http://localhost:23119/better-bibtex/cayw?probe=probe' 2>/dev/null; exit 0" if zotRunning is "" then display alert "Zotero not running" message "This script will not work unless Zotero is running. Please launch Zotero and try again" tell application appName activate end tell error number -128 else if zotRunning is "No endpoint found" then display alert "Better BibTeX not installed" message "This script will not work unless Better BibTeX is installed. Please make sure that Better BibTeX is installed in the running instance of Zotero" tell application appName activate end tell error number -128 else if zotRunning is "ready" then set theReference to do shell script "/usr/bin/curl 'http://localhost:23119/better-bibtex/cayw?format=pandoc' 2>/dev/null; exit 0" try repeat until application appName is frontmost tell application appName to activate end repeat on error errMsg display alert errMsg end try tell application "System Events" try keystroke theReference on error errMsg display alert errMsg end try end tell end if
Export with Marked 2 app
- To share my writing with others, I use Marked 2 app (macOS) to convert the Markdown files into other formats, such as PDF or DOCX.
TL;DR:
Configure Marked 2 to process citation in markdown files (.csl)
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
Preview/drag&drop markdown files in Marked 2 app
Choose the styles for the document (.css)
Export to PDF, DOCX, or HTML(special attention to references)
Configure Marked 2 App
You need:
- Zotero with BetterBibTex
- Pandoc and pandoc-citeproc
- 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:
- Check “Enable Custom Processor”
- 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
- Paste the folder location in “Path”
- Find the path of Zotero library export (BibTex format)
- Find the path of the referencing style file (CSL format)
- 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]
- 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
Select Document Style
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.
- I created additional (CSS) templates for academic writing.
- Chicago Academic.css: based on The Chicago Manual of Style
- AMJ Academic.css: based on the Academy of Management Journal Style Guide for Authors and the guide to AMJ referencing style (Library at the University of Queensland)
- Academic CV.css: suitable for both academic and industry CVs
- Academic Review.css: based on Academy of Management’s Reviewer Guidelines, particularly the Sample Review by Macro Editor; also suitable for reading summary/notes
Style the “References/Bibliography” Section
Add
# References/Bibliography
at the end of your Markdown fileIn my case, I use hanging indent, which is also used by APA style. 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. Feel free to change the code to meet your styling needs.
Print and Share
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.
To PDF: Marked 2 supports direct export to PDF format; alternatively, export to HTML format and print the HTML from your browser app.
To DOCX: export to HTML format and open and save to DOCX format in Microsoft Word or other word processors.
- Marked 2 app seems to have issues with exporting files into Word documents. The formats defined by CSL files can be lost.
- 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.
Issues and Limitations 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.
DocDown: Alternatives to Marked 2
- Download via GitHub
- “takes Markdown files, filters them through a Zotero bibliography file, a CSL file, and a reference .docx file, and exports a Word document with embedded citations and styles.”
- About DocDown
- Set your own workflow from markdown to docx