Custom Todos

Last updated:
2021-05-23 14:14

Purpose: This document details how to configure Firn to recognize different org todo types, similar to org-todo-keywords.

Overview

If you customize org-mode to use different "Todo types", you may wish Firn to also recognize these todos. When Firn parses your org mode content, if you customize your todo-keywords, it enables you to style your keywords.

(In future versions of Firn, we may also enable the collecting of all todo-types, which will enable access to a complete list of all todo-types across all files.)

Usage

In your config.edn file you can set your custom todo types like so:


{;...
 :todo-keywords     ["TODO" "START" "HOLD" "WAIT" "DONE"]
 ;...

Now, whenever Firn encounters a headline with one of these keywords, it will apply two css classes to it. For example, the headline below:

* TASK Finish application

Will have these two css classes applied to it:

firn-headline-keyword firn-headline-keyword__TASK

This way, all todo types can be generically styled with the firn-headline-keyword and each individual keywords can be styled with firn-headline-keyword__${keyword}.

Accessing all todos on your site.

Similar to logbooks and tags, Firn will collect all todo keywords (custom or default) when it processes your files. These are stored in a list called :site-todos and each list item looks (roughly) like so:

[{:from-headline "A todo thing."
  :headline-link "/file-metadata#a-todo-thing"
  :keyword "TODO"}
 ;....]

You can access the entire list of todos in your layouts. An simplified example layout that prints all your todos across your site could look like this:

(defn default
  [{:keys [site-todos] :as data}]
  [:html
   [:body
    (for [todo site-todos]
      [:div
       [:a {:href (todo :headline-link)}
        [:span {:style "color: lightcoral"} (todo :keyword) " "]
        [:span (todo :from-headline)]]])]])
Previous: Rss