1mako(5) File Formats Manual mako(5)
2
6 mako - configuration file
7
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 key=value
14 Empty lines and lines that begin with # are ignored.
16
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 Default: 5
24 sort=+/-time | +/-priority
26 Sorts incoming notifications by time and/or priority in ascend‐
27 ing(+) or descending(-) order.
28 Default: -time
30
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 on-button-left=action
37 Default: invoke-default-action
38 on-button-middle=action
40 Default: none
41 on-button-right=action
43 Default: dismiss
44 on-touch=action
46 Default: dismiss
47 on-notify = action
49 Default: none
50 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 on-button-middle=exec makoctl menu -n "$id" dmenu -p 'Select action: '
57 The following option will play a sound when a new notification is
59 opened:
60 on-notify=exec mpv /usr/share/sounds/freedesktop/stereo/message.oga
62 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 [app-name="some-app-id" actionable]
69 on-button-left=invoke-action mail-reply-sender
70
72 font=font
73 Set font to font, in Pango format.
74 Default: monospace 10
76 background-color=color
78 Set background color to color. See COLORS for more information.
79 Default: #285577FF
81 text-color=color
83 Set text color to color. See COLORS for more information.
84 Default: #FFFFFFFF
86 width=px
88 Set width of notification popups.
89 Default: 300
91 height=px
93 Set maximum height of notification popups. Notifications whose text
94 takes up less space are shrunk to fit.
95 Default: 100
97 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 Default: 0
104 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 Default: 10
113 padding=directional
115 Set padding on each side to the size specified by directional. See
116 DIRECTIONAL VALUES for more information.
117 Default: 5
119 border-size=px
121 Set popup border size to px pixels.
122 Default: 2
124 border-color=color
126 Set popup border color to color. See COLORS for more information.
127 Default: #4C7899FF
129 border-radius=px
131 Set popup corner radius to px pixels.
132 Default: 0
134 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 Progress can be indicated in a notification by setting a hint,
143 "value" to an integer between 0 and 100 inclusive.
144 Default: over #5588AAFF
146 icons=0|1
148 Show icons in notifications.
149 Default: 1
151 max-icon-size=px
153 Set maximum icon size to px pixels.
154 Default: 64
156 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 The path should be the root of the icon theme, the categories and
165 resolutions will be searched for the most appropriate match.
166 /usr/share/icons/hicolor and /usr/share/pixmaps are always
168 searched.
169 Default: ""
171 icon-location=position
173 Position of the icon relative to the displayed text. Valid options
174 are left, right, top and bottom.
175 Default: left
177 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 Default: 1
184 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 Default: 1
191 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 Default: 1
198 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 Default: <b>%s</b>\n%b
205 Default when grouped: (%g) <b>%s</b>\n%b
206 text-alignment=left|center|right
208 Set notification text alignment.
209 Default: left
211 default-timeout=timeout
213 Set the default timeout to timeout in milliseconds. To disable the
214 timeout, set it to zero.
215 Default: 0
217 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 Default: 0
223 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 Default: none
231 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 Default: 5
237 output=name
239 Show notifications on the specified output. If empty, notifications
240 will appear on the focused output.
241 Requires the compositor to support the Wayland protocol xdg-output-
243 unstable-v1 version 2.
244 Default: ""
246 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 Default: top
255 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 Default: top-right
262
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 [field=value field2=value2 ...]
271 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 The following fields are available in criteria:
282 • app-name (string)
284 • app-icon (string)
285 • summary (string)
286 • An exact match on the summary of the notification.
287 • This field conflicts with summary~.
288 • summary~ (string)
289 • A POSIX extended regular expression match on the summary of the
290 notification.
291 • This field conflicts with summary.
292 • body (string)
293 • An exact match on the body of the notification.
294 • This field conflicts with body~.
295 • body~ (string)
296 • A POSIX extended regular expression match on the body of the
297 notification.
299 • This field conflicts with body.
300 • urgency (one of "low", "normal", "critical")
301 • category (string)
302 • desktop-entry (string)
303 • actionable (boolean)
304 • expiring (boolean)
305 • mode (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 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 • grouped (boolean)
315 • Whether the notification is grouped with any others (its group-
316 index is not -1).
317 • group-index (int)
318 • The notification's index within its group, or -1 if it is not
319 grouped.
320 • hidden (boolean)
321 • hidden is special, it defines the style for the placeholder
322 shown when the number of notifications or groups exceeds max-
323 visible.
324 • output (string)
325 - Which output the notification was sorted onto. See the output
326 style
327 option for possible values.
328 • anchor (string)
329 • Which position on the output the notification was assigned to.
330 See the
331 anchor style option for possible values.
332 There are only two passes performed on each notification, so the sec‐
335 ond-pass criteria are not allowed to reposition the notification.
336 If a field's value contains special characters, they may be escaped
338 with a backslash, or quoted:
339 [app-name="Google Chrome"]
341 [app-name=Google\ Chrome]
343 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 Additionally, boolean values may be specified using any of true/false,
349 0/1, or as bare words:
350 [actionable=true] [actionable=1] [actionable]
352 [actionable=false] [actionable=0] [!actionable]
354 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 These options can be overridden by simply defining the criteria your‐
366 self and overriding them.
367 There are some rules restricting what can be configured depending on
369 what is being matched by a given criteria:
370 • 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
378 Some style options are not useful in the global context and therefore
379 have no associated command-line option.
380 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 Default: 0
388
390 Colors can be specified as #RRGGBB or #RRGGBBAA.
391
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 • 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 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 margin = 10,20,5
408
410 Format specification works similarly to printf(3), but with a different
411 set of specifiers.
412 %% Literal "%"
414 \\ Literal "\"
416 \n New Line
418 For notifications
420 %a Application name
421 %s Notification summary
423 %b Notification body
425 %g Number of notifications in the current group
427 %i Notification id
429 For the hidden notifications placeholder
431 %h Number of hidden notifications
432 %t Total number of notifications
434
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 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 For example, to hide all notifications if the mode "do-not-disturb" is
445 enabled:
446 [mode=do-not-disturb]
448 invisible=1
449 makoctl mode -a do-not-disturb will hide all notifications, makoctl
451 mode -r do-not-disturb will show them again.
452
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
459 mako(1) makoctl(1)
460 2023-06-03 mako(5)