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 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
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 outer-margin=directional
91 Set outer-margin of each edge to the size specified by directional.
92 See DIRECTIONAL VALUES for more information. This margin applies to
93 the outside of the whole notification list.
94 Default: 0
96 margin=directional
98 Set margin of each edge to the size specified by directional. See
99 DIRECTIONAL VALUES for more information. This margin applies to
100 each individual notification. Note that it applies in addition to
101 outer-margin, meaning first and last notifications will use the sum
102 of both margins.
103 Default: 10
105 padding=directional
107 Set padding on each side to the size specified by directional. See
108 DIRECTIONAL VALUES for more information.
109 Default: 5
111 border-size=px
113 Set popup border size to px pixels.
114 Default: 2
116 border-color=color
118 Set popup border color to color. See COLORS for more information.
119 Default: #4C7899FF
121 border-radius=px
123 Set popup corner radius to px pixels.
124 Default: 0
126 progress-color=[over|source] color
128 Set popup progress indicator color to color. See COLOR for more in‐
129 formation. To draw the progress indicator on top of the background
130 color, use the over attribute. To replace the background color, use
131 the source attribute (this can be useful when the notification is
132 semi-transparent).
133 Progress can be indicated in a notification by setting a hint,
135 "value" to an integer between 0 and 100 inclusive.
136 Default: over #5588AAFF
138 icons=0|1
140 Show icons in notifications.
141 Default: 1
143 max-icon-size=px
145 Set maximum icon size to px pixels.
146 Default: 64
148 icon-path=path[:path...]
150 Paths to search for icons when a notification specifies a name in‐
151 stead of a full path. Colon-delimited. This approximates the search
152 algorithm used by the XDG Icon Theme Specification, but does not
153 support any of the theme metadata. Therefore, if you want to search
154 parent themes, you'll need to add them to the path manually.
155 The path should be the root of the icon theme, the categories and
157 resolutions will be searched for the most appropriate match.
158 /usr/share/icons/hicolor and /usr/share/pixmaps are always
160 searched.
161 Default: ""
163 icon-location=position
165 Position of the icon relative to the displayed text. Valid options
166 are left, right, top and bottom.
167 Default: left
169 markup=0|1
171 If 1, enable Pango markup. If 0, disable Pango markup. If enabled,
172 Pango markup will be interpreted in your format specifier and in
173 the body of notifications.
174 Default: 1
176 actions=0|1
178 Applications may request an action to be associated with activating
179 a notification. Disabling this will cause mako to ignore these re‐
180 quests.
181 Default: 1
183 history=0|1
185 If set, mako will save notifications that have reached their time‐
186 out into the history buffer instead of immediately deleting them.
187 max-history determines the size of the history buffer.
188 Default: 1
190 format=format
192 Set notification format string to format. See FORMAT SPECIFIERS for
193 more information. To change this for grouped notifications, set it
194 within a grouped criteria.
195 Default: <b>%s</b>\n%b
197 Default when grouped: (%g) <b>%s</b>\n%b
198 text-alignment=left|center|right
200 Set notification text alignment.
201 Default: left
203 default-timeout=timeout
205 Set the default timeout to timeout in milliseconds. To disable the
206 timeout, set it to zero.
207 Default: 0
209 ignore-timeout=0|1
211 If set, mako will ignore the expire timeout sent by notifications
212 and use the one provided by default-timeout instead.
213 Default: 0
215 group-by=field[,field,...]
217 A comma-separated list of criteria fields that will be compared to
218 other visible notifications to determine if this one should form a
219 group with them. All listed criteria must be exactly equal for two
220 notifications to group.
221 Default: none
223 max-visible=n
225 Set maximum number of visible notifications to n. Older notifica‐
226 tions will be hidden. If -1, all notifications are visible.
227 Default: 5
229 output=name
231 Show notifications on the specified output. If empty, notifications
232 will appear on the focused output.
233 Requires the compositor to support the Wayland protocol xdg-output-
235 unstable-v1 version 2.
236 Default: ""
238 layer=layer
240 Arrange mako at the specified layer, relative to normal windows.
241 Supported values are background, bottom, top, and overlay. Using
242 overlay will cause notifications to be displayed above fullscreen
243 windows, though this may also occur at top depending on your com‐
244 positor.
245 Default: top
247 anchor=position
249 Show notifications at the specified position on the output. Sup‐
250 ported values are top-right, top-center, top-left, bottom-right,
251 bottom-center, bottom-left, center-right, center-left and center.
252 Default: top-right
254
256 In addition to the set of options at the top of the file, the config
257 file may contain zero or more sections, each containing any combination
258 of the BINDING OPTIONS and STYLE OPTIONS. The sections, called crite‐
259 ria, are defined with an INI-like square bracket syntax. The brackets
260 may contain any number of fields, like so:
261 [field=value field2=value2 ...]
263 When a notification is received, it will be compared to the fields de‐
265 fined in each criteria. If all of the fields match, the style options
266 within will be applied to the notification. Fields not included in the
267 criteria are not considered during the match. A notification may match
268 any number of criteria. This matching occurs in the order the criteria
269 are defined in the config file, meaning that if multiple criteria match
270 a notification, the last occurrence of any given style option will
271 "win".
272 The following fields are available in criteria:
274 • app-name (string)
276 • app-icon (string)
277 • summary (string)
278 • An exact match on the summary of the notification.
279 • This field conflicts with summary~.
280 • summary~ (string)
281 • A POSIX extended regular expression match on the summary of the
282 notification.
283 • This field conflicts with summary.
284 • body (string)
285 • An exact match on the body of the notification.
286 • This field conflicts with body~.
287 • body~ (string)
288 • A POSIX extended regular expression match on the body of the
289 notification.
291 • This field conflicts with body.
292 • urgency (one of "low", "normal", "critical")
293 • category (string)
294 • desktop-entry (string)
295 • actionable (boolean)
296 • expiring (boolean)
297 • mode (string)
298 • Only apply style options in this section if the provided mode
299 is currently enabled. For more information about modes, see the
300 MODES section.
301 The following fields are also available to match on a second pass based
304 on where previous style options decided to place each notification:
305 • grouped (boolean)
307 • Whether the notification is grouped with any others (its group-
308 index is not -1).
309 • group-index (int)
310 • The notification's index within its group, or -1 if it is not
311 grouped.
312 • hidden (boolean)
313 • hidden is special, it defines the style for the placeholder
314 shown when the number of notifications or groups exceeds max-
315 visible.
316 • output (string)
317 - Which output the notification was sorted onto. See the output
318 style
319 option for possible values.
320 • anchor (string)
321 • Which position on the output the notification was assigned to.
322 See the
323 anchor style option for possible values.
324 There are only two passes performed on each notification, so the sec‐
327 ond-pass criteria are not allowed to reposition the notification.
328 If a field's value contains special characters, they may be escaped
330 with a backslash, or quoted:
331 [app-name="Google Chrome"]
333 [app-name=Google\ Chrome]
335 Quotes within quotes may also be escaped, and a literal backslash may
337 be specified as \\. No spaces are allowed around the equal sign. Escap‐
338 ing equal signs within values is unnecessary.
339 Additionally, boolean values may be specified using any of true/false,
341 0/1, or as bare words:
342 [actionable=true] [actionable=1] [actionable]
344 [actionable=false] [actionable=0] [!actionable]
346 There are three criteria always present at the front of the list:
348 • An empty criteria which matches all notifications and contains the
349 defaults for all style options, overwritten with any configured in
350 the global section.
351 • [grouped], which sets the default format for grouped notifications
352 and sets them invisible.
353 • [group-index=0], which makes the first member of each group visible
354 again.
355 These options can be overridden by simply defining the criteria your‐
358 self and overriding them.
359 There are some rules restricting what can be configured depending on
361 what is being matched by a given criteria:
362 • Criteria matching grouped or group-index are not allowed to change
364 the anchor, output, or group-by, as this would invalidate the
365 grouping. Grouping is only performed once rather than recursively,
366 to avoid the potential for infinite loops.
367
370 Some style options are not useful in the global context and therefore
371 have no associated command-line option.
372 invisible=0|1
374 Whether this notification should be invisible even if it is above
375 the max-visible cutoff. This is used primarily for hiding members
376 of groups. If you want to make more than the first group member
377 visible, turn this option off within a group-index criteria.
378 Default: 0
380
382 Colors can be specified as #RRGGBB or #RRGGBBAA.
383
385 Some options set values that affect all four edges of a notification.
386 These options can be specified in several different ways, depending on
387 how much control over each edge is desired:
388 • A single value will apply to all four edges.
390 • Two values will set vertical and horizontal edges separately.
391 • Three will set top, horizontal, and bottom edges separately.
392 • Four will set top, right, bottom, and left edges separately.
393 When specifying multiple values, they should be comma-separated. For
396 example, this would set the top margin to 10, left and right to 20, and
397 bottom to five:
398 margin = 10,20,5
400
402 Format specification works similarly to printf(3), but with a different
403 set of specifiers.
404 %% Literal "%"
406 \\ Literal "\"
408 \n New Line
410 For notifications
412 %a Application name
413 %s Notification summary
415 %b Notification body
417 %g Number of notifications in the current group
419 %i Notification id
421 For the hidden notifications placeholder
423 %h Number of hidden notifications
424 %t Total number of notifications
426
428 mako supports applying style options conditionally via modes. A config‐
429 uration section with a mode criteria will only be applied if the cur‐
430 rent mode matches. makoctl(1) can be used to change the current mode.
431 The initial list of modes contains a single mode called "default". This
433 is deprecated, in a future version the initial list of modes will be
434 empty.
435 For example, to hide all notifications if the mode "do-not-disturb" is
437 enabled:
438 [mode=do-not-disturb]
440 invisible=1
441 makoctl mode -a do-not-disturb will hide all notifications, makoctl
443 mode -r do-not-disturb will show them again.
444
446 Maintained by Simon Ser <contact@emersion.fr>, who is assisted by other
447 open-source contributors. For more information about mako development,
448 see https://github.com/emersion/mako.
449
451 mako(1) makoctl(1)
452 2022-07-21 mako(5)