docs(man): backfill man pages with wiki-only info (source-of-truth pass)

Port information that previously lived only in the GitHub wiki into the
authoritative scdoc man pages, so the man pages become the single source
of truth for module documentation.

33 man pages enriched (options, format replacements, actions, style
selectors, troubleshooting and implementation notes). Additions were
verified against the source; stale/incorrect wiki entries were
deliberately not ported. All pages still compile with scdoc.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

man/waybar-backlight-slider.5.scd

@@ -41,6 +41,17 @@ The brightness can be controlled by dragging the slider across the bar or clicki
 	default: false ++
 	Enables this module to consume all left over space dynamically.
 
+*Note*: As well as the JSON configuration, the slider modules are special in
+that they *require* styling to work. You *need* to set *min-width* and/or
+*min-height* (depending on whether your slider is vertical or not) for it to
+display correctly. That is a GTK detail, not an issue with Waybar. See the
+*STYLE* section below.
+
+*Warning*: If *min* is set to *0* (default), the slider can set brightness to
+*0*, which may completely disable the backlight on some devices, making the
+screen fully black. Consider setting a small minimum value (e.g. *10*) or
+configuring brightness keybinds as a fallback.
+
 # EXAMPLES
 
 ```

man/waybar-backlight.5.scd

@@ -78,7 +78,13 @@ The *backlight* module displays the current backlight level.
 
 *reverse-scrolling*: ++
 	typeof: bool ++
-	Option to reverse the scroll direction.
+	default: false ++
+	Option to reverse the scroll direction for devices other than a mouse (touchpad, trackpad, etc).
+
+*reverse-mouse-scrolling*: ++
+	typeof: bool ++
+	default: false ++
+	Option to reverse the scroll direction for mice.
 
 *scroll-step*: ++
 	typeof: float ++
@@ -90,6 +96,15 @@ The *backlight* module displays the current backlight level.
 	default: 0.0 ++
 	The minimum brightness of the backlight.
 
+*tooltip*: ++
+	typeof: bool ++
+	default: true ++
+	Option to disable tooltip on hover.
+
+*tooltip-format*: ++
+	typeof: string ++
+	Text to be displayed in the tooltip.
+
 *menu*: ++
 	typeof: string ++
 	Action that popups the menu.

man/waybar-battery.5.scd

@@ -124,6 +124,11 @@ The *battery* module displays the current capacity and state (eg. charging) of y
 	default: true ++
 	Option to disable tooltip on hover.
 
+*tooltip-format*: ++
+	typeof: string ++
+	default: {timeTo} ++
+	The tooltip format. See *CUSTOM FORMATS* for status/state-specific variants.
+
 *bat-compatibility*: ++
 	typeof: bool ++
 	default: false ++
@@ -165,6 +170,12 @@ The *battery* module displays the current capacity and state (eg. charging) of y
 
 *{health}*: The percentage of the highest-capacity battery's original maximum charge it can still hold.
 
+The following additional replacement is available in *tooltip-format* (and its
+custom variants) only:
+
+*{timeTo}*: Either an estimate of time until full or empty, or "Full", "Plugged"
+or "Empty" depending on the current battery status.
+
 # TIME FORMAT
 
 The *battery* module allows you to define how time should be formatted via *format-time*.
@@ -184,6 +195,11 @@ The *battery* module allows one to define custom formats based on up to two fact
 
 *format-<status>-<state>*: You can also set a custom format depending on both values.
 
+The tooltip format can be customized the same way. The best fitting from
+*tooltip-format*, *tooltip-format-<state>*, *tooltip-format-<status>* and
+*tooltip-format-<status>-<state>* will be used (using the same logic as
+*format-\**).
+
 # STATES
 
 - Every entry (*state*) consists of a *<name>* (typeof: *string*) and a *<value>* (typeof: *integer*).
@@ -229,6 +245,20 @@ Where:
 }
 ```
 
