1mako(5)                       File Formats Manual                      mako(5)
2
3
4

NAME

6       mako - configuration file
7

DESCRIPTION

9       The config file is located at ~/.config/mako/config or at $XDG_CON‐
10       FIG_HOME/mako/config. Option lines can be specified to configure mako
11       like so:
12
13           key=value
14
15       Empty lines and lines that begin with # are ignored.
16

GLOBAL CONFIGURATION OPTIONS

18       max-history=n
19           Set maximum number of expired notifications to keep in the history
20           buffer to n. If the buffer is full, newly expired notifications re‐
21           place the oldest ones. If 0, history is disabled.
22
23           Default: 5
24
25       sort=+/-time | +/-priority
26           Sorts incoming notifications by time and/or priority in ascend‐
27           ing(+) or descending(-) order.
28
29           Default: -time
30

BINDING OPTIONS

32       Bindings allow to perform an action when an event is triggered. Sup‐
33       ported values are none, dismiss, dismiss-all, dismiss-group, invoke-de‐
34       fault-action and exec <command>.
35
36       on-button-left=action
37           Default: invoke-default-action
38
39       on-button-middle=action
40           Default: none
41
42       on-button-right=action
43           Default: dismiss
44
45       on-touch=action
46           Default: dismiss
47
48       on-notify = action
49           Default: none
50
51       When exec is used, the command will be executed in a POSIX shell. The
52       shell variable id will be set to the notification ID. For example, the
53       following option will display an interactive action menu on middle
54       click:
55
56           on-button-middle=exec makoctl menu -n "$id" dmenu -p 'Select action: '
57
58       The following option will play a sound when a new notification is
59       opened:
60
61           on-notify=exec mpv /usr/share/sounds/freedesktop/stereo/message.oga
62

STYLE OPTIONS

64       font=font
65           Set font to font, in Pango format.
66
67           Default: monospace 10
68
69       background-color=color
70           Set background color to color. See COLORS for more information.
71
72           Default: #285577FF
73
74       text-color=color
75           Set text color to color. See COLORS for more information.
76
77           Default: #FFFFFFFF
78
79       width=px
80           Set width of notification popups.
81
82           Default: 300
83
84       height=px
85           Set maximum height of notification popups. Notifications whose text
86           takes up less space are shrunk to fit.
87
88           Default: 100
89
90       margin=directional
91           Set margin of each edge to the size specified by directional. See
92           DIRECTIONAL VALUES for more information.
93
94           Default: 10
95
96       padding=directional
97           Set padding on each side to the size specified by directional. See
98           DIRECTIONAL VALUES for more information.
99
100           Default: 5
101
102       border-size=px
103           Set popup border size to px pixels.
104
105           Default: 2
106
107       border-color=color
108           Set popup border color to color. See COLORS for more information.
109
110           Default: #4C7899FF
111
112       border-radius=px
113           Set popup corner radius to px pixels.
114
115           Default: 0
116
117       progress-color=[over|source] color
118           Set popup progress indicator color to color. See COLOR for more in‐
119           formation. To draw the progress indicator on top of the background
120           color, use the over attribute. To replace the background color, use
121           the source attribute (this can be useful when the notification is
122           semi-transparent).
123
124           Progress can be indicated in a notification by setting a hint,
125           "value" to an integer between 0 and 100 inclusive.
126
127           Default: over #5588AAFF
128
129       icons=0|1
130           Show icons in notifications.
131
132           Default: 1
133
134       max-icon-size=px
135           Set maximum icon size to px pixels.
136
137           Default: 64
138
139       icon-path=path[:path...]
140           Paths to search for icons when a notification specifies a name in‐
141           stead of a full path. Colon-delimited. This approximates the search
142           algorithm used by the XDG Icon Theme Specification, but does not
143           support any of the theme metadata. Therefore, if you want to search
144           parent themes, you'll need to add them to the path manually.
145
146           The path should be the root of the icon theme, the categories and
147           resolutions will be searched for the most appropriate match.
148
149           /usr/share/icons/hicolor and /usr/share/pixmaps are always
150           searched.
151
152           Default: ""
153
154       icon-location=position
155           Position of the icon relative to the displayed text. Valid options
156           are left, right, top and bottom.
157
158           Default: left
159
160       markup=0|1
161           If 1, enable Pango markup. If 0, disable Pango markup. If enabled,
162           Pango markup will be interpreted in your format specifier and in
163           the body of notifications.
164
165           Default: 1
166
167       actions=0|1
168           Applications may request an action to be associated with activating
169           a notification. Disabling this will cause mako to ignore these re‐
170           quests.
171
172           Default: 1
173
174       history=0|1
175           If set, mako will save notifications that have reached their time‐
176           out into the history buffer instead of immediately deleting them.
177           max-history determines the size of the history buffer.
178
179           Default: 1
180
181       format=format
182           Set notification format string to format. See FORMAT SPECIFIERS for
183           more information. To change this for grouped notifications, set it
184           within a grouped criteria.
185
186           Default: <b>%s</b>\n%b
187           Default when grouped: (%g) <b>%s</b>\n%b
188
189       text-alignment=left|center|right
190           Set notification text alignment.
191
192           Default: left
193
194       default-timeout=timeout
195           Set the default timeout to timeout in milliseconds. To disable the
196           timeout, set it to zero.
197
198           Default: 0
199
200       ignore-timeout=0|1
201           If set, mako will ignore the expire timeout sent by notifications
202           and use the one provided by default-timeout instead.
203
204           Default: 0
205
206       group-by=field[,field,...]
207           A comma-separated list of criteria fields that will be compared to
208           other visible notifications to determine if this one should form a
209           group with them. All listed criteria must be exactly equal for two
210           notifications to group.
211
212           Default: none
213
214       max-visible=n
215           Set maximum number of visible notifications to n. Older notifica‐
216           tions will be hidden. If -1, all notifications are visible.
217
218           Default: 5
219
220       output=name
221           Show notifications on the specified output. If empty, notifications
222           will appear on the focused output.
223
224           Requires the compositor to support the Wayland protocol xdg-output-
225           unstable-v1 version 2.
226
227           Default: ""
228
229       layer=layer
230           Arrange mako at the specified layer, relative to normal windows.
231           Supported values are background, bottom, top, and overlay. Using
232           overlay will cause notifications to be displayed above fullscreen
233           windows, though this may also occur at top depending on your com‐
234           positor.
235
236           Default: top
237
238       anchor=position
239           Show notifications at the specified position on the output. Sup‐
240           ported values are top-right, top-center, top-left, bottom-right,
241           bottom-center, bottom-left, center-right, center-left and center.
242
243           Default: top-right
244

