Spacemacs and Org-mode

December 16, 2017

Coming from Vim, I could not find a firm footing when I first started using Emacs. I have my Vim configured for visual aesthetic with a pretty minimal configuration. You can see my Vim config posted on my Providence Wiki. This config utilizes Vundle to manage plugins and lightline.vim for statusline (ditched vim-airline recently).

I did not have time to dig deeper into Emacs. The goal was to learn how to use the venerable Org mode in Emacs. Although I could potentially use Org mode on Vim (plugins: either the vim-orgmode or VimOrganizer), their maintenance status and project longevity are questionable.

So, what would be the best option?

I went with the Spacemacs. It instantly turned my Emacs installation into a beautiful but still quite a monster to tame. On Xubuntu 17.10 Artful Advaark, first, you need to install Emacs and then clone the spacemacs git repository.

sudo apt install emacs
git clone https://github.com/syl20bnr/spacemacs ~/.emacs.d

Invoking the emacs (or emacs -nw for the CLI mode) will bring you the installation screen. I went with the Evil mode, which simply means it will use Vim’s modal keybinding instead of the Holy mode, which uses Emacs’ default (and boring) keybinding. Basically, the core is Emacs but now it feels a lot like Vim.

Note: Evil here stands for extensible vi layer for Emacs.

Spacemacs homescreen The ultimate goal to embrace Emacs is to use the Org mode.

At first, the experience felt a lot awkward. The problem stemmed from trying to figure my way around the supercharged Org mode while tutorials on the internet refer to the vanilla version. I spent quite a while reading this documentation. Here are the shortcuts that matter to me.

SPC f e d   => opens ~/.spacemacs
SPC t L     => enables line wrapping
SPC f f     => opens file
SPC t n     => shows line number
SPC a o o   => shows org mode
SPC b       => shows action for buffer
SPC b d     => kills current buffer
SPC m d     => set deadline for the current TODO
SPC m s     => set schedule for the current TODO
SPC TAB     => cycle between open buffers
SPC m RET   => insert headline (inherit from above)
C-c C-t     => toggle status for TODO
C-c [       => add this buffer to agenda list
C-c ]       => remove this file from agenda list
SPC m A     => archive a TODO item
SPC m R     => refile an archived item
SPC SPC     => M-x

---
SPC : <space>
RET : <return>
C   : <ctrl>
M   : <alt>, M stands for Meta

I did a tiny little one-line modification in the ~/.spacemacs configuration file too…

(global-visual-line-mode 1) ; wrap line by default

… which does as what the comment says, eliminating the need to hit SPC t L every time opening a file. There is also one more thing that I do every time I define a file for the Org mode. At the very top part of the file, I have this line:

#+TODO: TODO RUNNING BACK IDEA | DONE CANCELED

This line defines that in a particular file, there are 6 possible states for a TODO item: TODO, RUNNING, BACK, IDEA, DONE, and CANCELED. The reason why there is a separator between DONE and CANCELED is pretty interesting. By default, the last state defined (i.e. CANCELED here) will automatically be combined with a timestamp when set by using the C-c C-t.

But I want items marked with both DONE and CANCELED to have a timestamp. Thus, the separator defines that DONE and CANCELED items will be timestamped. Pretty cool, aite?

SpacemacsOrgMode-Agenda The “agenda view” on the Org mode is lit.

I am pretty happy with this setup. Up until now, I have been using the Inkscape with a kanban-like SVG template to track my productivity. Org mode in Emacs takes my productivity game a little bit further.


So I found two more tricks that could be the game-changer for my productivity in the Org mode: checkboxes and archiving. I took my time to understand how these two work and to my surprise I really love them.

So, the checkbox. Here’s my setup:

** RUNNING The Damned Lab Report [/] [%]
    - [ ] write abstract
    - [ ] write introduction
    - [ ] write methods and material
    - [X] annotate all the results (inkscape)
    - [ ] write result 
    - [ ] write discussion
    - [ ] collect all papers and citations

An empty checkbox is represented with the [ ] (note the space between the square brackets). As far as I understood, checkboxes only work with list (represented with the dash “-” sign) and will not work if the item is a headline (as denoted by the asterisk “*” sign). The parent headline has two elements, this one [/] and this one [%]. After the setup is complete, hit SPC SPC (which equals to M-x) and call the function org-update-checkbox-count. Lo and behold…

checkboxes

As for the archiving, the default Org mode setup is that when an item is marked to be archived, Org mode will create a new file with filename based on the current buffer, suffixed with _archive. For example, if my buffer is job.org, the archive file created by the Org mode will be job.org_archive.

I prefer another setup where all archived items are centralized (I have 3 *.org files, btw). Let’s call it the archive.org. For this to work, each and every active *.org file must have this new archive location directive. Simply prefix this line at the top of the *.org file.

#+ARCHIVE: archive.org::

So in my case since I also had to declare the +TODO states, my *.org file looks like this:

#+TODO: TODO RUNNING BACK IDEA | DONE CANCELED
#+ARCHIVE: archive.org::

To archive an item in the Evil normal mode, hit SPC m A and it should appear afterward in the archive.org file.

Update, 5th April 2018.

Open ~/.spacemacs

  (global-visual-line-mode 1) ; wrap line by default
  (setq org-refile-targets '((org-agenda-files . (:maxlevel . 2)))) ; set refile targets
  (setq org-agenda-start-on-weekday nil) ; org-agenda view starts today and +7

Function for these lines as commented above.