+Custom icon set depending on the status (*format-icons* as an object):
+
+```
+"battery": {
+	"bat": "BAT2",
+	"interval": 60,
+	"format": "{capacity}% {icon}",
+	"format-icons": {
+		"default": ["󰂎", "󰁺", "󰁻", "󰁼", "󰁽", "󰁾", "󰁿", "󰂀", "󰂁", "󰂂", "󰁹"],
+		"charging": ["󰢟", "󰢜", "󰂆", "󰂇", "󰂈", "󰢝", "󰂉", "󰢞", "󰂊", "󰂋", "󰂅"]
+	}
+}
+```
+
 # STYLE
 
 - *#battery*

man/waybar-cava.5.scd

@@ -216,7 +216,12 @@ Configuration can be provided as:
 # SOLVING ISSUES
 
 . On start Waybar throws an exception "error while loading shared libraries: libcava.so: cannot open shared object file: No such file or directory".
-  It might happen when libcava for some reason hasn't been registered in the system. sudo ldconfig should help
+  It might happen when libcava for some reason hasn't been registered in the system. sudo ldconfig should help.
+  It might also happen when Waybar was installed into /usr/local while libcava lives elsewhere. In that case:
+   1. Drop the local cava library: sudo rm -rfv /usr/local/include/cava /usr/local/lib64/pkgconfig/cava.pc /usr/local/lib64/libcava.so
+   2. Set the prefix where Waybar should be installed: meson configure build -Dprefix="/usr"
+   3. Build Waybar: make
+   4. Install Waybar into the system: sudo meson install -C build
 . Waybar is starting but cava module doesn't react to the music
    1. In such cases at first need to make sure usual cava application is working as well
    2. If so, need to comment all configuration options. Uncomment cava_config and provide the path to the working cava config

man/waybar-cffi.5.scd

@@ -37,6 +37,19 @@ Waybar config to enable the module:
 ```
 
 
+# DEVELOPING CFFI MODULES
+
+CFFI modules require a handful of functions and constants to be defined with C
+linkage. The way to achieve this depends on the programming language being used
+(search for FFI / Foreign Function Interface for that language).
+
+The complete list of symbols to define can be found in the header file shipped with
+Waybar at *resources/custom_modules/cffi_example/waybar_cffi_module.h*, and a full
+example written in C is provided in *resources/custom_modules/cffi_example/*.
+
+Language bindings exist for several languages, including Rust (the *waybar-cffi*
+crate) and Zig.
+
 # STYLE
 
 The classes and IDs are managed by the cffi dynamic library.

man/waybar-clock.5.scd

@@ -6,7 +6,16 @@ waybar - clock module
 
 # DESCRIPTION
 
-*clock* module displays current date and time
+*clock* module displays current date and time.
+
+There are two implementations:
+
+- *clock*: Full-featured implementation, including the calendar and timezone
+  support described below. Enabled at build time when either C++20 concepts
+  (\_\_cpp\_concepts >= 201907, gcc >= 13) are available, or the HowardHinnant date
+  library <https://github.com/HowardHinnant/date> is installed.
+- *simpleclock*: Fallback that provides date and time display only. Used when the
+  above build conditions are not met.
 
 # FILES
 
@@ -27,7 +36,8 @@ $XDG_CONFIG_HOME/waybar/config ++
 |[ *format*
 :[ string
 :[ *{:%H:%M}*
-:[ The format, how the date and time should be displayed. See format options below
+:[ The format, how the date and time should be displayed. See format options
+   below. Split the braces to insert literal text, e.g. *{0:%H}text{0:%M}*
 |[ *timezone*
 :[ string
 :[
@@ -295,6 +305,11 @@ View all valid format options in *strftime(3)* or have a look https://en.cpprefe
 
 - *#clock*
 
+If displaying seconds causes other modules to shift side to side, the cause is
+usually proportional-width digits. If your font supports it, add
+*font-feature-settings: "tnum";* to the *#clock* style (or wherever you set the bar
+font) to use fixed-width numbers.
+
 The following classes are used only inside the *{calendar}* tooltip. Their
 foreground *color* is read and applied to the corresponding calendar cells in
 the tooltip markup:
@@ -313,6 +328,10 @@ name not valid error message try one of the following:
 - check if LC_TIME is set properly (glibc)
 - set locale to C in the config file (musl)
 
+When using *clock* instead of *simpleclock*, the locale defaults to *C* regardless
+of the locale settings. To override this, prepend *L* to the format string, e.g.
+*{:%a %m %d}* becomes *{:L%a %m %d}*.
+
 The locale option must be set for {calendar} to use the correct start-of-week, regardless of system locale.
 
 ## Calendar in Chinese. Alignment

man/waybar-custom.5.scd

@@ -61,8 +61,11 @@ Addressed by *custom/<name>*
 	The format, how information should be displayed. On {text} data gets inserted.
 
 *format-icons*: ++
-	typeof: array ++
+	typeof: array or object or string ++
-	Based on the set percentage, the corresponding icon gets selected. The order is *low* to *high*.
+	If the type is an array, then based on the set percentage, the corresponding icon gets selected (the order is *low* to *high*). ++
+	If the type is an object, then the icon is selected according to the *alt* string from the output. ++
+	If the type is a string, it is pasted as is. ++
+	Arrays can be nested into objects: icons are then selected first according to *alt*, then percentage.
 
 *rotate*: ++
 	typeof: integer ++
@@ -163,11 +166,18 @@ When *return-type* is set to *json*, Waybar expects the *exec*-script  to output
 This should look like this:
 
 ```
