7th February, 2021 (Updated: February 19, 2021)

Bullet Journal

This is still a work-in-progress and subject to change.

A simple ruby gem that makes it easier to manage a bullet journal inspired personal notes system via a series of markdown files using a terminal executable called jo. Source available on GitHub.

How to install

Assuming you’re environment has ruby installed, you should just be able to:

gem install bullet_journal --pre

I’m not using any fancy ruby features, so any semi-recent version of ruby should do. It’s currently working for me with whatever ships with macOS by default.

Core concept

Bullet journal’s are a way of keeping track of notes & todo’s, and translate nicely to simple markdown files. I like to have a single markdown file per day, which will generally have a list of “items” in it, and then maybe a number of sections underneath of longer notes/scratchpad area.

But because of the loose format, after all we’re just opening up markdown files, you can actually use them however you want.

How to use

To start editing a note type into your terminal:


This will open an editor (default: vim) with a markdown file using the default journal name (“JOURNAL”) and the current date e.g.


To open yesterday’s file:

jo yesterday

Date options

Changing the journal

You might want to keep a separate journal for personal & work. After the date modifiers, bullet_journal will use whatever you have entered as the journal name. Multiple words will be hyphenated. Here are some examples assuming the current date is 2nd Feb 2021:

Changing the file locations, or default editor

By default bullet_journal will assume you want to create the note in the current directory. This isn’t how I use it though, I keep all of my notes in ~/Documents/notes. As I’m on a Mac, this means they all sync with iCloud and I can access them on the go if I need to.

There is a config file created at ~/.config/bullet_journal/config.yml that lets you:

Example config.yml

  journal_name: "JOURNAL"
  journal_location: "~/Documents/notes"
  editor: "nvim"

  # on a Mac, "open" will ask Finder
  # to use whatever handles `.md`, but
  # for this to work we actually create
  # the file upfront if it doesn't exist  
  editor: "open" 
  # work doesn't specify a journal location, 
  # so will use the default location

  journal_location: "~/Documents/example-corporation/notes"
  # "none" is a special editor that will simply print out
  # the debug info, with the final line always being the
  # file that would have been opened 
  editor: "none"

Alternative uses – create your own!

I’m currently using bullet_journal to keep a food diary (until I finish building weighted down). Every day, or really at multiple points during the day, I can quickly log what I’ve eaten with jo food and bring up my food diary. Want to see what I ate yesterday? That’s just jo yesterday food

Getting in touch

I’d love to hear if you’re finding bullet_journal useful, or have some recommendations. You can email me bullet_journal@robgough.net or message me on twitter.