Skip to content

Commit 54db664

Browse files
Alexaysclaude
Alexays
and
claude
committed
docs: revamp README and add contributor docs
- 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>
1 parent 6d3656a commit 54db664

5 files changed

Lines changed: 222 additions & 129 deletions

File tree

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
name: Bug report
3+
about: Report a problem with Waybar
4+
title: ''
5+
labels: bug
6+
assignees: ''
7+
---
8+
9+
**Describe the bug**
10+
A clear and concise description of what the bug is.
11+
12+
**To reproduce**
13+
Steps to reproduce the behaviour, including a minimal config that triggers it:
14+
15+
```jsonc
16+
// minimal config
17+
```
18+
19+
**Expected behaviour**
20+
What you expected to happen.
21+
22+
**Screenshots**
23+
If applicable, add screenshots to help explain the problem.
24+
25+
**Environment**
26+
- Waybar version (`waybar --version`):
27+
- Installed from (distro package / source / other):
28+
- Compositor and version (Sway, Hyprland, River, …):
29+
30+
**Debug output**
31+
Run `waybar -l debug` and paste any relevant output:
32+
33+
```
34+
```
35+
36+
**Additional context**
37+
Anything else that might help.

‎.github/ISSUE_TEMPLATE/feature_request.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
name: Feature request
3+
about: Suggest an idea or improvement for Waybar
4+
title: ''
5+
labels: enhancement
6+
assignees: ''
7+
---
8+
9+
**Is your feature request related to a problem?**
10+
A clear and concise description of the problem, e.g. "I'm frustrated when […]".
11+
12+
**Describe the solution you'd like**
13+
What you want to happen.
14+
15+
**Describe alternatives you've considered**
16+
Any alternative solutions or features you've thought about.
17+
18+
**Additional context**
19+
Which module does this concern? Add any other context or mockups here.

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
<!-- Thanks for contributing to Waybar! Please fill in the sections below. -->
2+
3+
**What does this PR do?**
4+
A short description of the change and the motivation behind it.
5+
6+
**Related issues**
7+
Closes #
8+
9+
**Checklist**
10+
- [ ] Code is formatted with `clang-format`
11+
- [ ] Builds locally (`ninja -C build`)
12+
- [ ] Man page updated for any new/changed user-facing option (`man/`)
13+
- [ ] Tested against the affected module(s)

‎CONTRIBUTING.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Contributing to Waybar
2+
3+
Thanks for helping improve Waybar! This guide covers the essentials.
4+
5+
## Building for development
6+
7+
```bash
8+
meson setup build
9+
ninja -C build
10+
./build/waybar # run your build directly
11+
```
12+
13+
Enable all optional modules while developing:
14+
15+
```bash
16+
meson setup build -Dexperimental=true
17+
```
18+
19+
## Code style
20+
21+
Waybar follows [Google's C++ style guide](https://google.github.io/styleguide/cppguide.html).
22+
Format your changes before committing:
23+
24+
```bash
25+
clang-format -i <files>
26+
```
27+
28+
CI runs `clang-format` and a full build on Linux and FreeBSD — please make sure
29+
both pass.
30+
31+
## Documentation
32+
33+
Module documentation lives in [`man/`](man) as scdoc man pages, **not** in the
34+
wiki. Editing a man page and merging to `master` regenerates the matching wiki
35+
page automatically (see [`.github/wiki`](.github/wiki)). When you add a module,
36+
add its man page and a line in [`.github/wiki/mapping.json`](.github/wiki/mapping.json).
37+
38+
## Pull requests
39+
40+
- Branch from `master` and keep each PR focused on one change.
41+
- Describe what changed and why; link any related issues.
42+
- Add or update the man page for every user-facing option you introduce.
43+
- Build and test against the module(s) you touched.
44+
45+
Have fun :)

‎README.md‎

