Building an Org-mode Workflow: Lists and Checklists

by Jeff Bradberry

I've reached a point where I need to organize things at a level lower than individual tasks. So for that, I've started making use of the lists and checklists features of Org mode.

Usage

As mentioned in the part about notes in Part 1, I've been using unordered lists from the beginning. There are other options for bullets to use with these, but so far I've only been using -.

While it is easy enough to just manually type these out (and I still do some of the time), the thing I have started to do recently is to make use of the keybindings to insert them instead. M-RET will add a new list item if your cursor is already in a list. A typical thing I might then combine with that is M-RIGHT to increase the indent of the new item, to turn it into the start of a sub-list. The only awkwardness then is starting the list, since M-RET will just create a new headline if you aren't already in a list. Technically you could turn that headline into a list item with C-c -, but I always just manually type the dash.

Many of my notes turn into these lists.

** add-ons and supplementary
- org-ref
  - org-cite / org-ref-cite
- Zotero
- org-roam
  - org-roam-bibtex
  - org-roam-ui
- org-babel (computational notebook)
- org-tree-slide (slideshow)
- org-present (slideshow)
- Beamer (export to pdf)
- ox-extra (ignore specified headlines during export)

The actual new thing that I've started to do, though, is to make use of checkbox items in my lists. These are represented by a prefix of - [ ] for your list items, and can be automatically added using M-S-RET. Though again like with ordinary list items, this will only work if your cursor is already in a list. Otherwise, you will wind up with a TODO headline.

For further tracking, you can add a progress "cookie" to your checklists. To start these out, type out a [/] or a [%] at the end of the parent of your checklist. These will then fill out with the completed fraction or percentage as you check off the checkboxes. As far as I'm aware there is no keybinding or function that will drop this cookie into place, but it is easy enough to just manually type it out.

*** TODO PR for model change [7/10]
- [X] Instance.node_state field with choices
- [X] InstanceLink.link_state field with choices
- [X] Django migration, with data migration
- [ ] update the provision_instance command to set the node_state to
  Installed
  - Originally this was going to be 'update the provision_instance and
    register_peers commands to optionally take the states', but I
    currently think this is unnecessary, these commands should only be
    used to register established nodes and links
- [X] add the peers/links to the appropriate Instance serializer
- [X] add the states to the serializers
- [X] represent enabled/disabled in the serializers
  - I decided to keep the orthogonal .enabled field
- [X] figure out how to represent de/provisioning failures
- [ ] update the heartbeat and healthcheck tasks to do proper
  state transitions
- [ ] make sure that job tasks only use ready nodes
- provide via the API a link to the de/provisioning job
  - this is punted to the issue about creating the job

As shown above, ordinary list items can be mixed freely with checkbox list items.

In theory checkboxes can be completed by typing in a capital X in the box, but that will fail to update the cookie (if you have one in place). Instead, you can use the keybinding C-c C-c which will both check off the item and update the cookie. If it happens that you have made some edits that have left the cookie out of date, you can instead place your cursor and do C-c C-c there to update it.

Once created, list items and checklist items can be rearranged using M-UP and M-DOWN, just like headlines.

Settings

No settings were changed to accommodate these changes to my workflow.

The org-mode section in my .emacs file still looks like this:

(global-set-key (kbd "C-c l") #'org-store-link)
(global-set-key (kbd "C-c a") #'org-agenda)
(global-set-key (kbd "C-c c") #'org-capture)

(setq org-agenda-files   (list "~/org/")
      org-refile-targets '((org-agenda-files :maxlevel . 5))
      org-refile-use-outline-path 'file
      org-log-into-drawer t
      org-log-done 'time
      org-log-redeadline 'time
      org-log-reschedule 'time
)

Key Bindings Learned

Within lists and/or checklists:

  • M-UP / M-DOWN: these keybindings work for moving list item subtrees up and down within lists/checklists, as well as regular headline subtrees.
  • M-RIGHT / M-LEFT: promote or demote the current list item, but not its children.
  • M-S-RIGHT / M-S-LEFT: promote or demote the subtree of the current list item.
  • M-RET: add a new list item at the same level as the current one.
    • Note: doing this in the middle of the text of some existing item will break the line, putting the right side of the text into the new item entry.
    • Note: this binding does not seem to be subtree aware and will put the new item entry immediately under the current one, even if there are child items.
    • if you do this keybinding at the beginning of the existing line, it will put the new item above the current one, instead of below.
  • M-S-RET: add a new checkbox item at the same level as the current list item.
    • Note: this has all of the same downsides as M-RET above.
  • C-c C-c: toggle a checkbox. This does have the side effect of updating a progress cookie in the parent of the list.

On a line with a progress cookie:

  • C-c C-c: update the progress cookie.

Outside of lists:

  • M-UP / M-DOWN: move a headline subtree up or down.
  • M-RIGHT / M-LEFT: promote or demote the current headline item, but not its children.
  • M-S-RIGHT / M-S-LEFT: promote or demote the current subtree.
  • M-RET: creates a new headline at the current level. Has all of the same caveats as the within-list version.
  • M-S-RET: creates a new TODO headline at the current level. Also has the same caveats.

Completely unrelated, I've recently learned that clicking on a link isn't the only way to open it:

  • C-c C-o: open a link in your browser

Next Steps

We've started ramping up a cycle of feature development at work recently, and I'm finding that my original style of organizing tasks plus notes is a bit awkward to deal with the larger features I need to work on. Next time I'll attempt to address that.