September 16, 2019 6 min read

Setting up jrnl for Journaling

There’s no shortage of posts and news items that tout the benefits of keeping a journal. It seems like everyone loves to tell you about the positive effects it will have on your psyche, mental-health, sex life, and the happiness of your pets.

I’m not sure about all of those but I can see how keeping a journal can help in one very important way: it gets you writing. I am not a professional author (or even an amateur) but this seems like a Good Thing^TM in general.

“If you want to be a writer, you must do two things above all others: read a lot and write a lot. There’s no way around these two things that I’m aware of, no shortcut.” Stephen King, On Writing: A Memoir of the Craft

Writing down your thoughts seems like it helps to make so many abstract ideas more concrete. Being able to review the words and getting a bigger picture of the thought process should surely help to organize and arrange things in a way that makes sense (or in other surprising ways perhaps not considered at first).

I can always use help in the writing department, so I’ve decided to start keeping a journal as well. The problem is that I like to keep things as simple and computer-agnostic as possible. So I thought I’d document my approach and rationale to setting up a journaling system that can suit the way I computer.

Requirements

I tend to prefer solutions that are OS/computer-agnostic. I currently use Ubuntu at home on my Nextcloud server and my personal laptop (I still seriously love my old 2011(!) MacBook Air) while I’m forced into Windows on my work desktop and laptop. My phone is still an iPhone.

I’m all over the place in the OS world. So one of my very first requirements is that the system can work for me no matter which OS I happen to be on. This also means that I’d like the format to be as agnostic and portable as possible too. Databases are neat, but overkill for something as simple as a text journal, so I’d like to see the files stored as plain text files.

I had previously written about setting up Nextcloud to be my online data storage and syncing solution. So my second requirement would be the ability to sync using Nextcloud.

I spend much of my day with a secure shell into my home server. One of the first things I’ll install in Windows is Cygwin to give me access to all of the tools I am accustomed to using (POSIX). So it’s fair to say that I’d love an interface that I can use from within my bash terminal.

Even better if I can use Vim!

Focused and accessible. Any journaling approach for me should be as simple and accessible as possible and focus on just journaling. Anything that gets in the way will only distract me from my purpose here, which is to capture my thoughts and notes every day. This is particularly true of web-based applications where it’s really easy for me to jump down another rabbit hole of distraction. Too many options and buttons and menus to play in and I’m liable to lose myself just fiddling around.

It should go without saying but it should also be Free Software.

In summary, I’d love if a solution:

is OS-agnostic
uses plain text files
uses Nextcloud for syncing
is accessible through terminal/bash
can use Vim
is focused, simple, and accessible

Free/Open Source Options

I came across a few different options for F/OSS journaling. This opensource.com article listed three neat looking Linux options: RedNotebook, Lifeograph, and Almanah Diary.

They all look neat and fancy but they don’t quite meet my requirements.

One option that I have played with a little previously is Joplin. It’s an incredibly robust note taking application that is packed with features (including a terminal interface). I may revisit it later but the complexity almost makes it too much for simple journaling.

Enter `jrnl`

I may have found what I’m looking for with jrnl. It’s a Python based utility so installation is pretty easy with pip install jrnl.

It stores the journal as a single text file (you can also have multiple journals for difference purposes if you want). I can just drop the file in my Nextcloud directory for syncing. As a plain text file I can also modify it directly from within the Nextcloud app as well (for iOS).

I can access the journal with a little more functionality from the terminal jrnl and creating a new entry or editing older entries are done through Vim (you can set jrnl to use any external editor you want).

It follows the Unix philosophy of “do one thing and do it well”.

The journal file itself looks quite simple and straightforward:

2019-09-02 09:00 Hot Sunday
Day was hot so the house was really hot when we got home (AC turned up while we were out).

2019-09-14 09:00 Doors
Installed the new door at the @bayhouse.
Had dinner with the Jones!

Worked on @LGW website a little.
Mostly formatting and some taxonomy stuff.

2019-09-15 23:30 It was a lazy Sunday
Swung in hammocks and read "The Shining" more.
Picked up dinner at Publix.

The docs do a better job explaining the options (there’s only a few).

Creating a new entry is as easy as:

$ jrnl This is a new entry
$ jrnl yesterday: This was a good day
$ jrnl

It has smart date parsing so you can pass it things like “yesterday” or “last monday”. The last version with just jrnl will open Vim and let me just start writing into a temporary file. When I save and quit it will write it into the journal.txt file in the appropriate location for me.

There’s plenty of options for listing/searching/displaying the journal including date and keyword filters. There’s also options for exporting the journal as json, Markdown, or text.

Vim `jrnl` Syntax Highlight

One small thing that I wanted was Vim syntax highlighting in my journal.txt file. The journal file format is pretty simple. There’s a date on a new line that is followed by a title for that entry. This is followed by further text for the entry until you find another new date. The only other unique token in the file is the use of “@” tags (@LGW, @movie, etc…).

I created a simple syntax highlighting file for Vim:

if exists("b:current_syntax")
    finish
endif

syntax match jtag "@.\{-}\w\+"
syntax match jyear /\d\{4}-\d\d-\d\d \d\d:\d\d/

syntax region entryLine start=/\d\{4}-\d\d-\d\d \d\d:\d\d/ end=/$/ contains=jyear

highlight def link jtag Constant
highlight def link jyear Identifier
highlight def entryLine ctermfg=250 guifg=Gray

let b:current_syntax = "jrnl"

You can simply drop the above into a syntax file (usually located somewhere like ~/.vim/syntax/jrnl.vim).

Modeline Tip

I have modeline set on my Vim, so it will automatically try to read a modeline within the first/last 5 lines of the file. The problem is the file journal.txt gets modified every time a new entry is added. To fix this I created an entry for long ago that has my modeline in it.
As long as I don’t create an entry older than my birth Vim should still pick up the modeline:

1974-02-01 09:00 Setting vim options
# vim: ft=jrnl

The Hard Part

Honestly, the hardest part of this is building the habit and discipline to consistently write/journal every day if possible. At least now I have a very low-friction way to do this on any of my computers.