Provide a configuration example file

[fauust]

Hi! This is not an issue.

I can't find any configuration example in the documentation.

I think that for easier adoption, it would be very good to provide such a configuration example (or pointer to mako users dotfiles maybe?).

[fluix-dev]

If you're looking for an example yourself, here you go. An example config would be nice though, I agree.

[fauust]

Thanks! I'll take a look at your dotfiles.

[markstos]

Here's a more minimal example:

font=JetBrains Mono 18
width=600
height=300
border-radius=8
# Putting notifications at the bottom conflicts with typing in editors/chat
# It's not as critical to cover a top corner.
anchor=top-right
default-timeout=10000

[markstos]

@fauust I presume you found man mako but did you find man 5 mako?

That's where all the config keys are documented.

The man page documentation format is ancient and not intuitive, but as seen in man man, "section 5" is for "file formats", while man mako loads the documentation from the section 1 man page for "executable programs".

man mako mentions mako(5) in SEE ALSO, but that's only helpful if you know that notation means. The SEE ALSO section might be more user friendly if more explicity said:

* `man 5 mako` # File file format documentation.
* `man makoctl` # Sends IPC commands to running mako daemon via dbus.

[fauust]

@fauust I presume you found man mako but did you find man 5 mako?

Of course and I really like that all these projects use extensively man for documentation!

What is missing for me, is a very basic example (maybe in the man). For instance, it was not clear for me, even reading the man 5 mako if you need to define a [global] section.

I would also add to your minimal example something like:

[urgency=critical]
default-timeout=0
background-color=#ff0000
border-color=#000000
text-color=#000000

[category=mpd]
default-timeout=2000
group-by=category

Just to show how sections should be used.

[apiraino]

Examples are important as much as a good documentation, so I took the liberty to do some copy&paste on the wiki from this issue and provide a configuration example to get started. It's not so pretty so feel free to improve it.

[S1SYPHOS]

I think providing a blank file with all options and some comments would be a good starting point, like

# ...
# Progress indicator color
# progress-color <color>

# Show icons in notifications
# icons <0|1>

# Icon search path, colon delimited
# icon-path <path>[:<path>]

# Set max size of icons
# max-icon-size <px>

# Enable/disable markup
# markup <0|1>

# Enable/disable application action execution
# actions <0|1>

# Format string
# format <format>

# Format string
# hidden-format <format>

# Max number of visible notifications
# max-visible <n>

# Sorts incoming notifications by time
# and/or priority in ascending(+) or
# descending(-) order
# sort <sort_criteria>

# Enable/disable notification timeout
# ignore-timeout <0|1>

# Show notifications on this output
# output <name>

# Arrange notifications at this layer
# layer <layer>

[fauust]

Why not but this information is already in the man pages so this could be redundant (and thus not easy to maintain)...
That's why I am more in favor of a very basic example config file. Or maybe having this config file example automatically generated from the man page then?

[apiraino]

Why not but this information is already in the man pages so this could be redundant (and thus not easy to maintain)...
That's why I am more in favor of a very basic example config file. Or maybe having this config file example automatically generated from the man page then?

my 2 cents on this feature request (as a mako user, not a contributor).

Given how mako currently loads a default configuration (by hardcoding values in the code), I feel that duplicating a default config generator in another place would be slightly problematic if one day defaults change (as @fauust points out)

So, in my opinion, either:

1. a "community-maintained" suggested default config (which we now already have in the wiki), or
2. submit for evaluation to the maintainer a patch that dumps the default config (e.g. mako --dump-config > ~/.config/mako/config)

[fauust]

1. a "community-maintained" suggested default config (which we now already have in the wiki), or

I didn't saw this update on the wiki, so this is perfectly sufficient IMO, I will be happy to close this issue if you agree with the wiki solution.

[S1SYPHOS]

I must say, i really dig the second option, but if that's too much trouble .. I like dumping a config file with all there is (up to this particular point) and then customize it, but that's just me ;)

[emersion]

What I really don't want to see is a very big default config file with a ton of comments and all supported options specified. This just makes it very hard to figure out which parts you've customized. The documentation is the man page.

The defaults are hard-coded in mako itself, and I agree this may not be the best option. While this makes it so mako doesn't hard-depend on a default system file, this makes it more difficult for users to start from scratch. In retrospect, maybe going the Sway way and falling back to /etc/mako/config if the user doesn't have a config file would be better.

However that would be a breaking change for our users. I'm not a fan of loading both the system-wide config file and the user-specific config file.

[vilhalmer]

Not having any internal defaults would also force the user config file to be exhaustive, because generating the style for a notification relies on having every value set to something after applying all the criteria. So we'd either have to fall back to the global config as you mentioned, or still have internal defaults anyway.

Having a way of dumping out the defaults as a basic config file seems pretty reasonable to me, I would be +1 on a PR for that. The maintenance cost isn't zero but should be fairly low since the config format is pretty simple and we don't add new style options very often.

[vilhalmer]

All that said, the man page really should be sufficient documentation to get started. If it isn't, we should improve it. I have a feeling the criteria section could use a revamp, but if there's anything that people have found unclear about the basic options as well, please help us improve! Improving the text to clarify that there is no [global] is a really cheap fix versus writing more code to dump out a config file. ;)