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:

jo

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

JOURNAL_2021_02_06_Saturday.md

To open yesterday’s file:

jo yesterday

Date options

• jo ➡️ defaults to today
• jo today ➡️ same as above
• jo yesterday
• jo tomorrow
• jo last tuesday ➡️ the previous Tuesday, works for all weekdays
• jo next thursday ➡️ the next thursday, works for all weekdays
• jo next week ➡️ same as next Monday useful towards the end of the week for logging things that you need to be aware of at the beginning of the week
• jo last week ➡️ same as last Friday. Useful when you made a quick getaway on the Friday, and can’t remember if you’ve got lingering tasks
• jo someday ➡️ a special case, creates JOURNAL_Someday.md – Useful for recording future tasks that don’t have a specific date yet

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:

• jo work ➡️ WORK_2021_02_06_Saturday.md
• jo yesterday work ➡️ WORK_2021_02_05_Friday.md
• jo next thursday work project ➡️ WORK-PROJECT_2021_02_11_Thursday.md

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:

• change the default journal name used when you don’t specify it explicitly. If you’re only using it for work, you might choose your employers name, or you might want it to default to ‘PERSONAL’
• change the journal location, on a per-journal basis. Perhaps you want to store your work notes separately from your personal notes?
• change the editor, also on a per-journal basis.

Example config.yml

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

work:
  # 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

example-corporation:
  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.