mako(5) | File Formats Manual | mako(5) |
NAME
mako - configuration file
DESCRIPTION
The config file is located at ~/.config/mako/config or at $XDG_CONFIG_HOME/mako/config. Option lines can be specified to configure mako like so:
Empty lines and lines that begin with # are ignored.
GLOBAL CONFIGURATION OPTIONS
max-history=n
Default: 5
sort=+/-time | +/-priority
Default: -time
BINDING OPTIONS
Bindings allow one to perform an action when an event is triggered.
Supported options:
on-button-left=action
Default: invoke-default-action
on-button-middle=action
Default: none
on-button-right=action
Default: dismiss
on-touch=action
Default: dismiss
on-notify=action
Default: none
Supported actions:
none
dismiss [--no-history]
dismiss-all
dismiss-group
invoke-action <action>
An xdg-activation token will be sent to the client, allowing the client to request focus from the compositor. The compositor must support the xdg_activation_v1 protocol and allow the focus request for the following example to work correctly:
[app-name="some-app-id" actionable] on-button-left=invoke-action mail-reply-sender
invoke-default-action
exec <command>
The command will be executed in a POSIX shell. The shell variable id will be set to the notification ID. For example, the following option will display an interactive action menu on middle click:
on-button-middle=exec makoctl menu -n "$id" dmenu -p 'Select action: '
The following option will play a sound when a new notification is opened:
on-notify=exec mpv /usr/share/sounds/freedesktop/stereo/message.oga
STYLE OPTIONS
font=font
Default: monospace 10
background-color=color
Default: #285577FF
text-color=color
Default: #FFFFFFFF
width=px
Default: 300
height=px
Default: 100
outer-margin=directional
Default: 0
margin=directional
Default: 10
padding=directional
Default: 5
border-size=px
Default: 2
border-color=color
Default: #4C7899FF
border-radius=px
Default: 0
progress-color=[over|source] color
Progress can be indicated in a notification by setting a hint, "value" to an integer between 0 and 100 inclusive.
Default: over #5588AAFF
icons=0|1
Default: 1
max-icon-size=px
Default: 64
icon-path=path[:path...]
The path should be the root of the icon theme, the categories and resolutions will be searched for the most appropriate match.
/usr/share/icons/hicolor and /usr/share/pixmaps are always searched.
Default: ""
icon-location=position
Default: left
markup=0|1
Default: 1
actions=0|1
Default: 1
history=0|1
Default: 1
format=format
Default: <b>%s</b>\n%b
Default when grouped: (%g) <b>%s</b>\n%b
text-alignment=left|center|right
Default: left
default-timeout=timeout
Default: 0
ignore-timeout=0|1
Default: 0
group-by=field[,field,...]
Default: none
max-visible=n
Default: 5
output=name
Requires the compositor to support the Wayland protocol xdg-output-unstable-v1 version 2.
Default: ""
layer=layer
Default: top
anchor=position
Default: top-right
CRITERIA
In addition to the set of options at the top of the file, the config file may contain zero or more sections, each containing any combination of the BINDING OPTIONS and STYLE OPTIONS. The sections, called criteria, are defined with an INI-like square bracket syntax. The brackets may contain any number of fields, like so:
When a notification is received, it will be compared to the fields defined in each criteria. If all of the fields match, the style options within will be applied to the notification. Fields not included in the criteria are not considered during the match. A notification may match any number of criteria. This matching occurs in the order the criteria are defined in the config file, meaning that if multiple criteria match a notification, the last occurrence of any given style option will "win".
The following fields are available in criteria:
- app-name (string)
- app-icon (string)
- summary (string): exact match on the summary of the notification. This field conflicts with summary~.
- summary~ (string): a POSIX extended regular expression match on the summary of the notification. This field conflicts with summary.
- body (string): an exact match on the body of the notification. This field conflicts with body~.
- body~ (string): a POSIX extended regular expression match on the body of the notification. This field conflicts with body.
- urgency (one of "low", "normal", "critical")
- category (string)
- desktop-entry (string)
- actionable (boolean)
- expiring (boolean)
- mode (string): only apply style options in this section if the provided mode is currently enabled. For more information about modes, see the MODES section.
The following fields are also available to match on a second pass based on where previous style options decided to place each notification:
- grouped (boolean): whether the notification is grouped with any others.
- group-index (int): the notification's index within its group, or -1 if it is not grouped.
- hidden (boolean): special field which defines the style for the placeholder shown when the number of notifications or groups exceeds max-visible.
- output (string): which output the notification was sorted onto. See the output style option for possible values.
- anchor (string): which position on the output the notification was assigned to. See the anchor style option for possible values.
There are only two passes performed on each notification, so the second-pass criteria are not allowed to reposition the notification.
If a field's value contains special characters, they may be escaped with a backslash, or quoted:
[app-name=Google\ Chrome]
Quotes within quotes may also be escaped, and a literal backslash may be specified as \\. No spaces are allowed around the equal sign. Escaping equal signs within values is unnecessary.
Additionally, boolean values may be specified using any of true/false, 0/1, or as bare words:
[actionable=false] [actionable=0] [!actionable]
There are three criteria always present at the front of the list:
- An empty criteria which matches all notifications and contains the defaults for all style options, overwritten with any configured in the global section.
- [grouped], which sets the default format for grouped notifications and sets them invisible.
- [group-index=0], which makes the first member of each group visible again.
These options can be overridden by simply defining the criteria yourself and overriding them.
There are some rules restricting what can be configured depending on what is being matched by a given criteria. Criteria matching grouped or group-index are not allowed to change the anchor, output, or group-by, as this would invalidate the grouping. Grouping is only performed once rather than recursively, to avoid the potential for infinite loops.
CRITERIA-ONLY STYLE OPTIONS
Some style options are not useful in the global context and therefore have no associated command-line option.
invisible=0|1
Default: 0
COLORS
Colors can be specified as #RRGGBB or #RRGGBBAA.
DIRECTIONAL VALUES
Some options set values that affect all four edges of a notification. These options can be specified in several different ways, depending on how much control over each edge is desired:
- A single value will apply to all four edges.
- Two values will set vertical and horizontal edges separately.
- Three will set top, horizontal, and bottom edges separately.
- Four will set top, right, bottom, and left edges separately.
When specifying multiple values, they should be comma-separated. For example, this would set the top margin to 10, left and right to 20, and bottom to five:
margin = 10,20,5
FORMAT SPECIFIERS
Format specification works similarly to printf(3), but with a different set of specifiers.
%% Literal "%"
\\ Literal "\"
\n New Line
For notifications
%a Application name
%s Notification summary
%b Notification body
%g Number of notifications in the current group
%i Notification id
For the hidden notifications placeholder
%h Number of hidden notifications
%t Total number of notifications
MODES
mako supports applying style options conditionally via modes. A configuration section with a mode criteria will only be applied if the current mode matches. makoctl(1) can be used to change the current mode.
The initial list of modes contains a single mode called "default". This is deprecated, in a future version the initial list of modes will be empty.
For example, to hide all notifications if the mode "do-not-disturb" is enabled:
[mode=do-not-disturb] invisible=1
makoctl mode -a do-not-disturb will hide all notifications, makoctl mode -r do-not-disturb will show them again.
AUTHORS
Maintained by Simon Ser <contact@emersion.fr>, who is assisted by other open-source contributors. For more information about mako development, see https://github.com/emersion/mako.
SEE ALSO
2024-05-12 |