.\" Generated by scdoc 1.11.3 .\" Complete documentation for this program is not available as a GNU info page .ie \n(.g .ds Aq \(aq .el .ds Aq ' .nh .ad l .\" Begin generated content: .TH "mako" "5" "2024-05-12" .PP .SH NAME .PP mako - configuration file .PP .SH DESCRIPTION .PP The config file is located at \fB~/.\&config/mako/config\fR or at \fB$XDG_CONFIG_HOME/mako/config\fR.\& Option lines can be specified to configure mako like so: .PP .RS 4 key=value .PP .RE Empty lines and lines that begin with # are ignored.\& .PP .SH GLOBAL CONFIGURATION OPTIONS .PP \fBmax-history\fR=\fIn\fR .RS 4 Set maximum number of expired notifications to keep in the history buffer to \fIn\fR.\& If the buffer is full, newly expired notifications replace the oldest ones.\& If 0, history is disabled.\& .PP Default: 5 .PP .RE \fBsort\fR=\fI+/-time\fR | \fI+/-priority\fR .RS 4 Sorts incoming notifications by time and/or priority in ascending(+) or descending(-) order.\& .PP Default: -time .PP .RE .SH BINDING OPTIONS .PP Bindings allow one to perform an action when an event is triggered.\& .PP Supported options: .PP \fBon-button-left\fR=\fIaction\fR .RS 4 Performs the action when the left pointer button is pressed.\& .PP Default: invoke-default-action .PP .RE \fBon-button-middle\fR=\fIaction\fR .RS 4 Performs the action when the middle pointer button is pressed.\& .PP Default: none .PP .RE \fBon-button-right\fR=\fIaction\fR .RS 4 Performs the action when the right pointer button is pressed.\& .PP Default: dismiss .PP .RE \fBon-touch\fR=\fIaction\fR .RS 4 Performs the action when tapped via a touch device.\& .PP Default: dismiss .PP .RE \fBon-notify\fR=\fIaction\fR .RS 4 Performs the action when the notification is opened.\& .PP Default: none .PP .RE Supported actions: .PP \fBnone\fR .RS 4 Do nothing.\& .PP .RE \fBdismiss [--no-history]\fR .RS 4 Dismiss the current notification.\& If \fB--no-history\fR is passed, the notification won'\&t be added to history.\& .PP .RE \fBdismiss-all\fR .RS 4 Dismiss all notifications.\& .PP .RE \fBdismiss-group\fR .RS 4 Dismiss notifications in the current group.\& .PP .RE \fBinvoke-action\fR .RS 4 Invoke the named action on the notification.\& .PP An xdg-activation token will be sent to the client, allowing the client to request focus from the compositor.\& The compositor must support the xdg_activation_v1 protocol and allow the focus request for the following example to work correctly: .PP .nf .RS 4 [app-name="some-app-id" actionable] on-button-left=invoke-action mail-reply-sender .fi .RE .PP .RE \fBinvoke-default-action\fR .RS 4 Invoke the default action on the notification.\& .PP .RE \fBexec\fR .RS 4 Execute a shell command.\& .PP The command will be executed in a POSIX shell.\& The shell variable \fIid\fR will be set to the notification ID.\& For example, the following option will display an interactive action menu on middle click: .PP .nf .RS 4 on-button-middle=exec makoctl menu -n "$id" dmenu -p \&'Select action: \&' .fi .RE .PP The following option will play a sound when a new notification is opened: .PP .nf .RS 4 on-notify=exec mpv /usr/share/sounds/freedesktop/stereo/message\&.oga .fi .RE .PP .RE .SH STYLE OPTIONS .PP \fBfont\fR=\fIfont\fR .RS 4 Set font to \fIfont\fR, as a Pango font description.\& For more information on Pango font descriptions, see: https://docs.\>k.\&org/Pango/type_func.\&FontDescription.\&from_string.\&html#description .PP Default: monospace 10 .PP .RE \fBbackground-color\fR=\fIcolor\fR .RS 4 Set background color to \fIcolor\fR.\& See \fBCOLORS\fR for more information.\& .PP Default: #285577FF .PP .RE \fBtext-color\fR=\fIcolor\fR .RS 4 Set text color to \fIcolor\fR.\& See \fBCOLORS\fR for more information.\& .PP Default: #FFFFFFFF .PP .RE \fBwidth\fR=\fIpx\fR .RS 4 Set width of notification popups.\& .PP Default: 300 .PP .RE \fBheight\fR=\fIpx\fR .RS 4 Set maximum height of notification popups.\& Notifications whose text takes up less space are shrunk to fit.\& .PP Default: 100 .PP .RE \fBouter-margin\fR=\fIdirectional\fR .RS 4 Set outer-margin of each edge to the size specified by \fIdirectional\fR.\& See \fBDIRECTIONAL VALUES\fR for more information.\& This margin applies to the outside of the whole notification list.\& .PP Default: 0 .PP .RE \fBmargin\fR=\fIdirectional\fR .RS 4 Set margin of each edge to the size specified by \fIdirectional\fR.\& See \fBDIRECTIONAL VALUES\fR for more information.\& This margin applies to each individual notification.\& Note that it applies in addition to outer-margin, meaning first and last notifications will use the sum of both margins.\& .PP Default: 10 .PP .RE \fBpadding\fR=\fIdirectional\fR .RS 4 Set padding on each side to the size specified by \fIdirectional\fR.\& See \fBDIRECTIONAL VALUES\fR for more information.\& .PP Default: 5 .PP .RE \fBborder-size\fR=\fIpx\fR .RS 4 Set popup border size to \fIpx\fR pixels.\& .PP Default: 2 .PP .RE \fBborder-color\fR=\fIcolor\fR .RS 4 Set popup border color to \fIcolor\fR.\& See \fBCOLORS\fR for more information.\& .PP Default: #4C7899FF .PP .RE \fBborder-radius\fR=\fIpx\fR .RS 4 Set popup corner radius to \fIpx\fR pixels.\& .PP Default: 0 .PP .RE \fBprogress-color\fR=[over|source] \fIcolor\fR .RS 4 Set popup progress indicator color to \fIcolor\fR.\& See \fBCOLOR\fR for more information.\& To draw the progress indicator on top of the background color, use the \fBover\fR attribute.\& To replace the background color, use the \fBsource\fR attribute (this can be useful when the notification is semi-transparent).\& .PP Progress can be indicated in a notification by setting a hint, "value" to an integer between 0 and 100 inclusive.\& .PP Default: over #5588AAFF .PP .RE \fBicons\fR=0|1 .RS 4 Show icons in notifications.\& .PP Default: 1 .PP .RE \fBmax-icon-size\fR=\fIpx\fR .RS 4 Set maximum icon size to \fIpx\fR pixels.\& .PP Default: 64 .PP .RE \fBicon-path\fR=\fIpath\fR[:\fIpath\fR.\&.\&.\&] .RS 4 Paths to search for icons when a notification specifies a name instead of a full path.\& Colon-delimited.\& This approximates the search algorithm used by the XDG Icon Theme Specification, but does not support any of the theme metadata.\& Therefore, if you want to search parent themes, you'\&ll need to add them to the path manually.\& .PP The path should be the root of the icon theme, the categories and resolutions will be searched for the most appropriate match.\& .PP /usr/share/icons/hicolor and /usr/share/pixmaps are always searched.\& .PP Default: "" .PP .RE \fBicon-location\fR=\fIposition\fR .RS 4 Position of the icon relative to the displayed text.\& Valid options are \fIleft\fR, \fIright\fR, \fItop\fR and \fIbottom\fR.\& .PP Default: left .PP .RE \fBmarkup\fR=0|1 .RS 4 If 1, enable Pango markup.\& If 0, disable Pango markup.\& If enabled, Pango markup will be interpreted in your format specifier and in the body of notifications.\& .PP Default: 1 .PP .RE \fBactions\fR=0|1 .RS 4 Applications may request an action to be associated with activating a notification.\& Disabling this will cause mako to ignore these requests.\& .PP Default: 1 .PP .RE \fBhistory\fR=0|1 .RS 4 If set, mako will save notifications that have reached their timeout into the history buffer instead of immediately deleting them.\& \fImax-history\fR determines the size of the history buffer.\& .PP Default: 1 .PP .RE \fBformat\fR=\fIformat\fR .RS 4 Set notification format string to \fIformat\fR.\& See \fBFORMAT SPECIFIERS\fR for more information.\& To change this for grouped notifications, set it within a \fIgrouped\fR criteria.\& .PP Default: %s\en%b .br Default when grouped: (%g) %s\en%b .PP .RE \fBtext-alignment\fR=left|center|right .RS 4 Set notification text alignment.\& .PP Default: left .PP .RE \fBdefault-timeout\fR=\fItimeout\fR .RS 4 Set the default timeout to \fItimeout\fR in milliseconds.\& To disable the timeout, set it to zero.\& .PP Default: 0 .PP .RE \fBignore-timeout\fR=0|1 .RS 4 If set, mako will ignore the expire timeout sent by notifications and use the one provided by \fIdefault-timeout\fR instead.\& .PP Default: 0 .PP .RE \fBgroup-by\fR=\fIfield[,field,.\&.\&.\&]\fR .RS 4 A comma-separated list of criteria fields that will be compared to other visible notifications to determine if this one should form a group with them.\& All listed criteria must be exactly equal for two notifications to group.\& .PP Default: none .PP .RE \fBmax-visible\fR=\fIn\fR .RS 4 Set maximum number of visible notifications to \fIn\fR.\& Older notifications will be hidden.\& If -1, all notifications are visible.\& .PP Default: 5 .PP .RE \fBoutput\fR=\fIname\fR .RS 4 Show notifications on the specified output.\& If empty, notifications will appear on the focused output.\& .PP Requires the compositor to support the Wayland protocol xdg-output-unstable-v1 version 2.\& .PP Default: "" .PP .RE \fBlayer\fR=\fIlayer\fR .RS 4 Arrange mako at the specified layer, relative to normal windows.\& Supported values are \fIbackground\fR, \fIbottom\fR, \fItop\fR, and \fIoverlay\fR.\& Using \fIoverlay\fR will cause notifications to be displayed above fullscreen windows, though this may also occur at \fItop\fR depending on your compositor.\& .PP Default: top .PP .RE \fBanchor\fR=\fIposition\fR .RS 4 Show notifications at the specified position on the output.\& Supported values are \fItop-right\fR, \fItop-center\fR, \fItop-left\fR, \fIbottom-right\fR, \fIbottom-center\fR, \fIbottom-left\fR, \fIcenter-right\fR, \fIcenter-left\fR and \fIcenter\fR.\& .PP Default: top-right .PP .RE .SH CRITERIA .PP In addition to the set of options at the top of the file, the config file may contain zero or more sections, each containing any combination of the \fBBINDING OPTIONS\fR and \fBSTYLE OPTIONS\fR.\& The sections, called criteria, are defined with an INI-like square bracket syntax.\& The brackets may contain any number of fields, like so: .PP .RS 4 [field=value field2=value2 .\&.\&.\&] .PP .RE When a notification is received, it will be compared to the fields defined in each criteria.\& If all of the fields match, the style options within will be applied to the notification.\& Fields not included in the criteria are not considered during the match.\& A notification may match any number of criteria.\& This matching occurs in the order the criteria are defined in the config file, meaning that if multiple criteria match a notification, the last occurrence of any given style option will "win".\& .PP The following fields are available in criteria: .PP .PD 0 .IP \(bu 4 \fIapp-name\fR (string) .IP \(bu 4 \fIapp-icon\fR (string) .IP \(bu 4 \fIsummary\fR (string): exact match on the summary of the notification.\& This field conflicts with \fIsummary~\fR.\& .IP \(bu 4 \fIsummary~\fR (string): a POSIX extended regular expression match on the summary of the notification.\& This field conflicts with \fIsummary\fR.\& .IP \(bu 4 \fIbody\fR (string): an exact match on the body of the notification.\& This field conflicts with \fIbody~\fR.\& .IP \(bu 4 \fIbody~\fR (string): a POSIX extended regular expression match on the body of the notification.\& This field conflicts with \fIbody\fR.\& .IP \(bu 4 \fIurgency\fR (one of "low", "normal", "critical") .IP \(bu 4 \fIcategory\fR (string) .IP \(bu 4 \fIdesktop-entry\fR (string) .IP \(bu 4 \fIactionable\fR (boolean) .IP \(bu 4 \fIexpiring\fR (boolean) .IP \(bu 4 \fImode\fR (string): only apply style options in this section if the provided mode is currently enabled.\& For more information about modes, see the \fIMODES\fR section.\& .PD .PP The following fields are also available to match on a second pass based on where previous style options decided to place each notification: .PP .PD 0 .IP \(bu 4 \fIgrouped\fR (boolean): whether the notification is grouped with any others.\& .IP \(bu 4 \fIgroup-index\fR (int): the notification'\&s index within its group, or -1 if it is not grouped.\& .IP \(bu 4 \fIhidden\fR (boolean): special field which defines the style for the placeholder shown when the number of notifications or groups exceeds \fImax-visible\fR.\& .IP \(bu 4 \fIoutput\fR (string): which output the notification was sorted onto.\& See the \fIoutput\fR style option for possible values.\& .IP \(bu 4 \fIanchor\fR (string): which position on the output the notification was assigned to.\& See the \fIanchor\fR style option for possible values.\& .PD .PP There are only two passes performed on each notification, so the second-pass criteria are not allowed to reposition the notification.\& .PP If a field'\&s value contains special characters, they may be escaped with a backslash, or quoted: .PP .RS 4 [app-name="Google Chrome"] .PP [app-name=Google\e Chrome] .PP .RE Quotes within quotes may also be escaped, and a literal backslash may be specified as \e\e.\& No spaces are allowed around the equal sign.\& Escaping equal signs within values is unnecessary.\& .PP Additionally, boolean values may be specified using any of true/false, 0/1, or as bare words: .PP .RS 4 [actionable=true] [actionable=1] [actionable] .PP [actionable=false] [actionable=0] [!\&actionable] .PP .RE There are three criteria always present at the front of the list: .PD 0 .IP \(bu 4 An empty criteria which matches all notifications and contains the defaults for all style options, overwritten with any configured in the global section.\& .IP \(bu 4 [grouped], which sets the default \fBformat\fR for grouped notifications and sets them \fBinvisible\fR.\& .IP \(bu 4 [group-index=0], which makes the first member of each group visible again.\& .PD .PP These options can be overridden by simply defining the criteria yourself and overriding them.\& .PP There are some rules restricting what can be configured depending on what is being matched by a given criteria.\& Criteria matching \fIgrouped\fR or \fIgroup-index\fR are not allowed to change the \fIanchor\fR, \fIoutput\fR, or \fIgroup-by\fR, as this would invalidate the grouping.\& Grouping is only performed once rather than recursively, to avoid the potential for infinite loops.\& .PP .SH CRITERIA-ONLY STYLE OPTIONS .PP Some style options are not useful in the global context and therefore have no associated command-line option.\& .PP \fBinvisible\fR=0|1 .RS 4 Whether this notification should be invisible even if it is above the \fImax-visible\fR cutoff.\& This is used primarily for hiding members of groups.\& If you want to make more than the first group member visible, turn this option off within a \fIgroup-index\fR criteria.\& .PP Default: 0 .PP .RE .SH COLORS .PP Colors can be specified as \fI#RRGGBB\fR or \fI#RRGGBBAA\fR.\& .PP .SH DIRECTIONAL VALUES .PP Some options set values that affect all four edges of a notification.\& These options can be specified in several different ways, depending on how much control over each edge is desired: .PP .PD 0 .IP \(bu 4 A single value will apply to all four edges.\& .IP \(bu 4 Two values will set vertical and horizontal edges separately.\& .IP \(bu 4 Three will set top, horizontal, and bottom edges separately.\& .IP \(bu 4 Four will set top, right, bottom, and left edges separately.\& .PD .PP When specifying multiple values, they should be comma-separated.\& For example, this would set the top margin to 10, left and right to 20, and bottom to five: .PP .nf .RS 4 margin = 10,20,5 .fi .RE .PP .SH FORMAT SPECIFIERS .PP Format specification works similarly to \fBprintf\fR(3), but with a different set of specifiers.\& .PP \fB%%\fR Literal "%" .PP \fB\e\e\fR Literal "\e" .PP \fB\en\fR New Line .PP .SS For notifications .PP \fB%a\fR Application name .PP \fB%s\fR Notification summary .PP \fB%b\fR Notification body .PP \fB%g\fR Number of notifications in the current group .PP \fB%i\fR Notification id .PP .SS For the hidden notifications placeholder .PP \fB%h\fR Number of hidden notifications .PP \fB%t\fR Total number of notifications .PP .SH MODES .PP mako supports applying style options conditionally via modes.\& A configuration section with a \fImode\fR criteria will only be applied if the current mode matches.\& \fB\fRmakoctl\fB\fR(1) can be used to change the current mode.\& .PP The initial list of modes contains a single mode called "default".\& This is deprecated, in a future version the initial list of modes will be empty.\& .PP For example, to hide all notifications if the mode "do-not-disturb" is enabled: .PP .nf .RS 4 [mode=do-not-disturb] invisible=1 .fi .RE .PP \fImakoctl mode -a do-not-disturb\fR will hide all notifications, \fImakoctl mode -r do-not-disturb\fR will show them again.\& .PP .SH AUTHORS .PP Maintained by Simon Ser , who is assisted by other open-source contributors.\& For more information about mako development, see https://github.\&com/emersion/mako.\& .PP .SH SEE ALSO .PP \fBmako\fR(1) \fBmakoctl\fR(1)