Skip to content

Templates

Jump to bottom Edit New page
Brett Terpstra edited this page Mar 26, 2024 · 6 revisions

The templates section of the Configuration contains templates for various command outputs. Include placeholders by placing a % before the keyword. The available tokens are:

  • %title: the "what was I doing" entry line. See below for additional format options
  • %date: the date based on the template's date_format setting
  • %shortdate: a custom date format for "relative" dates (see below)
  • %note: Any note in the entry will be included here. A linebreak is included before, and each line is indented one tab.
  • %idnote: The notes with an extra leading tab (indented note)
  • %odnote: The notes with leading tab removed (outdented note)
  • %>_3: note: Custom note formatting, see below
  • %chompnote: Notes on one line, beginning and trailing whitespace removed.
  • %section: The section/project the entry is currently in
  • %hr: a horizontal rule (-) the width of the terminal
  • %hr_under: a horizontal rule (_) the width of the terminal
  • %n: inserts a newline
  • %t: inserts a tab
  • %[color]: color can be black, red, green, blue, yellow, magenta, cyan, or white
    • you can prefix bg to affect background colors (%bgyellow)
    • prefix bold and boldbg for strong colors (%boldgreen, %boldbgblue)
    • there are some random special combo colors. Use doing colors to see the list
  • %interval: when used with the -t switch on the show command, it will display the time between a timestamp or @start(date) tag and the @done(date) tag, if it exists. Otherwise, it will remain empty. Format can be specified with the key interval_format (text or human).
  • %duration: when used with the --duration switch on display commands, entries not marked @done will display an elapsed time since start. Responds to interval_format template setting.

Date formats are based on Ruby strftime formatting. You can try it out here.

Date Formatting

%date uses the template's date_format string, or the default date format set in the config.

The %shortdate placeholder inserts a relative date. If the entry date is from today, it only shows the time in 12 hour format (3:00pm). If it's within the last week, it shows the abbreviated day name and the time (Wed 12:00pm). If it's within the last year, it shows the month/day and time (10/12 3:30pm). If it's from a previous year, it shows month/day/year and time (10/01/2020 4:30pm). I know this formatting is very US-centric. If anyone complains I'll figure out how to localize it better.

You can include an integer inside a %date placeholder (also works with %shortdate) to indicate a width to pad to, e.g. %20date or %15shortdate. If the number is present, spaces are added to the left side of the date string (based on template) to bring the total characters to that width.

If the number is negative, padding will be added on the right side.

With an ISO date format, %20date produces 2020-07-19 13:30. %-20date produces 2020-07-19 13:30 .

Title Formatting

The %title placeholder accepts some formatting options. The first is a wrap width, specified as %60title, where 60 is the number of characters at which to wrap the title. This overrides the wrap_width setting if provided in the template. The title will be wrapped to new lines, but anything after the title in the template will stay on the first line. The wrap lines will automatically be indented to the character position of the % in %title.

If you specify a negative width, it becomes a minimum width. If the title is less than that width, it will be padded on the right. Titles longer than the minimum width will be left as is.

The second parameter is the indent, which is an indent character followed by a number. By default, wrapped lines are indented 2 spaces. You can control this by using a space or underscore, or a "t" for tab, followed by a number. The placeholder %60_4title would wrap lines at 60 characters, and indent the wrapped lines an additional 4 spaces. To remove indent, use %60_0.

You can use either or both parameters, but the width must come before the indent if both are used.

Note Formatting

When a note is included in a template, it will always be extracted and placed on a new line below the rest of the content. The only exception to this is %chompnote, which will compress the note to a single line and insert it directly.

Because notes are extracted to new lines, if you want to apply a color to a note, the note color needs to come at the end of the template string. If you do this, add %reset at the beginning of the template string to reset any changes before starting the next entry.

In addition to the static placeholders for inserting notes (%note, %idnote, %odnote, %chompnote), you can also provide custom formatting. A format string looks like %^> 8: note. Here's now it works:

There are three parts, all of them optional.

