From 228f1ca22053226a50667bcd499c360ce321db3c Mon Sep 17 00:00:00 2001 From: Sebastien Graf <95282692+Seb-GRAF@users.noreply.github.com> Date: Fri, 30 Oct 2026 11:37:12 +0100 Subject: [PATCH 1/3] docs: show StableBar in motion in the README --- README.md | 92 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 48 insertions(+), 44 deletions(-) diff --git a/README.md b/README.md index 8942f81..b4d11cf 100644 --- a/README.md +++ b/README.md @@ -18,10 +18,7 @@ Themes, widgets and popups, set up in the app or in plain JSON.
- - - StableBar with workspaces, the active app, the next meeting, CPU and memory use, the battery and the time. Today's agenda is open below the meeting. - +The macOS menu bar's items fade away and StableBar takes its place: workspaces with their app icons, the active app, music, the next meeting, CPU and memory, the battery and the clock. ## Features @@ -34,46 +31,63 @@ Themes, widgets and popups, set up in the app or in plain JSON. - **Every display.** Notch-aware placement, widgets per kind of screen and a separate bar for each screen setup. - **Scriptable.** The command line queries and edits the running bar and sends events from other tools. -## Themes +## Workspaces -The same bar in each theme that ships with StableBar. Choose one during setup, cycle through them on your own bar with **Try Themes…**, or get more from the [store](https://github.com/Seb-GRAF/stablebar-packages). +The workspaces widget shows each workspace and its apps from AeroSpace, yabai or OmniWM, and follows you as you switch. Without a window manager, it can show macOS Spaces. See [Built-in widgets](docs/widgets.md). - - - One bar shown in each theme that ships with StableBar - +The bar's workspaces widget switching between workspaces while the window below changes to each workspace's app ## Popups Any widget can open a popup. Build it from rows, columns, text, graphs, lists, buttons, sliders, toggles and search fields, filled with the widget's data. See [Custom popups](docs/popups.md). - - - Three popups: CPU and memory with a graph, today's agenda, and a panel with a slider, a toggle, a segmented control and a search field - +Clicking the meeting, system and music widgets opens today's agenda, a CPU and memory graph, and the playing track with its controls -## Settings +## Themes -Change content, appearance and behavior without touching JSON. Settings saves to the same configuration file you can edit by hand, with undo and redo. See [Settings](docs/settings.md). +Six themes ship with StableBar, alongside Built-in. Choose one during setup, cycle through them on your own bar with **Try Themes…**, or get more from the [store](https://github.com/Seb-GRAF/stablebar-packages). **Save as Theme…** turns your own look into one. See [Themes](docs/themes.md). - - - The Theme section of StableBar Settings, with a preview of the bar, the theme gallery and the theme's colors - +One bar, with its agenda popup open, changing through each theme that ships with StableBar -## Install +## Edit the bar in place -1. Download `StableBar.dmg` from the [latest release](https://github.com/Seb-GRAF/StableBar/releases/latest). -2. Open it and drag StableBar to Applications. -3. Open StableBar. Setup walks you through a preset, a theme and a placement. +Choose **Edit Bar in Place** from the bar's right-click menu to arrange widgets on the bar itself: drag them between positions, remove them with **−** or add one with **+**. Changes save as you go, with undo. See [Settings](docs/settings.md). -With [Homebrew](https://brew.sh), `brew install --cask seb-graf/tap/stablebar` replaces the first two steps. +Editing the bar in place: the music widget is dragged from the right of the bar to its center, then Done restores the normal bar -StableBar needs macOS 14 or later on Apple silicon. Releases update themselves; choose the Beta track in **Settings → General → Updates** to get betas. See [Getting started](docs/getting-started.md). To remove StableBar, use **Settings → General → [Uninstall](docs/getting-started.md#uninstall)**, which also turns off the menu bar auto-hide that StableBar turned on. +## Any script is a widget + +A widget can run any command that prints text or a JSON object, refresh on a timer or on events, and open a popup with graphs, lists and controls. + +A two-line shell script prints the disk usage, and its output appears on the bar as a new widget + +```sh +#!/bin/sh +# ~/.config/stablebar/widgets/disk.sh +used=$(df -h / | awk 'NR == 2 { print $5 }') +printf '{"text":"%s","icon":"internaldrive"}' "$used" +``` + +```json +{ + "id": "disk", "type": "script", "position": "right", "interval": 300, + "command": "~/.config/stablebar/widgets/disk.sh" +} +``` -## Configure +[Create a widget](docs/create-a-widget.md) covers the output format, events and layouts. Share a widget as a [package](docs/packages.md). -Your bar lives in `~/.config/stablebar/config.json`. Setup and Settings save to it, and you can edit it yourself: StableBar applies the file when you save it, and keeps the last working bar if a change is invalid. The JSON schema gives editors completion and validation. +## Widget store + +**Settings → Packages → Store** lists widgets and themes from the [StableBar store](https://github.com/Seb-GRAF/stablebar-packages). Before anything runs, StableBar shows the commands, hosts and permissions a package uses. See [Packages and the store](docs/packages.md#store). + +The Store in Settings lists widget packages; getting the Weather package marks it installed + +## Settings or JSON + +Change content, appearance and behavior in Settings, with undo and redo, or edit the file it saves to. Your bar lives in `~/.config/stablebar/config.json`: StableBar applies the file when you save it, and keeps the last working bar if a change is invalid. The JSON schema gives editors completion and validation. See [Settings](docs/settings.md) and [Configuration](docs/configuration.md). + +The Theme section of StableBar Settings next to the configuration file it saves to ```json { @@ -88,25 +102,15 @@ Your bar lives in `~/.config/stablebar/config.json`. Setup and Settings save to } ``` -## Write a widget - -A widget can run any command that prints text or a JSON object: +## Install -```sh -#!/bin/sh -# ~/.config/stablebar/widgets/disk.sh -used=$(df -h / | awk 'NR == 2 { print $5 }') -printf '{"text":"%s","icon":"internaldrive"}' "$used" -``` +1. Download `StableBar.dmg` from the [latest release](https://github.com/Seb-GRAF/StableBar/releases/latest). +2. Open it and drag StableBar to Applications. +3. Open StableBar. Setup walks you through a preset, a theme and a placement. -```json -{ - "id": "disk", "type": "script", "position": "right", "interval": 300, - "command": "~/.config/stablebar/widgets/disk.sh" -} -``` +With [Homebrew](https://brew.sh), `brew install --cask seb-graf/tap/stablebar` replaces the first two steps. -[Create a widget](docs/create-a-widget.md) covers the output format, events and layouts. Share a widget as a [package](docs/packages.md), or install others from the store in **Settings → Packages**. +StableBar needs macOS 14 or later on Apple silicon. Releases update themselves; choose the Beta track in **Settings → General → Updates** to get betas. See [Getting started](docs/getting-started.md). To remove StableBar, use **Settings → General → [Uninstall](docs/getting-started.md#uninstall)**, which also turns off the menu bar auto-hide that StableBar turned on. ## Documentation From 8a4097945111bd109325b361dde61188fa6b4d83 Mon Sep 17 00:00:00 2001 From: Sebastien Graf <95282692+Seb-GRAF@users.noreply.github.com> Date: Fri, 30 Oct 2026 11:56:25 +0100 Subject: [PATCH 2/3] docs: use calmer clips made for the README --- README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index b4d11cf..7a9233b 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ Themes, widgets and popups, set up in the app or in plain JSON.
-The macOS menu bar's items fade away and StableBar takes its place: workspaces with their app icons, the active app, music, the next meeting, CPU and memory, the battery and the clock. +StableBar on the desktop: workspaces with their app icons, the active app, music, the next meeting, CPU and memory, the battery and the clock. It moves to another workspace and back. ## Features @@ -35,31 +35,31 @@ Themes, widgets and popups, set up in the app or in plain JSON. The workspaces widget shows each workspace and its apps from AeroSpace, yabai or OmniWM, and follows you as you switch. Without a window manager, it can show macOS Spaces. See [Built-in widgets](docs/widgets.md). -The bar's workspaces widget switching between workspaces while the window below changes to each workspace's app +The bar's workspaces widget switching between workspaces while the window below changes to each workspace's app ## Popups Any widget can open a popup. Build it from rows, columns, text, graphs, lists, buttons, sliders, toggles and search fields, filled with the widget's data. See [Custom popups](docs/popups.md). -Clicking the meeting, system and music widgets opens today's agenda, a CPU and memory graph, and the playing track with its controls +The pointer clicks the meeting, system and music widgets in turn, opening today's agenda, a CPU and memory graph, and the playing track with its controls ## Themes Six themes ship with StableBar, alongside Built-in. Choose one during setup, cycle through them on your own bar with **Try Themes…**, or get more from the [store](https://github.com/Seb-GRAF/stablebar-packages). **Save as Theme…** turns your own look into one. See [Themes](docs/themes.md). -One bar, with its agenda popup open, changing through each theme that ships with StableBar +The bar and its open agenda popup changing through each theme that ships with StableBar, then back to Built-in ## Edit the bar in place Choose **Edit Bar in Place** from the bar's right-click menu to arrange widgets on the bar itself: drag them between positions, remove them with **−** or add one with **+**. Changes save as you go, with undo. See [Settings](docs/settings.md). -Editing the bar in place: the music widget is dragged from the right of the bar to its center, then Done restores the normal bar +Editing the bar in place: the music widget is dragged from the right of the bar to its center, then Done restores the normal bar ## Any script is a widget A widget can run any command that prints text or a JSON object, refresh on a timer or on events, and open a popup with graphs, lists and controls. -A two-line shell script prints the disk usage, and its output appears on the bar as a new widget +A two-line shell script that prints the disk usage is typed, and its output appears on the bar as a new widget ```sh #!/bin/sh @@ -81,13 +81,13 @@ printf '{"text":"%s","icon":"internaldrive"}' "$used" **Settings → Packages → Store** lists widgets and themes from the [StableBar store](https://github.com/Seb-GRAF/stablebar-packages). Before anything runs, StableBar shows the commands, hosts and permissions a package uses. See [Packages and the store](docs/packages.md#store). -The Store in Settings lists widget packages; getting the Weather package marks it installed +The Store in Settings lists widget packages; getting the Weather package marks it installed ## Settings or JSON Change content, appearance and behavior in Settings, with undo and redo, or edit the file it saves to. Your bar lives in `~/.config/stablebar/config.json`: StableBar applies the file when you save it, and keeps the last working bar if a change is invalid. The JSON schema gives editors completion and validation. See [Settings](docs/settings.md) and [Configuration](docs/configuration.md). -The Theme section of StableBar Settings next to the configuration file it saves to +In config.json the theme is changed from catppuccin to nord and saved, and the bar above switches to Nord; then it is changed back ```json { From 05814ff62d429459ebc1d86f3d00edcd89b59533 Mon Sep 17 00:00:00 2001 From: Sebastien Graf <95282692+Seb-GRAF@users.noreply.github.com> Date: Fri, 30 Oct 2026 12:04:20 +0100 Subject: [PATCH 3/3] docs: stop the README themes clip from showing two themes at once --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 7a9233b..58b128e 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,7 @@ Any widget can open a popup. Build it from rows, columns, text, graphs, lists, b Six themes ship with StableBar, alongside Built-in. Choose one during setup, cycle through them on your own bar with **Try Themes…**, or get more from the [store](https://github.com/Seb-GRAF/stablebar-packages). **Save as Theme…** turns your own look into one. See [Themes](docs/themes.md). -The bar and its open agenda popup changing through each theme that ships with StableBar, then back to Built-in +The bar and its open agenda popup changing through each theme that ships with StableBar, then back to Built-in ## Edit the bar in place