4.25 Option for the headings’ overall style

Brief: Heading styles with optional list of values for levels 0-8.

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-8) or t, which pertains to the fallback style.

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, followed by a presentation of all available properties:

(setq modus-themes-headings
      '((1 . (background overline variable-pitch 1.5))
        (2 . (overline rainbow 1.3))
        (3 . (overline 1.1))
        (t . (monochrome))))

Properties:

• rainbow
• overline
• background
• monochrome
• A font weight, which must be supported by the underlying typeface:
  • thin
  • ultralight
  • extralight
  • light
  • semilight
  • regular
  • medium
  • semibold
  • bold
  • heavy
  • extrabold
  • ultrabold
• no-bold (deprecated alias of a regular weight)
• 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 rainbow property makes the text color more saturated.

An overline property draws a line above the area of the heading.

A background property adds a subtle tinted color to the background of the heading.

A monochrome property makes the heading the same as the base color, which is that of the default face’s foreground. When background is also set, monochrome changes its color to gray. If both monochrome and rainbow are set, the former takes precedence.

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. For backward compatibility, the no-bold value is accepted, though users are encouraged to specify a regular weight instead.

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)
(rainbow background)
(overline monochrome semibold 1.3)
(overline monochrome semibold (height 1.3)) ; same as above
(overline monochrome 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 . (background overline rainbow 1.5))
        (2 . (background overline 1.3))
        (t . (overline semibold))))

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 . (background overline))
        (t . (rainbow)))) ; style for all other headings

(setq modus-themes-headings
      '((1 . (background overline))
        (2 . (rainbow semibold))
        (t . t))) ; default style for all other levels

For Org users, the extent of the heading depends on the variable org-fontify-whole-heading-line. This affects the overline and background properties. Depending on the version of Org, there may be others, such as org-fontify-done-headline.