%(^>)( 8)(: )note
  1. The first part must start with ^ (caret, Shift-6) followed by 1 character. This is a marker character that will go at the beginning of the line, before any indent.
  2. The second part is a space character followed by a number. The space can be an actual space or an underscore to represent a space. If it's a "t", then tabs will be used. Any other non-alphanumeric character will be used as is. The number after it specifies how many of the character to insert. To indent by two tabs, you would use %t2note.
  3. The last part is one character followed by an optional space (or underscore). This is a line prefix that will be prepended to every line of the note, after the indent.

%^> 11: note displays notes as:

Mon 12:16pm | Adding flexible padding to note indent @doing
>           : This is a note
>           : with a couple of lines

You can use any combination of the parts:

%: note outputs:

Mon 12:16pm | Adding flexible padding to note indent @doing
: This is a note
: with a couple of lines

And %t2note is the same as %idnote, just the note indented by two tabs.

Here's how a formatted note can look. This line in a template:

template: "%blue%shortdate %boldgreen│ %boldwhite%title %cyan(%section) %yellow%interval%default%white%_12┃ note%default"

Renders the view as:

Here's an example with wrapping and indent applied to title as well.

template: %blue%shortdate %boldgreen│ %boldwhite%80_4title %cyan(%section) %yellow%interval%default%white%_14┃_note%default

Colors

Run doing colors to see available placeholders and the colors the represent.

You can use the following colors in view templates. Set a foreground color with a named color:

%black
%red
%green
%yellow
%blue
%magenta
%cyan
%white

You can also add a background color (%bg[color]) by placing one after the foreground color:

%white%bgblack
%black%bgred
...etc.

There are bold variants for both foreground and background colors

%boldblack
%boldred
... etc.

%boldbgblack
%boldbgred
... etc.

And a few special colors you'll just have to try out to see (or just run doing colors):

%softpurple
%hotpants
%knightrider
%flamingo
%yeller
%whiteboard

You can apply some additional formatting using modifiers. If you use one of these, it will be active until you use %reset.

%bold
%dark
%italic
%underline
%underscore
%blink
%rapid_blink
%negative
%concealed
%strikethrough

Any time you use one of the foreground colors it will reset the bold and background settings to their default automatically. You can force a reset to default terminal colors using %default.

RGB Values

You can also hardcode RGB values for any color by using %#XXX[XXX]. RGB values can be 3 or 6 characters. 3-character strings will be interpreted as XYZ -> XXYYZZ. Any 256 color value can be entered, e.g.:

%#10edc4

Examples

My normal template for the recent command looks like this:

recent:
  date_format: '%_I:%M%P'
  template: '%date > %title%odnote'
  wrap_width: 88

And it outputs:

$ doing recent 3
 4:30am > Made my `console` script smarter...
    Checks first argument to see if it's a file, if it is, that's the log

    Else, it checks the first argument for a ".log" suffix and does a search in the user
    application logs with `find` for it.

    Otherwise, system.log.

    I also made an awesome Cope wrapper for it...
12:00pm > Working on `doing` again.
12:45pm > I think this thing (doing) is ready to document and distribute
$

You can include line breaks and tabs using %n and %t.

For example, this block:

recent:
  date_format: '%_I:%M%P'
  template: "%n%hr%n%date%n > %title%odnote%n%hr_under"
  wrap_width: 100

will output my recent entries like this:

$ doing recent 3
-----------------------------------------------------------------------
 4:30am
 > Made my `console` script smarter...
    Checks first argument to see if it's a file, if it is, that's the log

    Else, it checks the first argument for a ".log" suffix and does a search in the user application
    logs with `find` for it.

    Otherwise, system.log.

    I also made an awesome Cope wrapper for it...
_______________________________________________________________________

-----------------------------------------------------------------------
12:00pm
 > Working on `doing` again.
_______________________________________________________________________

-----------------------------------------------------------------------
12:45pm
 > I think this thing (doing) is ready to document and distribute
_______________________________________________________________________

$

The recent template can include a count key to specify the number of entries shown when run without an argument. Default is 10.

BrettTerpstra.com

Documentation:

→ BrettTerpstra.com

Clone this wiki locally