Zander671/Waybar
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: revamp README and add contributor docs

Browse Source 
- README: quick-links bar, compositor-support table, module list grouped by
  theme with links to the wiki, getting-started section, collapsible
  dependency blocks, updated badges (CI, release), and a note that module
  docs live in man/ (auto-synced to the wiki)
- add CONTRIBUTING.md (dev build, code style, docs workflow, PR checklist)
- add issue templates (bug report, feature request) and a PR template

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Alex
2026-07-04 13:06:47 +02:00
co-authored by Claude Opus 4.8
parent 6d3656a4a8
commit 54db6642ce
5 changed files with 216 additions and 123 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/ISSUE_TEMPLATE/bug_report.md
+37
View File
@@ -0,0 +1,37 @@
---
name: Bug report
about: Report a problem with Waybar
title: ''
labels: bug
assignees: ''
---
**Describe the bug**
A clear and concise description of what the bug is.
**To reproduce**
Steps to reproduce the behaviour, including a minimal config that triggers it:
```jsonc
// minimal config
```
**Expected behaviour**
What you expected to happen.
**Screenshots**
If applicable, add screenshots to help explain the problem.
**Environment**
- Waybar version (`waybar --version`):
- Installed from (distro package / source / other):
- Compositor and version (Sway, Hyprland, River, …):
**Debug output**
Run `waybar -l debug` and paste any relevant output:
```
```
**Additional context**
Anything else that might help.
.github/ISSUE_TEMPLATE/feature_request.md
+19
View File
@@ -0,0 +1,19 @@
---
name: Feature request
about: Suggest an idea or improvement for Waybar
title: ''
labels: enhancement
assignees: ''
---
**Is your feature request related to a problem?**
A clear and concise description of the problem, e.g. "I'm frustrated when […]".
**Describe the solution you'd like**
What you want to happen.
**Describe alternatives you've considered**
Any alternative solutions or features you've thought about.
**Additional context**
Which module does this concern? Add any other context or mockups here.
.github/PULL_REQUEST_TEMPLATE.md
+13
View File
@@ -0,0 +1,13 @@
<!-- Thanks for contributing to Waybar! Please fill in the sections below. -->
**What does this PR do?**
A short description of the change and the motivation behind it.
**Related issues**
Closes #
**Checklist**
- [ ] Code is formatted with `clang-format`
- [ ] Builds locally (`ninja -C build`)
- [ ] Man page updated for any new/changed user-facing option (`man/`)
- [ ] Tested against the affected module(s)
CONTRIBUTING.md
+45
View File
@@ -0,0 +1,45 @@
# Contributing to Waybar
Thanks for helping improve Waybar! This guide covers the essentials.
## Building for development
```bash
meson setup build
ninja -C build
./build/waybar # run your build directly
```
Enable all optional modules while developing:
```bash
meson setup build -Dexperimental=true
```
## Code style
Waybar follows [Google's C++ style guide](https://google.github.io/styleguide/cppguide.html).
Format your changes before committing:
```bash
clang-format -i <files>
```
CI runs `clang-format` and a full build on Linux and FreeBSD — please make sure
both pass.
## Documentation
Module documentation lives in [`man/`](man) as scdoc man pages, **not** in the
wiki. Editing a man page and merging to `master` regenerates the matching wiki
page automatically (see [`.github/wiki`](.github/wiki)). When you add a module,
add its man page and a line in [`.github/wiki/mapping.json`](.github/wiki/mapping.json).
## Pull requests
- Branch from `master` and keep each PR focused on one change.
- Describe what changed and why; link any related issues.
- Add or update the man page for every user-facing option you introduce.
- Build and test against the module(s) you touched.
Have fun :)
README.md
+102 -123
View File
@@ -1,161 +1,140 @@
# Waybar [![Licence](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![Paypal Donate](https://img.shields.io/badge/Donate-Paypal-2244dd.svg)](https://paypal.me/ARouillard)<br>![Waybar](https://raw.githubusercontent.com/alexays/waybar/master/preview-2.png) # Waybar
> Highly customizable Wayland bar for Sway and Wlroots based compositors.<br> [![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
> Available in [all major distributions](https://github.com/Alexays/Waybar/wiki/Installation)<br> [![Donate](https://img.shields.io/badge/Donate-Paypal-2244dd.svg)](https://paypal.me/ARouillard)
> *Waybar [examples](https://github.com/Alexays/Waybar/wiki/Examples)* [![CI](https://github.com/Alexays/Waybar/actions/workflows/linux.yml/badge.svg)](https://github.com/Alexays/Waybar/actions/workflows/linux.yml)
[![Release](https://img.shields.io/github/v/release/Alexays/Waybar)](https://github.com/Alexays/Waybar/releases)
#### Current features ![Waybar](https://raw.githubusercontent.com/alexays/waybar/master/preview-2.png)
- Sway (Workspaces, Binding mode, Focused window name)
- River (Mapping mode, Tags, Focused window name, Layout)
- Hyprland (Window Icons, Workspaces, Focused window name)
- Niri (Workspaces, Focused window name, Language)
- Mango (Workspaces, Focused window name, Language, Keymode)
- DWL (Tags, Focused window name) [requires dwl ipc patch](https://codeberg.org/dwl/dwl-patches/src/branch/main/patches/ipc)
- Tray [#21](https://github.com/Alexays/Waybar/issues/21)
- Local time
- Battery
- UPower
- Power profiles daemon
- Network
- Bluetooth
- Pulseaudio
- Privacy Info
- Wireplumber
- Disk
- Memory
- Cpu load average
- Temperature
- MPD
- Custom scripts
- Custom image
- Multiple output configuration
- And many more customizations
#### Configuration and Styling > Highly customizable Wayland bar for Sway and wlroots-based compositors.<br>
> Available in [all major distributions](https://github.com/Alexays/Waybar/wiki/Installation).
[See the wiki for more details](https://github.com/Alexays/Waybar/wiki). **[Installation](#installation) · [Wiki](https://github.com/Alexays/Waybar/wiki) · [Configuration](https://github.com/Alexays/Waybar/wiki/Configuration) · [Styling](https://github.com/Alexays/Waybar/wiki/Styling) · [Examples](https://github.com/Alexays/Waybar/wiki/Examples) · [FAQ](https://github.com/Alexays/Waybar/wiki/FAQ)**
### Installation ## Features
Waybar is available from a number of Linux distributions: ### Compositor integration
| Compositor | Workspaces / Tags | Window | Layout | Language | Mode |
| --- | :---: | :---: | :---: | :---: | :---: |
| [Sway](https://github.com/Alexays/Waybar/wiki/Module:-Sway) | ✅ | ✅ | | ✅ | ✅ |
| [River](https://github.com/Alexays/Waybar/wiki/Module:-River) | ✅ | ✅ | ✅ | | ✅ |
| [Hyprland](https://github.com/Alexays/Waybar/wiki/Module:-Hyprland) | ✅ | ✅ | | ✅ | ✅ |
| [Niri](https://github.com/Alexays/Waybar/wiki/Module:-Niri) | ✅ | ✅ | | ✅ | |
| [Mango](https://github.com/Alexays/Waybar/wiki/Module:-Mango) | ✅ | ✅ | ✅ | ✅ | ✅ |
| [DWL](https://github.com/Alexays/Waybar/wiki/Module:-Dwl) | ✅ | ✅ | | | |
| [Wayfire](https://github.com/Alexays/Waybar/wiki/Module:-Wayfire) | ✅ | ✅ | | | |
> DWL requires the [dwl IPC patch](https://codeberg.org/dwl/dwl-patches/src/branch/main/patches/ipc).
### Modules
- **Power & hardware** — [Battery](https://github.com/Alexays/Waybar/wiki/Module:-Battery), [UPower](https://github.com/Alexays/Waybar/wiki/Module:-UPower), [Power profiles daemon](https://github.com/Alexays/Waybar/wiki/Module:-PowerProfilesDaemon), [Backlight](https://github.com/Alexays/Waybar/wiki/Module:-Backlight), [CPU](https://github.com/Alexays/Waybar/wiki/Module:-CPU), [Memory](https://github.com/Alexays/Waybar/wiki/Module:-Memory), [Disk](https://github.com/Alexays/Waybar/wiki/Module:-Disk), [Temperature](https://github.com/Alexays/Waybar/wiki/Module:-Temperature)
- **Connectivity** — [Network](https://github.com/Alexays/Waybar/wiki/Module:-Network), [Bluetooth](https://github.com/Alexays/Waybar/wiki/Module:-Bluetooth), [GPS](https://github.com/Alexays/Waybar/wiki/Module:-GPS), [WWAN](https://github.com/Alexays/Waybar/wiki/Module:-WWAN)
- **Audio & media** — [PulseAudio](https://github.com/Alexays/Waybar/wiki/Module:-PulseAudio), [WirePlumber](https://github.com/Alexays/Waybar/wiki/Module:-WirePlumber), [JACK](https://github.com/Alexays/Waybar/wiki/Module:-JACK), [sndio](https://github.com/Alexays/Waybar/wiki/Module:-Sndio), [Cava](https://github.com/Alexays/Waybar/wiki/Module:-Cava), [MPD](https://github.com/Alexays/Waybar/wiki/Module:-MPD), [MPRIS](https://github.com/Alexays/Waybar/wiki/Module:-MPRIS)
- **Desktop** — [Clock & calendar](https://github.com/Alexays/Waybar/wiki/Module:-Clock), [System tray](https://github.com/Alexays/Waybar/wiki/Module:-Tray), [Idle inhibitor](https://github.com/Alexays/Waybar/wiki/Module:-Idle-Inhibitor), [Keyboard state](https://github.com/Alexays/Waybar/wiki/Module:-Keyboard-State), [Privacy](https://github.com/Alexays/Waybar/wiki/Module:-Privacy), [Gamemode](https://github.com/Alexays/Waybar/wiki/Module:-Gamemode), [Systemd failed units](https://github.com/Alexays/Waybar/wiki/Module:-Systemd-failed-units), [Image](https://github.com/Alexays/Waybar/wiki/Module:-Image), [Custom scripts](https://github.com/Alexays/Waybar/wiki/Module:-Custom)
…and more. Every module is documented on the [wiki](https://github.com/Alexays/Waybar/wiki) (see the *Modules* sidebar).
## Getting started
```bash
git clone https://github.com/Alexays/Waybar
cd Waybar
meson setup build
ninja -C build
./build/waybar # run without installing
```
Waybar launches with a sensible [default config](resources/config.jsonc). To make
it yours, copy the default config and stylesheet into `~/.config/waybar/` and edit
them. The [Configuration](https://github.com/Alexays/Waybar/wiki/Configuration)
and [Styling](https://github.com/Alexays/Waybar/wiki/Styling) guides cover every
option, and [Examples](https://github.com/Alexays/Waybar/wiki/Examples) has
ready-to-use community setups.
## Installation
Waybar is packaged by most distributions:
[![Packaging status](https://repology.org/badge/vertical-allrepos/waybar.svg?columns=3&header=Waybar%20Downstream%20Packaging)](https://repology.org/project/waybar/versions) [![Packaging status](https://repology.org/badge/vertical-allrepos/waybar.svg?columns=3&header=Waybar%20Downstream%20Packaging)](https://repology.org/project/waybar/versions)
An Ubuntu PPA with more recent versions is available An Ubuntu PPA with more recent versions is available [here](https://launchpad.net/~nschloe/+archive/ubuntu/waybar).
[here](https://launchpad.net/~nschloe/+archive/ubuntu/waybar).
### Building from source
#### Building from source
```bash ```bash
$ git clone https://github.com/Alexays/Waybar git clone https://github.com/Alexays/Waybar
$ cd Waybar cd Waybar
$ meson setup build meson setup build
$ ninja -C build ninja -C build
$ ./build/waybar ninja -C build install # optional
# If you want to install it
$ ninja -C build install
$ waybar
``` ```
**Dependencies** <details>
<summary><b>Runtime dependencies</b></summary>
``` ```
gtkmm3 gtkmm3 jsoncpp libsigc++ fmt wayland
jsoncpp chrono-date spdlog xkbregistry libgtk-3-dev upower
libsigc++
fmt libpulse [Pulseaudio module]
wayland libnl [Network module]
chrono-date
spdlog
libgtk-3-dev [gtk-layer-shell]
gobject-introspection [gtk-layer-shell]
libgirepository1.0-dev [gtk-layer-shell]
libpulse [Pulseaudio module]
libnl [Network module]
libappindicator-gtk3 [Tray module] libappindicator-gtk3 [Tray module]
libdbusmenu-gtk3 [Tray module] libdbusmenu-gtk3 [Tray module]
libmpdclient [MPD module] libmpdclient [MPD module]
libsndio [sndio module] libsndio [sndio module]
libevdev [KeyboardState module] libevdev [KeyboardState module]
xkbregistry
upower [UPower battery module]
``` ```
</details>
**Build dependencies** <details>
<summary><b>Build dependencies</b></summary>
``` ```
cmake cmake meson scdoc wayland-protocols
meson
scdoc
wayland-protocols
``` ```
</details>
On Ubuntu, you can install all the relevant dependencies using this command (tested with 19.10 and 20.04): <details>
<summary><b>Install dependencies — Ubuntu</b></summary>
``` ```bash
sudo apt install \ sudo apt install \
clang-tidy \ clang-tidy gobject-introspection libdbusmenu-gtk3-dev libevdev-dev \
gobject-introspection \ libfmt-dev libgirepository1.0-dev libgtk-3-dev libgtkmm-3.0-dev \
libdbusmenu-gtk3-dev \ libinput-dev libjsoncpp-dev libmpdclient-dev libnl-3-dev libnl-genl-3-dev \
libevdev-dev \ libpulse-dev libsigc++-2.0-dev libspdlog-dev libwayland-dev scdoc upower \
libfmt-dev \
libgirepository1.0-dev \
libgtk-3-dev \
libgtkmm-3.0-dev \
libinput-dev \
libjsoncpp-dev \
libmpdclient-dev \
libnl-3-dev \
libnl-genl-3-dev \
libpulse-dev \
libsigc++-2.0-dev \
libspdlog-dev \
libwayland-dev \
scdoc \
upower \
libxkbregistry-dev libxkbregistry-dev
``` ```
</details>
On Arch, you can use this command: <details>
<summary><b>Install dependencies — Arch</b></summary>
``` ```bash
pacman -S --asdeps \ pacman -S --asdeps \
gtkmm3 \ gtkmm3 jsoncpp libsigc++ fmt wayland chrono-date spdlog gtk3 \
jsoncpp \ gobject-introspection libgirepository libpulse libnl libappindicator-gtk3 \
libsigc++ \ libdbusmenu-gtk3 libmpdclient sndio libevdev libxkbcommon upower meson \
fmt \ cmake scdoc wayland-protocols glib2-devel
wayland \
chrono-date \
spdlog \
gtk3 \
gobject-introspection \
libgirepository \
libpulse \
libnl \
libappindicator-gtk3 \
libdbusmenu-gtk3 \
libmpdclient \
sndio \
libevdev \
libxkbcommon \
upower \
meson \
cmake \
scdoc \
wayland-protocols \
glib2-devel
``` ```
</details>
## Contributing
Contributions welcome!<br> Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). The style
Have fun :)<br> guidelines are [Google's C++ style](https://google.github.io/styleguide/cppguide.html).
The style guidelines are [Google's](https://google.github.io/styleguide/cppguide.html)
> **Docs live in the man pages.** Module documentation is written in
> [`man/`](man) (scdoc) and auto-synced to the wiki. Edit the man page, not the
> wiki — see [`.github/wiki`](.github/wiki).
> [!CAUTION] > [!CAUTION]
> Distributions of Waybar are only released on the [official GitHub page](https://github.com/Alexays/Waybar).<br/> > Distributions of Waybar are only released on the [official GitHub page](https://github.com/Alexays/Waybar).<br>
> Waybar does **not** have an official website. Do not trust any sites that claim to be official. > Waybar does **not** have an official website. Do not trust any site claiming to be official.
## License ## License
Waybar is licensed under the MIT license. [See LICENSE for more information](https://github.com/Alexays/Waybar/blob/master/LICENSE). Waybar is licensed under the MIT license. [See LICENSE for details](https://github.com/Alexays/Waybar/blob/master/LICENSE).