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 one to perform an action when an event is triggered.
33       Supported values are none, dismiss, dismiss-all, dismiss-group, invoke-
34       action <action>, invoke-default-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
63       When using invoke-action or invoke-default-action a xdg-activation to‐
64       ken will be sent to the client, allowing the client to request focus
65       from the compositor. The compositor must support the xdg_activation_v1
66       protocol and allow the focus request for the example to work correctly:
67
68           [app-name="some-app-id" actionable]
69           on-button-left=invoke-action mail-reply-sender
70

STYLE OPTIONS

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

CRITERIA

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

CRITERIA-ONLY STYLE OPTIONS

378       Some style options are not useful in the global context and therefore
379       have no associated command-line option.
380
381       invisible=0|1
382           Whether this notification should be invisible even if it is above
383           the max-visible cutoff. This is used primarily for hiding members
384           of groups. If you want to make more than the first group member
385           visible, turn this option off within a group-index criteria.
386
387           Default: 0
388

COLORS

390       Colors can be specified as #RRGGBB or #RRGGBBAA.
391

DIRECTIONAL VALUES

393       Some options set values that affect all four edges of a notification.
394       These options can be specified in several different ways, depending on
395       how much control over each edge is desired:
396
397       •   A single value will apply to all four edges.
398       •   Two values will set vertical and horizontal edges separately.
399       •   Three will set top, horizontal, and bottom edges separately.
400       •   Four will set top, right, bottom, and left edges separately.
401
402
403       When specifying multiple values, they should be comma-separated. For
404       example, this would set the top margin to 10, left and right to 20, and
405       bottom to five:
406
407           margin = 10,20,5
408

FORMAT SPECIFIERS

410       Format specification works similarly to printf(3), but with a different
411       set of specifiers.
412
413       %%   Literal "%"
414
415       \\   Literal "\"
416
417       \n   New Line
418
419   For notifications
420       %a   Application name
421
422       %s   Notification summary
423
424       %b   Notification body
425
426       %g   Number of notifications in the current group
427
428       %i   Notification id
429
430   For the hidden notifications placeholder
431       %h   Number of hidden notifications
432
433       %t   Total number of notifications
434

MODES

436       mako supports applying style options conditionally via modes. A config‐
437       uration section with a mode criteria will only be applied if the cur‐
438       rent mode matches. makoctl(1) can be used to change the current mode.
439
440       The initial list of modes contains a single mode called "default". This
441       is deprecated, in a future version the initial list of modes will be
442       empty.
443
444       For example, to hide all notifications if the mode "do-not-disturb" is
445       enabled:
446
447           [mode=do-not-disturb]
448           invisible=1
449
450       makoctl mode -a do-not-disturb will hide all notifications, makoctl
451       mode -r do-not-disturb will show them again.
452

AUTHORS

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

SEE ALSO

459       mako(1) makoctl(1)
460
461
462
463                                  2023-06-03                           mako(5)
Impressum