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 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 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
64 font=font
65 Set font to font, in Pango format.
66 Default: monospace 10
68 background-color=color
70 Set background color to color. See COLORS for more information.
71 Default: #285577FF
73 text-color=color
75 Set text color to color. See COLORS for more information.
76 Default: #FFFFFFFF
78 width=px
80 Set width of notification popups.
81 Default: 300
83 height=px
85 Set maximum height of notification popups. Notifications whose text
86 takes up less space are shrunk to fit.
87 Default: 100
89 margin=directional
91 Set margin of each edge to the size specified by directional. See
92 DIRECTIONAL VALUES for more information.
93 Default: 10
95 padding=directional
97 Set padding on each side to the size specified by directional. See
98 DIRECTIONAL VALUES for more information.
99 Default: 5
101 border-size=px
103 Set popup border size to px pixels.
104 Default: 2
106 border-color=color
108 Set popup border color to color. See COLORS for more information.
109 Default: #4C7899FF
111 border-radius=px
113 Set popup corner radius to px pixels.
114 Default: 0
116 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 Progress can be indicated in a notification by setting a hint,
125 "value" to an integer between 0 and 100 inclusive.
126 Default: over #5588AAFF
128 icons=0|1
130 Show icons in notifications.
131 Default: 1
133 max-icon-size=px
135 Set maximum icon size to px pixels.
136 Default: 64
138 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 The path should be the root of the icon theme, the categories and
147 resolutions will be searched for the most appropriate match.
148 /usr/share/icons/hicolor and /usr/share/pixmaps are always
150 searched.
151 Default: ""
153 icon-location=position
155 Position of the icon relative to the displayed text. Valid options
156 are left, right, top and bottom.
157 Default: left
159 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 Default: 1
166 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 Default: 1
173 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 Default: 1
180 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 Default: <b>%s</b>\n%b
187 Default when grouped: (%g) <b>%s</b>\n%b
188 text-alignment=left|center|right
190 Set notification text alignment.
191 Default: left
193 default-timeout=timeout
195 Set the default timeout to timeout in milliseconds. To disable the
196 timeout, set it to zero.
197 Default: 0
199 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 Default: 0
205 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 Default: none
213 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 Default: 5
219 output=name
221 Show notifications on the specified output. If empty, notifications
222 will appear on the focused output.
223 Requires the compositor to support the Wayland protocol xdg-output-
225 unstable-v1 version 2.
226 Default: ""
228 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 Default: top
237 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 Default: top-right
244
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 [field=value field2=value2 ...]
253 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 The following fields are available in criteria:
264 • app-name (string)
266 • app-icon (string)
267 • summary (string)
268 • An exact match on the summary of the notification.
269 • This field conflicts with summary~.
270 • summary~ (string)
271 • A POSIX extended regular expression match on the summary of the
272 notification.
273 • This field conflicts with summary.
274 • body (string)
275 • An exact match on the body of the notification.
276 • This field conflicts with body~.
277 • body~ (string)
278 • A POSIX extended regular expression match on the body of the
279 notification.
281 • This field conflicts with body.
282 • urgency (one of "low", "normal", "critical")
283 • category (string)
284 • desktop-entry (string)
285 • actionable (boolean)
286 • expiring (boolean)
287 • mode (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 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 • grouped (boolean)
297 • Whether the notification is grouped with any others (its group-
298 index is not -1).
299 • group-index (int)
300 • The notification's index within its group, or -1 if it is not
301 grouped.
302 • hidden (boolean)
303 • hidden is special, it defines the style for the placeholder
304 shown when the number of notifications or groups exceeds max-
305 visible.
306 • output (string)
307 - Which output the notification was sorted onto. See the output
308 style
309 option for possible values.
310 • anchor (string)
311 • Which position on the output the notification was assigned to.
312 See the
313 anchor style option for possible values.
314 There are only two passes performed on each notification, so the sec‐
317 ond-pass critera are not allowed to reposition the notification.
318 If a field's value contains special characters, they may be escaped
320 with a backslash, or quoted:
321 [app-name="Google Chrome"]
323 [app-name=Google\ Chrome]
325 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 Additionally, boolean values may be specified using any of true/false,
331 0/1, or as bare words:
332 [actionable=true] [actionable=1] [actionable]
334 [actionable=false] [actionable=0] [!actionable]
336 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 These options can be overridden by simply defining the criteria your‐
348 self and overriding them.
349 There are some rules restricting what can be configured depending on
351 what is being matched by a given criteria:
352 • 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
360 Some style options are not useful in the global context and therefore
361 have no associated command-line option.
362 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 Default: 0
370
372 Colors can be specified as #RRGGBB or #RRGGBBAA.
373
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 • 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 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 margin = 10,20,5
390
392 Format specification works similarly to printf(3), but with a different
393 set of specifiers.
394 %% Literal "%"
396 \\ Literal "\"
398 \n New Line
400 For notifications
402 %a Application name
403 %s Notification summary
405 %b Notification body
407 %g Number of notifications in the current group
409 For the hidden notifications placeholder
411 %h Number of hidden notifications
412 %t Total number of notifications
414
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 The default mode is named "default".
421 For example, to hide all notifications if the mode "do-not-disturb" is
423 enabled:
424 [mode=do-not-disturb]
426 invisible=1
427 makoctl set-mode do-not-disturb will hide all notifications, makoctl
429 set-mode default will show them again.
430
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
437 mako(1) makoctl(1)
438 2022-01-20 mako(5)