Lines changed: 108 additions & 129 deletions
Original file line numberDiff line numberDiff line change
@@ -1,161 +1,140 @@
1-
# 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)
2-
3-
> Highly customizable Wayland bar for Sway and Wlroots based compositors.<br>
4-
> Available in [all major distributions](https://github.com/Alexays/Waybar/wiki/Installation)<br>
5-
> *Waybar [examples](https://github.com/Alexays/Waybar/wiki/Examples)*
6-
7-
#### Current features
8-
- Sway (Workspaces, Binding mode, Focused window name)
9-
- River (Mapping mode, Tags, Focused window name, Layout)
10-
- Hyprland (Window Icons, Workspaces, Focused window name)
11-
- Niri (Workspaces, Focused window name, Language)
12-
- Mango (Workspaces, Focused window name, Language, Keymode)
13-
- DWL (Tags, Focused window name) [requires dwl ipc patch](https://codeberg.org/dwl/dwl-patches/src/branch/main/patches/ipc)
14-
- Tray [#21](https://github.com/Alexays/Waybar/issues/21)
15-
- Local time
16-
- Battery
17-
- UPower
18-
- Power profiles daemon
19-
- Network
20-
- Bluetooth
21-
- Pulseaudio
22-
- Privacy Info
23-
- Wireplumber
24-
- Disk
25-
- Memory
26-
- Cpu load average
27-
- Temperature
28-
- MPD
29-
- Custom scripts
30-
- Custom image
31-
- Multiple output configuration
32-
- And many more customizations
33-
34-
#### Configuration and Styling
35-
36-
[See the wiki for more details](https://github.com/Alexays/Waybar/wiki).
37-
38-
### Installation
39-
40-
Waybar is available from a number of Linux distributions:
1+
# Waybar
412

42-
[![Packaging status](https://repology.org/badge/vertical-allrepos/waybar.svg?columns=3&header=Waybar%20Downstream%20Packaging)](https://repology.org/project/waybar/versions)
3+
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
4+
[![Donate](https://img.shields.io/badge/Donate-Paypal-2244dd.svg)](https://paypal.me/ARouillard)
5+
[![CI](https://github.com/Alexays/Waybar/actions/workflows/linux.yml/badge.svg)](https://github.com/Alexays/Waybar/actions/workflows/linux.yml)
6+
[![Release](https://img.shields.io/github/v/release/Alexays/Waybar)](https://github.com/Alexays/Waybar/releases)
7+
8+
![Waybar](https://raw.githubusercontent.com/alexays/waybar/master/preview-2.png)
9+
10+
> Highly customizable Wayland bar for Sway and wlroots-based compositors.<br>
11+
> Available in [all major distributions](https://github.com/Alexays/Waybar/wiki/Installation).
12+
13+
**[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)**
14+
15+
## Features
16+
17+
### Compositor integration
18+
19+
| Compositor | Workspaces / Tags | Window | Layout | Language | Mode |
20+
| --- | :---: | :---: | :---: | :---: | :---: |
21+
| [Sway](https://github.com/Alexays/Waybar/wiki/Module:-Sway) | ✅ | ✅ | | ✅ | ✅ |
22+
| [River](https://github.com/Alexays/Waybar/wiki/Module:-River) | ✅ | ✅ | ✅ | | ✅ |
23+
| [Hyprland](https://github.com/Alexays/Waybar/wiki/Module:-Hyprland) | ✅ | ✅ | | ✅ | ✅ |
24+
| [Niri](https://github.com/Alexays/Waybar/wiki/Module:-Niri) | ✅ | ✅ | | ✅ | |
25+
| [Mango](https://github.com/Alexays/Waybar/wiki/Module:-Mango) | ✅ | ✅ | ✅ | ✅ | ✅ |
26+
| [DWL](https://github.com/Alexays/Waybar/wiki/Module:-Dwl) | ✅ | ✅ | | | |
27+
| [Wayfire](https://github.com/Alexays/Waybar/wiki/Module:-Wayfire) | ✅ | ✅ | | | |
4328

44-
An Ubuntu PPA with more recent versions is available
45-
[here](https://launchpad.net/~nschloe/+archive/ubuntu/waybar).
29+
> DWL requires the [dwl IPC patch](https://codeberg.org/dwl/dwl-patches/src/branch/main/patches/ipc).
4630
31+
### Modules
4732

48-
#### Building from source
33+
- **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)
34+
- **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)
35+
- **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)
36+
- **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)
37+
38+
…and more. Every module is documented on the [wiki](https://github.com/Alexays/Waybar/wiki) (see the *Modules* sidebar).
39+
40+
## Getting started
4941

5042
```bash
51-
$ git clone https://github.com/Alexays/Waybar
52-
$ cd Waybar
53-
$ meson setup build
54-
$ ninja -C build
55-
$ ./build/waybar
56-
# If you want to install it
57-
$ ninja -C build install
58-
$ waybar
43+
git clone https://github.com/Alexays/Waybar
44+
cd Waybar
45+
meson setup build
46+
ninja -C build
47+
./build/waybar # run without installing
5948
```
6049

61-
**Dependencies**
50+
Waybar launches with a sensible [default config](resources/config.jsonc). To make
51+
it yours, copy the default config and stylesheet into `~/.config/waybar/` and edit
52+
them. The [Configuration](https://github.com/Alexays/Waybar/wiki/Configuration)
53+
and [Styling](https://github.com/Alexays/Waybar/wiki/Styling) guides cover every
54+
option, and [Examples](https://github.com/Alexays/Waybar/wiki/Examples) has
55+
ready-to-use community setups.
56+
57+
## Installation
58+
59+
Waybar is packaged by most distributions:
60+
61+
[![Packaging status](https://repology.org/badge/vertical-allrepos/waybar.svg?columns=3&header=Waybar%20Downstream%20Packaging)](https://repology.org/project/waybar/versions)
62+
63+
An Ubuntu PPA with more recent versions is available [here](https://launchpad.net/~nschloe/+archive/ubuntu/waybar).
64+
65+
### Building from source
66+
67+
```bash
68+
git clone https://github.com/Alexays/Waybar
69+
cd Waybar
70+
meson setup build
71+
ninja -C build
72+
ninja -C build install # optional
73+
```
74+
75+
<details>
76+
<summary><b>Runtime dependencies</b></summary>
6277

6378
```
64-
gtkmm3
65-
jsoncpp
66-
libsigc++
67-
fmt
68-
wayland
69-
chrono-date
70-
spdlog
71-
libgtk-3-dev [gtk-layer-shell]
72-
gobject-introspection [gtk-layer-shell]
73-
libgirepository1.0-dev [gtk-layer-shell]
74-
libpulse [Pulseaudio module]
75-
libnl [Network module]
79+
gtkmm3 jsoncpp libsigc++ fmt wayland
80+
chrono-date spdlog xkbregistry libgtk-3-dev upower
81+
82+
libpulse [Pulseaudio module]
83+
libnl [Network module]
7684
libappindicator-gtk3 [Tray module]
77-
libdbusmenu-gtk3 [Tray module]
78-
libmpdclient [MPD module]
79-
libsndio [sndio module]
80-
libevdev [KeyboardState module]
81-
xkbregistry
82-
upower [UPower battery module]
85+
libdbusmenu-gtk3 [Tray module]
86+
libmpdclient [MPD module]
87+
libsndio [sndio module]
88+
libevdev [KeyboardState module]
8389
```
90+
</details>
8491

85-
**Build dependencies**
92+
<details>
93+
<summary><b>Build dependencies</b></summary>
8694

8795
```
88-
cmake
89-
meson
90-
scdoc
91-
wayland-protocols
96+
cmake meson scdoc wayland-protocols
9297
```
98+
</details>
9399

94-
On Ubuntu, you can install all the relevant dependencies using this command (tested with 19.10 and 20.04):
100+
<details>
101+
<summary><b>Install dependencies — Ubuntu</b></summary>
95102

96-
```
103+
```bash
97104
sudo apt install \
98-
clang-tidy \
99-
gobject-introspection \
100-
libdbusmenu-gtk3-dev \
101-
libevdev-dev \
102-
libfmt-dev \
103-
libgirepository1.0-dev \
104-
libgtk-3-dev \
105-
libgtkmm-3.0-dev \
106-
libinput-dev \
107-
libjsoncpp-dev \
108-
libmpdclient-dev \
109-
libnl-3-dev \
110-
libnl-genl-3-dev \
111-
libpulse-dev \
112-
libsigc++-2.0-dev \
113-
libspdlog-dev \
114-
libwayland-dev \
115-
scdoc \
116-
upower \
105+
clang-tidy gobject-introspection libdbusmenu-gtk3-dev libevdev-dev \
106+
libfmt-dev libgirepository1.0-dev libgtk-3-dev libgtkmm-3.0-dev \
107+
libinput-dev libjsoncpp-dev libmpdclient-dev libnl-3-dev libnl-genl-3-dev \
108+
libpulse-dev libsigc++-2.0-dev libspdlog-dev libwayland-dev scdoc upower \
117109
libxkbregistry-dev
118110
```
111+
</details>
119112

120-
On Arch, you can use this command:
113+
<details>
114+
<summary><b>Install dependencies — Arch</b></summary>
121115

122-
```
116+
```bash
123117
pacman -S --asdeps \
124-
gtkmm3 \
125-
jsoncpp \
126-
libsigc++ \
127-
fmt \
128-
wayland \
129-
chrono-date \
130-
spdlog \
131-
gtk3 \
132-
gobject-introspection \
133-
libgirepository \
134-
libpulse \
135-
libnl \
136-
libappindicator-gtk3 \
137-
libdbusmenu-gtk3 \
138-
libmpdclient \
139-
sndio \
140-
libevdev \
141-
libxkbcommon \
142-
upower \
143-
meson \
144-
cmake \
145-
scdoc \
146-
wayland-protocols \
147-
glib2-devel
118+
gtkmm3 jsoncpp libsigc++ fmt wayland chrono-date spdlog gtk3 \
119+
gobject-introspection libgirepository libpulse libnl libappindicator-gtk3 \
120+
libdbusmenu-gtk3 libmpdclient sndio libevdev libxkbcommon upower meson \
121+
cmake scdoc wayland-protocols glib2-devel
148122
```
123+
</details>
124+
125+
## Contributing
149126

127+
Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). The style
128+
guidelines are [Google's C++ style](https://google.github.io/styleguide/cppguide.html).
150129

151-
Contributions welcome!<br>
152-
Have fun :)<br>
153-
The style guidelines are [Google's](https://google.github.io/styleguide/cppguide.html)
130+
> **Docs live in the man pages.** Module documentation is written in
131+
> [`man/`](man) (scdoc) and auto-synced to the wiki. Edit the man page, not the
132+
> wiki — see [`.github/wiki`](.github/wiki).
154133
155134
> [!CAUTION]
156-
> Distributions of Waybar are only released on the [official GitHub page](https://github.com/Alexays/Waybar).<br/>
157-
> Waybar does **not** have an official website. Do not trust any sites that claim to be official.
135+
> Distributions of Waybar are only released on the [official GitHub page](https://github.com/Alexays/Waybar).<br>
136+
> Waybar does **not** have an official website. Do not trust any site claiming to be official.
158137
159138
## License
160139

161-
Waybar is licensed under the MIT license. [See LICENSE for more information](https://github.com/Alexays/Waybar/blob/master/LICENSE).
140+
Waybar is licensed under the MIT license. [See LICENSE for details](https://github.com/Alexays/Waybar/blob/master/LICENSE).

0 commit comments

Comments
 (0)