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.
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➡️ defaults to today
jo today➡️ same as above
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 Mondayuseful 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.
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 firstname.lastname@example.org or message me on twitter.