4.24 Option for Org agenda constructs

Brief: Control the style of the Org agenda. Multiple parameters are available, each with its own options.

Symbol: modus-themes-org-agenda (‘alist’ type, multiple styles)

This is an alist that accepts a ‘(key . value)’ combination. Some values are specified as a list. Here is a sample, followed by a description of all possible combinations:

(setq modus-themes-org-agenda
      '((header-block . (variable-pitch 1.5))
        (header-date . (grayscale workaholic bold-today 1.2))
        (event . (accented italic varied))
        (scheduled . uniform)
        (habit . traffic-light)))

A header-block key applies to elements that concern the headings which demarcate blocks in the structure of the agenda. By default (a nil value) those are rendered in a bold typographic weight, plus a height that is slightly taller than the default font size. Acceptable values come in the form of a list that can include either or both of those properties:

• variable-pitch to use a proportionately spaced typeface;
• A number as a floating point (e.g. 1.5) to set the height of the text to that many times the default font height. A float of 1.0 or the symbol no-scale have the same effect of making the font the same height as the rest of the buffer. When neither a number nor ‘no-scale’ are present, the default is a small increase in height (a value of 1.15).

  Instead of a floating point, an acceptable value can be in the form of a cons cell like ‘(height . FLOAT)’ or ‘(height FLOAT)’, where FLOAT is the given number.

• The symbol of a weight attribute adjusts the font of the heading accordingly, such as light, semibold, etc. Valid symbols are defined in the variable modus-themes-weights. The absence of a weight means that bold will be used by virtue of inheriting the bold face.

Configure bold and italic faces.

In case both a number and no-scale are in the list, the latter takes precedence. If two numbers are specified, the first one is applied.

Example usage:

(header-block . nil)
(header-block . (1.5))
(header-block . (no-scale))
(header-block . (variable-pitch 1.5))
(header-block . (variable-pitch 1.5 semibold))

A header-date key covers date headings. Dates use only a foreground color by default (a nil value), with weekdays and weekends having a slight difference in hueness. The current date has an added gray background. This key accepts a list of values that can include any of the following properties:

• grayscale to make weekdays use the main foreground color and weekends a more subtle gray;
• workaholic to make weekdays and weekends look the same in terms of color;
• bold-today to apply a bold typographic weight to the current date;
• bold-all to render all date headings in a bold weight;
• underline-today applies an underline to the current date while removing the background it has by default;
• A number as a floating point (e.g. 1.2) to set the height of the text to that many times the default font height. The default is the same as the base font height (the equivalent of 1.0). Instead of a floating point, an acceptable value can be in the form of a cons cell like ‘(height . FLOAT)’ or ‘(height FLOAT)’, where FLOAT is the given number.

For example:

(header-date . nil)
(header-date . (workaholic))
(header-date . (grayscale bold-all))
(header-date . (grayscale workaholic))
(header-date . (grayscale workaholic bold-today))
(header-date . (grayscale workaholic bold-today scale-heading))

An event key covers (i) headings with a plain time stamp that are shown on the agenda, also known as events, (ii) entries imported from the diary, and (iii) other items that derive from a symbolic expression or sexp (phases of the moon, holidays, etc.). By default all those look the same and have a subtle foreground color (the default is a nil value or an empty list). This key accepts a list of properties. Those are:

• accented applies an accent value to the event’s foreground, replacing the original gray. It makes all entries stand out more.
• italic adds a slant to the font’s forms (italic or oblique forms, depending on the typeface).
• varied differentiates between events with a plain time stamp and entries that are generated from either the diary or a symbolic expression. It generally puts more emphasis on events. When varied is combined with accented, it makes only events use an accent color, while diary/sexp entries retain their original subtle foreground. When varied is used in tandem with italic, it applies a slant only to diary and sexp entries, not events. And when varied is the sole property passed to the event key, it has the same meaning as the list (italic varied). The combination of varied, accented, italic covers all of the aforementioned cases.

For example:

(event . nil)
(event . (italic))
(event . (accented italic))
(event . (accented italic varied))

A scheduled key applies to tasks with a scheduled date. By default (a nil value), those use varying shades of yellow to denote (i) a past or current date and (ii) a future date. Valid values are symbols:

• nil (default);
• uniform to make all scheduled dates the same color;
• rainbow to use contrasting colors for past, present, future scheduled dates.

For example:

(scheduled . nil)
(scheduled . uniform)
(scheduled . rainbow)

A habit key applies to the org-habit graph. All possible value are passed as a symbol. Those are:

• The default (nil) is meant to conform with the original aesthetic of org-habit. It employs all four color codes that correspond to the org-habit states—clear, ready, alert, and overdue—while distinguishing between their present and future variants. This results in a total of eight colors in use: red, yellow, green, blue, in tinted and shaded versions. They cover the full set of information provided by the org-habit consistency graph.
• simplified is like the default except that it removes the dichotomy between current and future variants by applying uniform color-coded values. It applies a total of four colors: red, yellow, green, blue. They produce a simplified consistency graph that is more legible (or less busy) than the default. The intent is to shift focus towards the distinction between the four states of a habit task, rather than each state’s present/future outlook.
• traffic-light further reduces the available colors to red, yellow, and green. As in simplified, present and future variants appear uniformly, but differently from it, the clear state is rendered in a green hue, instead of the original blue. This is meant to capture the use-case where a habit task being too early is less important than it being too late. The difference between ready and clear states is attenuated by painting both of them using shades of green. This option thus highlights the alert and overdue states.
• When modus-themes-deuteranopia is non-nil the exact style of the habit graph adapts to the needs of users with red-green color deficiency by substituting every instance of green with blue or cyan (depending on the specifics).

Option for red-green color deficiency or deuteranopia.

For example:

(habit . nil)
(habit . simplified)
(habit . traffic-light)

Putting it all together, the alist can look like this:

'((header-block . (1.5 variable-pitch))
  (header-date . (grayscale workaholic bold-today))
  (event . (accented varied))
  (scheduled . uniform)
  (habit . traffic-light))

;; Or else:
(setq modus-themes-org-agenda
      '((header-block . (1.5 variable-pitch))
        (header-date . (grayscale workaholic bold-today))
        (event . (accented varied))
        (scheduled . uniform)
        (habit . traffic-light)))