-{"text": "$text", "tooltip": "$tooltip", "class": "$class", "percentage": $percentage }
+{"text": "$text", "alt": "$alt", "tooltip": "$tooltip", "class": "$class", "percentage": $percentage }
 ```
 
+The whole JSON object must be printed on a single line. This can be achieved by
+piping the output of your script through *jq --unbuffered --compact-output*.
+
 The *class* parameter also accepts an array of strings.
 
+To have multiline tooltips, use *\\r* in your script to separate the lines. If
+using PowerShell for scripting, use the standard newline operator "\`n" in double
+quotes; *\\r* and *\\n* will not work.
+
 If nothing or an invalid option is specified, Waybar expects i3blocks style output. Values are *newline* separated.
 This should look like this:
 
@@ -179,6 +189,8 @@ $text\\n$tooltip\\n$class*
 
 # FORMAT REPLACEMENTS
 
+*{}*: Output of the script. Equivalent to *{text}*.
+
 *{text}*: Output of the script.
 
 *{alt}*: The *alt* value from a json return type.
@@ -187,6 +199,11 @@ $text\\n$tooltip\\n$class*
 
 *{icon}*: An icon from 'format-icons' according to percentage.
 
+The *{}* placeholder is special: it automatically displays the text output of your
+script, but it cannot be combined with other placeholders like *{icon}* in the same
+format string. To display both an icon and text, use *{icon}* together with *{text}*
+explicitly (e.g. *"format": "{icon} {text}"*).
+
 # EXAMPLES
 
 ## Spotify:
@@ -264,3 +281,34 @@ Under the premise that interval is not defined, you can use the signal and updat
 - *<class>* can be set by the script. For more information see *return-type*
 - *.flat* and *.text-button* are always applied to the module's label.
 - *.image-button* is always applied to the module's image (see *image-path*/*image-name*).
+
+# CONTINUOUS SCRIPTS
+
+The *exec* script may be continuous (i.e. contain some kind of infinite loop). The
+display is updated for each new line of data printed on stdout (following the chosen
+*return-type*). The *interval* option does not apply to a continuous script; use
+*restart-interval* instead to restart the script if it stops after some time.
+
+Be aware that some languages buffer their output. If your module displays nothing
+even though your script works as expected, the output may be held in a buffer. Look
+up how to flush the output buffer for your language of choice (for example, in Ruby
+call *$stdout.flush* after each print).
+
+# OUTPUT NAME
+
+The *exec* script is run with the *WAYBAR_OUTPUT_NAME* environment variable set to
+the name of the output (monitor) the bar is displayed on.
+
+# TROUBLESHOOTING
+
+*Self-looping module does not show up*
+
+If your module is self-looping and it does not even show up in the bar, check that:
+
+- Its configuration does *not* include an *interval* parameter.
+- Output to stdout is not buffered.
+
+*Custom json class not displayed*
+
+If a class set in your custom script is not picked up by *style.css*, ensure that
+the output carrying the most variables is emitted first.

man/waybar-dwl-tags.5.scd

@@ -8,6 +8,9 @@ waybar - dwl tags module
 
 The *tags* module displays the current state of tags in dwl.
 
+Using this module requires patching dwl with the IPC patch
+<https://codeberg.org/dwl/dwl-patches/wiki/ipc>.
+
 # CONFIGURATION
 
 Addressed by *dwl/tags*
@@ -15,7 +18,8 @@ Addressed by *dwl/tags*
 *num-tags*: ++
 	typeof: uint ++
 	default: 9 ++
-	The number of tags that should be displayed. Max 32.
+	The number of tags that should be displayed. Max 32. This should match the
+	number of tags configured in dwl.
 
 *tag-labels*: ++
 	typeof: array ++

man/waybar-dwl-window.5.scd

@@ -8,6 +8,9 @@ waybar - dwl window module
 
 The *window* module displays the title of the currently focused window in DWL
 
+Using this module requires patching dwl with the IPC patch
+<https://codeberg.org/dwl/dwl-patches/wiki/ipc>.
+
 # CONFIGURATION
 
 Addressed by *dwl/window*

man/waybar-ext-workspaces.5.scd

@@ -8,6 +8,9 @@ waybar - wlr workspaces module
 
 The *workspaces* module displays the currently used workspaces in wayland compositor.
 
+To use this module, your compositor must implement the *ext-workspace-v1*
+Wayland protocol.
+
 # CONFIGURATION
 
 Addressed by *ext/workspaces*

man/waybar-gamemode.5.scd

@@ -54,7 +54,7 @@ Feral Gamemode optimizations.
 *icon-size*: ++
 	typeof: unsigned integer ++
 	default: 20 ++
-	Defines the size of the icons.
+	Defines the size of the icons. Set to *0* for auto size.
 
 *icon-spacing*: ++
 	typeof: unsigned integer ++

man/waybar-hyprland-window.5.scd

@@ -17,6 +17,10 @@ Addressed by *hyprland/window*
 	default: {title} ++
 	The format, how information should be displayed. On {} the current window title is displayed.
 
+*max-length*: ++
+	typeof: integer ++
+	The maximum length in character the module should display.
+
 *rewrite*: ++
 	typeof: object ++
 	Rules to rewrite window title. See *rewrite rules*.

man/waybar-hyprland-workspaces.5.scd

@@ -139,7 +139,8 @@ This setting is ignored if *workspace-taskbar.enable* is set to true.
 *persistent-workspaces*: ++
 	typeof: object ++
 	default: empty ++
-	Lists workspaces that should always be shown, even when they do not exist. Keys are workspace names and values are arrays of output names on which the workspace should be shown (an empty array means all outputs). See the examples below.
+	Lists workspaces that should always be shown, even when they do not exist. Keys are workspace names and values are arrays of output names on which the workspace should be shown (an empty array means all outputs). See the examples below. ++
+	Note: for persistent workspaces to actually work you must also declare them in your Hyprland config, e.g. *workspace = 1, monitor:eDP-1, persistent:true*.
 
 *all-outputs*: ++
 	typeof: bool ++
@@ -219,6 +220,32 @@ This setting is ignored if *workspace-taskbar.enable* is set to true.
 
 *{windows}*: The windows in the workspace, formatted according to *window-rewrite* and joined with *format-window-separator*.
 
+# WINDOW REWRITE RULES
+
+The rules in *window-rewrite* are regexes that may match against a window's
+class, title, or both. There are four categories of rule, distinguished by how
+they are written in the config:
+
+[- *Rule*
+:- *Category*
+|[ *something*
+:[ Vague
+|[ *class<something>*
+:[ Class-only
+|[ *title<something>*
+:[ Title-only
+|[ *class<something1> title<something2>*
+:[ Hybrid
+
+When the config contains only "vague" rules, they are matched against window
+*classes* only. This is both for backwards compatibility and for performance:
+matching against the title requires listening to window title changes via
+Hyprland's IPC, which is unnecessary when no title rule is in use.
+
+When the config contains *at least one* "title-only" or "hybrid" rule, then all
+"vague" rules match against *both* class and title. This lets you define vague
+rules where it does not matter whether the class or the title matched.
+
 # ICONS
 
 Additional to workspace name matching, the following *format-icons* can be set.
@@ -229,6 +256,7 @@ Additional to workspace name matching, the following *format-icons* can be set.
 - *empty*: Will be shown on non-active, non-special empty persistent workspaces
 - *visible*: Will be shown on workspaces that are visible but not active. For example: this is useful if you want your visible workspaces on other monitors to have the same look as active.
 - *persistent*: Will be shown on non-empty persistent workspaces
+- *urgent*: Will be shown on non-active urgent workspaces
 
 # EXAMPLES
 

man/waybar-image.5.scd

@@ -100,6 +100,29 @@ $path\\n$tooltip
 }
 ```
 
