Option for the headings’ overall style

Brief: Heading styles with optional list of values per heading level.

Symbol: modus-themes-headings (‘alist’ type, multiple properties)

This is an alist that accepts a ‘(KEY . LIST-OF-VALUES)’ combination. The ‘KEY’ is either a number, representing the heading’s level (0 through 8) or t, which pertains to the fallback style. The named keys ‘agenda-date’ and ‘agenda-structure’ apply to the Org agenda.

Level 0 is a special heading: it is used for what counts as a document title or equivalent, such as the ‘#+title’ construct we find in Org files. Levels 1-8 are regular headings.

The ‘LIST-OF-VALUES’ covers symbols that refer to properties, as described below. Here is a complete sample with various stylistic combinations, followed by a presentation of all available properties:

(setq modus-themes-headings
      '((1 . (variable-pitch 1.5))
        (2 . (1.3))
        (agenda-date . (1.3))
        (agenda-structure . (variable-pitch light 1.8))
        (t . (1.1))))

Properties:

• A font weight, which must be supported by the underlying typeface:

  • thin
  • ultralight
  • extralight
  • light
  • semilight
  • regular
  • medium
  • semibold
  • bold (default)
  • heavy
  • extrabold
  • ultrabold

• A floating point as a height multiple of the default or a cons cell in the form of ‘(height . FLOAT)’.

By default (a nil value for this variable), all headings have a bold typographic weight and use a desaturated text color.

A variable-pitch property changes the font family of the heading to that of the variable-pitch face (normally a proportionately spaced typeface).

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.

A number, expressed as a floating point (e.g. 1.5), adjusts the height of the heading to that many times the base font size. The default height is the same as 1.0, though it need not be explicitly stated. 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.

Combinations of any of those properties are expressed as a list, like in these examples:

(semibold)
(variable-pitch semibold 1.3)
(variable-pitch semibold (height 1.3)) ; same as above
(variable-pitch semibold (height . 1.3)) ; same as above

The order in which the properties are set is not significant.

In user configuration files the form may look like this:

(setq modus-themes-headings
      '((1 . (variable-pitch 1.5))
        (2 . (1.3))
        (agenda-date . (1.3))
        (agenda-structure . (variable-pitch light 1.8))
        (t . (1.1))))

When defining the styles per heading level, it is possible to pass a non-nil value (t) instead of a list of properties. This will retain the original aesthetic for that level. For example:

(setq modus-themes-headings
      '((1 . t)           ; keep the default style
        (2 . (semibold 1.2))
        (t . (rainbow)))) ; style for all other headings

(setq modus-themes-headings
      '((1 . (variable-pitch 1.5))
        (2 . (semibold))
        (t . t))) ; default style for all other levels

Note that the text color of headings, of their background, and overline can all be set via the overrides. It is possible to have any color combination for any heading level (something that could not be done in older versions of the themes).

Option for palette overrides.

Make headings more or less colorful.