Making notes accessible from the command line

I stumbled upon a cool repository for cheatsheets aptly named “cheat”. It enables the user to store cheatsheets in a series of directories and then access them through cheat {cheatsheet_name}. While there are a ton of community created cheatsheets, I wanted to see if I could get the tool to work with my online notes, which are written in markdown and organized through mkdocs. I was able to get some elements to work quite well, although some functionality will take more work to development.

Basic setup

The first thing is to install cheatsheet itself. I chose to install it by unpacking the release and putting it in the bin directory since it is not packaged in apt, but if you are on macOS or arch, there is a package for you.

cd /tmp \
  && wget https://github.com/cheat/cheat/releases/download/4.4.2/cheat-linux-amd64.gz \
  && gunzip cheat-linux-amd64.gz \
  && chmod +x cheat-linux-amd64 \
  && sudo mv cheat-linux-amd64 /usr/local/bin/cheat

Now that cheat is installed and on the path, we need to write a config for it. By default, cheat assumes the config is on an XDG-compliant configuration path (such as ~/.config/cheat/conf.yml), however you can customize this through an CHEAT_CONFIG_PATH environment variable in your shell.

My configuration file looks like this, and I’ll walk through what each of the different lines is doing.

cheatpaths:
  - name: personal
    path: ~/code/notes/docs/
    readonly: false
editor: nvim
colorize: true
style: catppuccin_mocha
pager: less -FRX

The cheatpaths: object defines which directories cheat should look in for the cheatsheets, and whether they can be edited or not. My solution isn’t perfect, because docs/ also contains favicon information and a stylesheet in mkdocs, but it’s as close as I could get. Multiple cheatpaths can be defined if you have different sets of documents that you want to search through, and naming is supported. The example in the repository README shows this well.

cheatpaths:
  - name: community
    path: ~/documents/cheat/community
    tags: [ community ]
    readonly: true

  - name: personal
    path: ~/documents/cheat/personal
    tags: [ personal ]
    readonly: false

The editor: object defines which editor should be used to open files that can be edited. I picked neovim, however you could easily pick something like nano if you prefer.

Applying the Catppuccin theme was straightforward, just add colorize: true and style: catppuccin_mocha.

The last key, pager, defines how you would like to scroll through cheatsheets that take up more vertical space than your terminal can present in one go. Using less -FRX is recommended for linux, more is recommend for Windows.

How does it work in practice?

If I want to quickly see my note for debian I can use the following command.

cheat debian.md

This will pull up the note and allow me to scroll through it with jk and quit through q. The output is nicely colorized to match my terminal setup. If I want to edit the note, I can use the -e flag to open it up in neovim and make said edits. I can search through my notes for a word with -s instead of using a filename.

I mentioned in the intro that there were some clunky parts. Having to type .md at the end of the file is annoying, and I haven’t touched any of the tagging functionality because I don’t know how it would interact with mkdocs. I am thinking of trying to adjust my mkdocs setup such that files are all plaintext.

Wait… isn’t this all possible through tools like fzf?

Glad you asked, absolutely. I experimented with setting up something like the below, which allows me to search the notes (ns for “note search”) and display the contents nicely in the terminal without having to switch out of the current window.

alias ns='find ~/code/notes/docs -type f -name "*.md" \ 
| fzf --preview="batcat --wrap=auto --color=always {}" \
--preview-window="up:70%" --bind=pgup:preview-page-up,pgdn:preview-page-down,up:preview-up,down:preview-down \
| xargs -I {} nvim {}'

There are pros and cons to this solution over the cheat solution

Pros

1. Highlighting by bat is much better than the syntax highlighting in cheat.
2. No need to type in .md when searching.
3. Can ignore the favicons and stylesheet

Cons

1. Scrolling is done with arrow-up and arrow-down instead of j and k
2. Setup is more intensive.

I still have some tinkering to do to figure out the nuts and bolts of how exactly I want to do this, but I am very excited by the idea. Having the notes accessible from the terminal helps when I am at my desk, while having them online helps when I am on the go and want to pull something up on my phone. I am also going to look through the community created cheatsheets and see which ones I would like to save, which should expand the current selection of notes a bit. They are all CC0 licensed, but I still want to see about a way to tag them as external and attribute the original source.

I’ll finish off with the awesome xkcd comic that is relevant to this whole process (and which I was reminded of via the cheat README). The end goal is just to remember how to do simple things in high-stakes scenarios from the terminal!