+Using *exec* to fetch the image via a script:
+
+```
+"image#album-art": {
+	"exec": "~/.config/waybar/custom/spotify/album_art.sh",
+	"size": 32,
+	"interval": 30
+}
+```
+
+Where *album\_art.sh* looks like this:
+
+```
+#!/bin/bash
+album_art=$(playerctl -p spotify metadata mpris:artUrl)
+if [[ -z $album_art ]]; then
+	# spotify is dead, we should die too.
+	exit
+fi
+curl -s "${album_art}" --output "/tmp/cover.jpeg"
+echo "/tmp/cover.jpeg"
+```
+
 # STYLE
 
 - *#image*

man/waybar-jack.5.scd

@@ -6,7 +6,13 @@ waybar - JACK module
 
 # DESCRIPTION
 
-The *jack* module displays the current state of the JACK server.
+The *jack* module displays the current state of the JACK server. It supports both
+the JACK2 <https://github.com/jackaudio/jack2> and PipeWire <https://pipewire.org/>
+implementations of the JACK API.
+
+PipeWire users are advised to run at least v0.3.57; earlier versions cause the
+Waybar client to hang indefinitely if the server shuts down while the module is
+running.
 
 # CONFIGURATION
 

man/waybar-keyboard-state.5.scd

@@ -8,7 +8,8 @@ waybar - keyboard-state module
 
 The *keyboard-state* module displays the state of number lock, caps lock, and scroll lock.
 
