My Org-Mode Workflow

I have been a massive fan of Emacs ever since my PhD supervisor introduced it to me, and how he used it to manage almost the entirety of his daily workflow. I’ve also gone fully down the rabbit hole and use Emacs for development, content writing (using excellent packages like AucTex), and managing my emails.

Recently I’ve pulled away from using Emacs for managing my emails (poor HTML support is a bit of a showstopper here in 2020..) but it’s still my go to tool for project management, documentation creation, and mundane tasks such as documenting meetings, my to do list, and various ideas for new projects. This is all using what I think to be Emacs’ greatest major mode: Org-Mode.

Org-Mode is a plain text based hierarchical markup system, with a significant number of powerful features that allow it to be used flexibly for tasks such as writing up PDF’s, generating simple web pages (both using Org-Export) and managing a diary. It is an excellent platform for writing technical documents and even writing books, with its ability to easily export to PDF. However, there are some limitations which I will cover, which mean that for very advanced writing tasks (such as writing my PhD thesis) I tend to use LaTeX directly as it offers more control over the output document.

Org-Mode is for all intents and purposes a completely seperate, and extremely feature heavy, general purpose writing system supporting many languages. It is furthermore, very extensible through the Emacs Lisp dialect, which does not require significant knowledge of the language to begin to mould Emacs to your workflow.

I won’t cover the basics of the Org-Mode syntax as it is much better explained in the excellent Org-Mode documentation: The Org Manual

I’d like to demonstrate instead how I use it as a day to day system to gather notes for/from meetings, and as a general to-do list. I’ll also detail how I use it for writing and creation. 

Org- Capture

One of the greatest features of Org-Mode past its use in editing plain .org files is its ability to manage either a single, or a collection of, org files arranged in a way fitting the user’s needs.

The configuration to set this up is relatively straightforwards. You will need to setup a lisp of org-capture templates such as my own:

(setq org-capture-templates
       '(("t" "TODO" entry (file org-default-notes-file)
	  "* TODO %?\n%u\n%a\n" :clock-in t :clock-resume t)
	 ("m" "Meeting" entry (file+datetree "~/git-working/WriteUps/org/diary.org")
	  "* MEETING with %? :MEETING:\n%t" :clock-in t :clock-resume t)
	 ("d" "Diary" entry (file+datetree "~/git-working/Writeups/org/diary.org")
	  "* %?\n%u\n%a\n" :clock-in t :clock-resume t)
	 ("p" "Paper" entry (file "~/git-working/Writeups/org/papers.org")
	  "* %?\n:PAPER: %U\n** Overview: \n\n** Abbreviations: \n\n** Useful Additional References: \n\n")
	 
	 ("i" "Idea" entry (file org-default-notes-file)
	  "* %? :IDEA: \n%t" :clock-in t :clock-resume t)
	 ("n" "Note" entry (file org-default-notes-file)
	  "")
	 ("r" "TREE" entry (file org-default-notes-file)
	  "* %? \n\n")))

(setq org-tag-persistent-alist
      '(("MEETING" . ?m)
	("IDEA" . ?i)
	("DIARY" . ?d)
	("NEXT" . ?n)
	("PROJECT" . ?p)
	("PROJECT(PERSONAL)" . ?o)
	("BOOK" . ?b) ;; Use this for marking books in papers.org.
	("ADVANCED" .?a)
	("TEACHING" . ?t)
	("WRITEUP" . ?w)))

You will notice that in the Diary template I have setup to have it setup a date tree for the capture when it is saved to my allotted org file. I have a Meeting template that goes into the same “diary.org” file. I have also setup all of them to keep track of the time I clock into and out of each task (the time between generating the capture, and saving it to disk). The TODO entry allows me to save a capture to my default notes file (in this case named “capture.org”) and it is flagged up using Org-Agenda so I can track tasks and when they need to be completed by.

Org-Mode also offers powerful time-tracking for tasks but I don’t currently use this.

Org Export

Org-Mode is a pretty much complete writing framework, and allows the ability to write an org file and use org-export, C-c e, to convert the .org file to either Latex, HTML, Plain Text, ODT, or even a PDF (via LaTeX). You will need to have a LaTeX framework installed on your local machine, such as texlive. The org-export window is very straightforward and I’ve never had any trouble with it.

A drawback I discussed earlier is the difficulty for large content creation tasks such as writing a book or thesis. In my case when writing my PhD thesis I had to use a standard thesis which satisfied the departmental guidelines, so I used a template written in LaTeX, but I had written several precusor Chapter’s in Org Mode which I incorporated into the final thesis by using org-export to export these .org files to a LaTeX file.

This drawback however is not significant for those interested in using org-mode for such a purpose, and can be used a full Publishing system as specified in The Org Manual: Publishing . This feature can even manage automatic uploading of published document as a PDF/HTML (or both) to a web server for hosting!

Org-Ref

A writeup on an org mode workflow for technical writing would not be complete without a bibliography management solution. I tend towards, for reasons of simplicity, having a monolithic reference file which contains my entire library of BibTex references. Some people prefer to have seperate BibTex files for writing papers, but I’ll describe how I use simple Org-Ref defaults to manage citations for both Org-Mode and Latex documents. Firstly the syntax:

;; My bibliography for references. 


(setq org-ref-default-bibliography "~/git-working/WriteUps/references_all.bib")
(setq reftex-default-bibliography '("~/git-working/WriteUps/references_all.bib"))
(setq reftex-plug-into-AUCTeX t)
;; see org-ref for use of these variables
(setq org-ref-bibliography-notes "~/git-working/WriteUps/org/notes.org"
      org-ref-default-bibliography '("~/git-working/WriteUps/references_all.bib")
      org-ref-pdf-directory "~/Google_Drive/PhD/Academic/Reading")

(global-set-key (kbd "C-c o") 'org-ref-helm-insert-cite-link)

Here I setup the default BibTex file that Org-Ref refers to as well as point it to my default notes file (so I can file notes on individual PDF’s) as well as the directory where I store PDF’s. Finally I set the global reference key for the org-ref-helm framework, which gives Helm support for Org-Ref. There is also a completion framework available for Ivy, or just plain Emacs.

Org Config

My complete Org-Mode config can be found in this Gist.