CRITERIA

246       In addition to the set of options at the top of the file, the config
247       file may contain zero or more sections, each containing any combination
248       of the BINDING OPTIONS and STYLE OPTIONS. The sections, called crite‐
249       ria, are defined with an INI-like square bracket syntax. The brackets
250       may contain any number of fields, like so:
251
252           [field=value field2=value2 ...]
253
254       When a notification is received, it will be compared to the fields de‐
255       fined in each criteria. If all of the fields match, the style options
256       within will be applied to the notification. Fields not included in the
257       criteria are not considered during the match. A notification may match
258       any number of criteria. This matching occurs in the order the criteria
259       are defined in the config file, meaning that if multiple criteria match
260       a notification, the last occurrence of any given style option will
261       "win".
262
263       The following fields are available in criteria:
264
265app-name (string)
266app-icon (string)
267summary (string)
268           •   An exact match on the summary of the notification.
269           •   This field conflicts with summary~.
270summary~ (string)
271           •   A POSIX extended regular expression match on the summary of the
272               notification.
273           •   This field conflicts with summary.
274body (string)
275           •   An exact match on the body of the notification.
276           •   This field conflicts with body~.
277body~ (string)
278           •   A POSIX extended regular expression match on the body of the
279
280       notification.
281           •   This field conflicts with body.
282urgency (one of "low", "normal", "critical")
283category (string)
284desktop-entry (string)
285actionable (boolean)
286expiring (boolean)
287mode (string)
288           •   Only apply style options in this section if the provided mode
289               is currently enabled. For more information about modes, see the
290               MODES section.
291
292
293       The following fields are also available to match on a second pass based
294       on where previous style options decided to place each notification:
295
296grouped (boolean)
297           •   Whether the notification is grouped with any others (its group-
298               index is not -1).
299group-index (int)
300           •   The notification's index within its group, or -1 if it is not
301               grouped.
302hidden (boolean)
303hidden is special, it defines the style for the placeholder
304               shown when the number of notifications or groups exceeds max-
305               visible.
306output (string)
307             - Which output the notification was sorted onto. See the output
308           style
309               option for possible values.
310anchor (string)
311           •   Which position on the output the notification was assigned to.
312               See the
313               anchor style option for possible values.
314
315
316       There are only two passes performed on each notification, so the sec‐
317       ond-pass critera are not allowed to reposition the notification.
318
319       If a field's value contains special characters, they may be escaped
320       with a backslash, or quoted:
321
322           [app-name="Google Chrome"]
323
324           [app-name=Google\ Chrome]
325
326       Quotes within quotes may also be escaped, and a literal backslash may
327       be specified as \\. No spaces are allowed around the equal sign. Escap‐
328       ing equal signs within values is unnecessary.
329
330       Additionally, boolean values may be specified using any of true/false,
331       0/1, or as bare words:
332
333           [actionable=true] [actionable=1] [actionable]
334
335           [actionable=false] [actionable=0] [!actionable]
336
337       There are three criteria always present at the front of the list:
338       •   An empty criteria which matches all notifications and contains the
339           defaults for all style options, overwritten with any configured in
340           the global section.
341       •   [grouped], which sets the default format for grouped notifications
342           and sets them invisible.
343       •   [group-index=0], which makes the first member of each group visible
344           again.
345
346
347       These options can be overridden by simply defining the criteria your‐
348       self and overriding them.
349
350       There are some rules restricting what can be configured depending on
351       what is being matched by a given criteria:
352
353       •   Criteria matching grouped or group-index are not allowed to change
354           the anchor, output, or group-by, as this would invalidate the
355           grouping. Grouping is only performed once rather than recursively,
356           to avoid the potential for infinite loops.
357
358