-You must be a member of the input group to use this module.
+You must be a member of the input group to use this module. Add yourself with
+*usermod -a -G input <username>* (as root), then reboot.
 
 # CONFIGURATION
 

man/waybar-memory.5.scd

@@ -84,6 +84,11 @@ Addressed by *memory*
 	default: true ++
 	Option to disable tooltip on hover.
 
+*tooltip-format*: ++
+	typeof: string ++
+	default: {used:0.1f}GiB used ++
+	The format of the tooltip shown on hover. Supports the same replacements as *format*.
+
 *menu*: ++
 	typeof: string ++
 	Action that popups the menu.

man/waybar-mpd.5.scd

@@ -8,17 +8,19 @@ waybar - mpd module
 
 The *mpd* module displays information about a running "Music Player Daemon" instance.
 
+Note that Waybar must be compiled with MPD support in order to use this module.
+
 # CONFIGURATION
 
 Addressed by *mpd*
 
 *server*: ++
 	typeof: string ++
-	The network address or Unix socket path of the MPD server. If empty, connect to the default host.
+	The network address or Unix socket path of the MPD server. If empty, connect to the default host (`MPD_HOST`).
 
 *port*: ++
 	typeof: integer ++
-	The port MPD listens to. If empty, use the default port.
+	The port MPD listens to. If empty, use the default port (`MPD_PORT`).
 
 *password*: ++
 	typeof: string ++

man/waybar-network.5.scd

@@ -56,6 +56,10 @@ Addressed by *network*
 	typeof: string ++
 	This format is used when rfkill is blocking wlan interfaces.
 
+*format-alt*: ++
+	typeof: string ++
+	On click, toggle between this format and the regular format. The click button is set with *format-alt-click* (defaults to the left button).
+
 *format-icons*: ++
 	typeof: array/object ++
 	Based on the current signal strength, the corresponding icon gets selected. ++

man/waybar-power-profiles-daemon.5.scd

@@ -44,6 +44,18 @@ $XDG_CONFIG_HOME/waybar/config
 
 
 
+# FORMAT REPLACEMENTS
+
+*{profile}*: Active profile full name.
+
+*{icon}*: Icon (from *format-icons*) representing the active profile.
+
+*{cpu_driver}*: The CPU driver reported by recent power-profiles-daemon versions. *(tooltip)*
+
+*{platform_driver}*: The platform driver reported by recent power-profiles-daemon versions. *(tooltip)*
+
+*{driver}*: Kept for backward compatibility: resolves to the legacy single driver on older daemons and falls back to the CPU driver on recent ones. *(tooltip)*
+
 # CONFIGURATION EXAMPLES
 
 Compact display (default config):

man/waybar-privacy.5.scd

@@ -19,7 +19,7 @@ the screen or playing audio.
 *icon-size*: ++
 	typeof: integer ++
 	default: 20 ++
-	The size of each privacy icon.
+	The size of each privacy icon. Set to *0* for auto size.
 
 *transition-duration*: ++
 	typeof: integer ++
@@ -57,7 +57,8 @@ the screen or playing audio.
 
 *icon-name*: ++
 	typeof: string ++
-	If set, changes the modules icon.
+	If set, changes the modules icon. Accepts any valid GTK icon name. ++
+	Note: the icon is only visible when the resource is actively in use; the item is hidden when idle.
 
 *tooltip*: ++
 	typeof: bool ++

man/waybar-pulseaudio-slider.5.scd

@@ -87,6 +87,12 @@ The volume can be controlled by dragging the slider across the bar or clicking o
 
 # STYLE
 
+Unlike most modules, the slider modules *require* styling to display correctly.
+In particular you *need* to set *min-width* and/or *min-height* (depending on
+whether the slider is vertical or horizontal) on the *trough* node, otherwise
+the slider renders too small to be usable. This is a GTK detail, not a Waybar
+issue.
+
 The slider is a component with multiple CSS Nodes, of which the following are exposed:
 
 *#pulseaudio-slider*: ++

man/waybar-pulseaudio.5.scd

@@ -108,6 +108,10 @@ Additionally, you can control the volume by scrolling *up* or *down* while the c
 	default: true ++
 	Option to disable tooltip on hover.
 
+*tooltip-format*: ++
+	typeof: string ++
+	The format of the tooltip shown on hover. When unset, the tooltip shows the current sink's description.
+
 *max-volume*: ++
 	typeof: integer ++
 	default: 100 ++
@@ -115,7 +119,7 @@ Additionally, you can control the volume by scrolling *up* or *down* while the c
 
 *ignored-sinks*: ++
 	typeof: array ++
-	Sinks in this list will not be shown as active sink by Waybar. Entries should be the sink's description field.
+	Sinks in this list will not be shown as active sink by Waybar. Entries should be the sink's description field. Use *pactl list sinks* to find the correct description.
 
 *sink-mapping*: ++
 	typeof: object ++
@@ -164,6 +168,8 @@ The following strings for *format-icons* are supported.
 
 - the device name
 
+The device name looks something like *alsa\_output.pci-0000\_00\_1f.3.analog-stereo*. You can find it with a PulseAudio frontend such as *pacmd list-sinks* or *pamixer --list-sinks*.
+
 If they are found in the current PulseAudio port name, the corresponding icons will be selected.
 
 - *default* (Shown, when no other port is found)

man/waybar-river-tags.5.scd