CRITERIA-ONLY STYLE OPTIONS

360       Some style options are not useful in the global context and therefore
361       have no associated command-line option.
362
363       invisible=0|1
364           Whether this notification should be invisible even if it is above
365           the max-visible cutoff. This is used primarily for hiding members
366           of groups. If you want to make more than the first group member
367           visible, turn this option off within a group-index criteria.
368
369           Default: 0
370

COLORS

372       Colors can be specified as #RRGGBB or #RRGGBBAA.
373

DIRECTIONAL VALUES

375       Some options set values that affect all four edges of a notification.
376       These options can be specified in several different ways, depending on
377       how much control over each edge is desired:
378
379       •   A single value will apply to all four edges.
380       •   Two values will set vertical and horizontal edges separately.
381       •   Three will set top, horizontal, and bottom edges separately.
382       •   Four will give each edge a separate value.
383
384
385       When specifying multiple values, they should be comma-separated. For
386       example, this would set the top margin to 10, left and right to 20, and
387       bottom to five:
388
389           margin = 10,20,5
390

FORMAT SPECIFIERS

392       Format specification works similarly to printf(3), but with a different
393       set of specifiers.
394
395       %%   Literal "%"
396
397       \\   Literal "\"
398
399       \n   New Line
400
401   For notifications
402       %a   Application name
403
404       %s   Notification summary
405
406       %b   Notification body
407
408       %g   Number of notifications in the current group
409
410   For the hidden notifications placeholder
411       %h   Number of hidden notifications
412
413       %t   Total number of notifications
414

MODES

416       mako supports applying style options conditionally via modes. A config‐
417       uration section with a mode criteria will only be applied if the cur‐
418       rent mode matches. makoctl(1) can be used to change the current mode.
419
420       The default mode is named "default".
421
422       For example, to hide all notifications if the mode "do-not-disturb" is
423       enabled:
424
425           [mode=do-not-disturb]
426           invisible=1
427
428       makoctl set-mode do-not-disturb will hide all notifications, makoctl
429       set-mode default will show them again.
430

AUTHORS

432       Maintained by Simon Ser <contact@emersion.fr>, who is assisted by other
433       open-source contributors. For more information about mako development,
434       see https://github.com/emersion/mako.
435

SEE ALSO

437       mako(1) makoctl(1)
438
439
440
441                                  2021-07-22                           mako(5)
Impressum