@@ -52,6 +52,23 @@ Addressed by *river/tags*
 }
 ```
 
+Sticky tag: this enables 5 tags and, to support a sticky tag (tag 32),
+*set-tags* is given bitmasks with the 32nd bit set so that tag stays selected
+whichever button is clicked.
+
+```
+"river/tags": {
+	"num-tags": 5,
+	"set-tags": [
+		2147483649,
+		2147483650,
+		2147483652,
+		2147483656,
+		2147483664
+	]
+}
+```
+
 # STYLE
 
 - *#tags button*

man/waybar-river-window.5.scd

@@ -49,6 +49,11 @@ Addressed by *river/window*
 	typeof: string ++
 	Command to execute when you right-click on the module.
 
+*tooltip*: ++
+	typeof: bool ++
+	default: true ++
+	Option to enable tooltip on hover. The tooltip shows the same text as the module label.
+
 *menu*: ++
 	typeof: string ++
 	Action that popups the menu.

man/waybar-states.5.scd

@@ -14,7 +14,7 @@ apply a class when the value matches the declared state value.
 Every entry (*state*) consists of a *<name>* (typeof: *string*) and a *<value>* (typeof: *integer*).
 
 - The state can be addressed as a CSS class in the *style.css*. The name of the CSS class is the *<name>* of the state.
-  Each class gets activated when the current value is equal to or less than the configured *<value>* for the *battery* module, or equal to or greater than the configured *<value>* for all other modules.
+  Each class gets activated when the current value is equal to or less than the configured *<value>* for the *battery*, *pulseaudio* and *wireplumber* modules, or equal to or greater than the configured *<value>* for all other modules.
 
 - Also, each state can have its own *format*.
   Those can be configured via *format-<name>*, or if you want to differentiate a bit more, as *format-<status>-<state>*.

man/waybar-sway-language.5.scd

@@ -32,6 +32,18 @@ Addressed by *sway/language*
 	default: true ++
 	Option to disable tooltip on hover.
 
+*on-click*: ++
+	typeof: string ++
+	Command to execute when clicked on the module.
+
+*on-click-middle*: ++
+	typeof: string ++
+	Command to execute when you middle clicked on the module using mousewheel.
+
+*on-click-right*: ++
+	typeof: string ++
+	Command to execute when you right clicked on the module.
+
 *menu*: ++
 	typeof: string ++
 	Action that popups the menu.
@@ -67,6 +79,7 @@ Addressed by *sway/language*
 ```
 "sway/language": {
 	"format": "{}",
+	"on-click": "swaymsg input type:keyboard xkb_switch_layout next",
 },
 
 "sway/language": {

man/waybar-sway-window.5.scd

@@ -173,3 +173,11 @@ window widget:
 - *window#waybar.tabbed* When there is more than one window in the workspace and the workspace layout is tabbed
 - *window#waybar.tiled* When there is more than one window in the workspace and the workspace layout is splith or splitv
 - *window#waybar.<app_id>* Where *app_id* is the app_id or *instance* name like (*chromium*) of the only window in the workspace
+
+These additional classes are applied to the whole Waybar (an element with the
+name *window* and the id *waybar*) rather than to the module widget itself (an
+element with the name *box* and the id *window*). In most cases you therefore
+want to target *window#waybar.<stylename> #window* to style the module.
+
+Switching layouts does not change the style unless the focus is changed. Sway
+does not provide events for layout switching and the module does not poll.

man/waybar-temperature.5.scd

@@ -156,6 +156,8 @@ Addressed by *temperature*
 
 *{temperatureK}*: Temperature in Kelvin.
 
+*{icon}*: Icon, as selected from *format-icons* based on the current temperature.
+
 # EXAMPLES
 
 ```
@@ -173,3 +175,24 @@ Addressed by *temperature*
 - *#temperature*
 - *#temperature.warning*
 - *#temperature.critical*
+
+# TROUBLESHOOTING
+
+## Finding your thermal zone
+
+To list all the thermal zone types, run:
+
+```
+for i in /sys/class/thermal/thermal_zone*; do echo "$i: $(<$i/type)"; done
+```
+
+## Finding an hwmon path
+
+If you do not have a thermal zone, use *sensors* to find the preferred
+temperature source, then run:
+
+```
+for i in /sys/class/hwmon/hwmon*/temp*_input; do echo "$(<$(dirname $i)/name): $(cat ${i%_*}_label 2>/dev/null || echo $(basename ${i%_*})) $(readlink -f $i)"; done
+```
+
+to find the path to the desired file, then set it in *hwmon-path*.

man/waybar-tray.5.scd

@@ -55,6 +55,9 @@ Addressed by *tray*
 	Key: name of item. ++
 	Value: integer, higher value means to place this item to the right.
 
+Note: custom *icons* only work with actual image files, not font-based icons. They
+might not work for some Electron apps (see https://github.com/electron/electron/issues/40936).
+
 *ignore-list*: ++
 	typeof: array ++
 	List of strings used to hide matching tray items. An item is hidden when any string in the list is found (as a substring) in the item's bus name, category, icon name, id or title.
@@ -80,6 +83,20 @@ Addressed by *tray*
 # STYLE
 
 - *#tray*
-- *#tray > .passive*
+- *#tray menu* for the context menu
-- *#tray > .active*
+- *#tray widget>image* for icons
-- *#tray > .needs-attention*
+- *#tray > .passive* for icons with status *Passive*
+- *#tray > .active* for icons with status *Active*
+- *#tray > .needs-attention* for icons with status *NeedsAttention*
+
+# TRAY APPLETS
+
+The following applets are known to work with the *tray* module:
+
+- *NetworkManager*: install networkmanager, enable it with
+  *systemctl enable NetworkManager.service*, and start the applet with
+  *nm-applet --indicator*.
+- *Blueman*: enable the Bluetooth daemon, install blueman, and start
+  *blueman-applet*.
+- *Electron apps*: apps like Slack, Telegram, Caprine and Discord should work
+  out of the box.

man/waybar-upower.5.scd

@@ -26,7 +26,7 @@ compatible devices in the tooltip.
 *icon-size*: ++
 	typeof: integer ++
 	default: 20 ++
-	Defines the size of the icons.
+	Defines the size of the icons. Set to *0* for automatic sizing.
 
 *format*: ++
 	typeof: string ++

man/waybar-wireplumber.5.scd

@@ -36,6 +36,10 @@ The *wireplumber* module displays the current volume reported by WirePlumber.
 	typeof: string ++
 	The format used for the *{format_source}* sub-string when the source (microphone) is muted.
 
+*format-icons*: ++
+	typeof: array ++
+	Based on the current volume, the corresponding icon gets selected. The order is *low* to *high*.
+
 *node-type*: ++
 	typeof: string ++
 	default: *Audio/Sink* ++
@@ -90,6 +94,14 @@ The *wireplumber* module displays the current volume reported by WirePlumber.
 	default: cubic_percent
 	The scale to use for the scrolling volume change. Options are 'linear', 'db', 'cubic', and 'cubic_percent'.
 
+*reverse-scrolling*: ++
+	typeof: bool ++
+	Option to reverse the scroll direction for touchpads.
+
+*reverse-mouse-scrolling*: ++
+	typeof: bool ++
+	Option to reverse the scroll direction for mice.
+
 *on-click*: ++
 	typeof: string ++
 	Command to execute when clicked on the module.
@@ -142,6 +154,8 @@ The *wireplumber* module displays the current volume reported by WirePlumber.
 
 *{volume_db}*: Volume in decibel scale as float.
 
+*{icon}*: Icon, as defined in *format-icons*.
+
 *{node_name}*: The node's nickname as reported by WirePlumber (*node.nick* property)
 
 *{source_volume}*: Source (microphone) volume in percentage, cubic scale as integer.

man/waybar-wlr-taskbar.5.scd

@@ -135,6 +135,11 @@ Addressed by *wlr/taskbar*
 
 *{short_state}*: The state (minimize == m, maximized == M, active == A, fullscreen == F) represented as one character of the application.
 
+As with all format replacements in Waybar, a length limit such as *{title:.15}* is
+measured in bytes, not characters. This may produce invalid text if a multi-byte
+character is split, or (when *markup* is true) if the truncation cuts through a
+value that must be escaped in XML.
+
 # CLICK ACTIONS
 
 *activate*: Bring the application into foreground.
@@ -157,6 +162,8 @@ captures of the expression.
 
 Regular expression and replacement follow ECMA-script rules.
 
+An expression must match the format output *fully* to trigger its replacement.
+
 If no expression matches, the format output is left unchanged.
 
 Invalid expressions (e.g., mismatched parentheses) are skipped.