[PR #1320] Documentation site #8326

New issue

Open

opened 2026-05-23 02:57:16 +01:00 by JakeStanger · 0 comments

JakeStanger commented

2026-05-23 02:57:16 +01:00

Owner

📋 Pull Request Information

Original PR: https://github.com/JakeStanger/ironbar/pull/1320
Author: @JakeStanger
Created: 1/3/2026
Status: 🔄 Open

Base: master ← Head: docs/starlight

📝 Commits (4)

1a7dce5 docs: replace configs tables with template for generation
d57abe6 refactor(bindmode): rename struct to BindmodeModule
a123b1f docs: tidy and improve config comments and schema gen
85b979c docs(dev guide): add info on new docs site

📊 Changes

58 files changed (+423 additions, -2489 deletions)

View changed files

📝 Cargo.lock (+1 -0)
📝 Cargo.toml (+1 -1)
📝 docs/dynamic content/Controlling Ironbar.md (+0 -0)
📝 docs/dynamic content/Dynamic values.md (+0 -0)
📝 docs/dynamic content/IPC.md (+0 -0)
📝 docs/dynamic content/Ironvars.md (+0 -0)
📝 docs/dynamic content/Scripts.md (+0 -0)
📝 docs/examples/custom/Power-Menu.md (+0 -156)
📝 docs/examples/custom/Weather.md (+0 -317)
📝 docs/guides/Compiling.md (+0 -0)
📝 docs/guides/Configuration guide.md (+5 -195)
📝 docs/guides/Development guide.md (+28 -1)
📝 docs/guides/GTK4.md (+0 -0)
📝 docs/guides/Images.md (+0 -0)
📝 docs/guides/Profiles.md (+0 -0)
📝 docs/guides/Styling guide.md (+0 -0)
📝 docs/modules/Battery.md (+6 -95)
📝 docs/modules/Bindmode.md (+8 -54)
📝 docs/modules/Bluetooth.md (+5 -173)
📝 docs/modules/Cairo.md (+11 -66)

...and 38 more files

📄 Description

I'm aiming to move away from the GitHub Wiki to a dedicated documentation site that gives some more power and control over the site.

The new docs site is built with Astro and Starlight. Markdown files are pulled in from this repo to keep updating docs centralised and simple as possible. They are then automatically converted into .mdx with the added functionality added in at build time.

Primarily, module configs no longer need to be manually documented. Instead, the JSON schema that Ironbar already generates is used. This is used to generate each page's configuration section and automatically includes all the information that's already present.

Config options are now listed out as headers and sections on a page, rather than one large table. This makes some of the more complex module documentation less cramped and provides much more room to provide additional detail inline where appropriate.

Configuration examples also do not need to be written out in all 4 supported languages. Instead, only the Corn format needs to be included. The code blocks are pulled out and converted into tabbed views for each format. This is achieved using corn.js.

Code can be found here:

https://github.com/JakeStanger/ironbar-docs/

The site is live but there's a good few issues to work through before this is stable. My primary focus has been on the module pages, so the others are lacking the new features and still need a good comb through.

https://ironb.ar

Any immediate feedback is appreciated.

This PR also includes a few minor fixes to existing documentation I found along the way. In some cases, properties that were not manually documented are now correctly documented on the site.

PS: you can also use https://ironb.ar/gh/* as a shorthand redirect to this repo. Probs not useful for anybody except me, but I have to get here a lot :P

Remaining tasks:

Load schema from external source
Add version selection
Rewrite and split up some of the guides and non-module configuration pages
Reorganise the docs
Fix all links
Figure out CI (probably using repository_dispatch event)
Document the documentation site
Add homepage and any other nav pages

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/JakeStanger/ironbar/pull/1320 **Author:** [@JakeStanger](https://github.com/JakeStanger) **Created:** 1/3/2026 **Status:** 🔄 Open **Base:** `master` ← **Head:** `docs/starlight` --- ### 📝 Commits (4) - [`1a7dce5`](https://github.com/JakeStanger/ironbar/commit/1a7dce57512fc2e217c7968b3732742559fc270b) docs: replace configs tables with template for generation - [`d57abe6`](https://github.com/JakeStanger/ironbar/commit/d57abe6dfce5e427d2221d0fe5ddb1391d2562d2) refactor(bindmode): rename struct to `BindmodeModule` - [`a123b1f`](https://github.com/JakeStanger/ironbar/commit/a123b1f1294530274bcc7bbcacc3d120c1931fcf) docs: tidy and improve config comments and schema gen - [`85b979c`](https://github.com/JakeStanger/ironbar/commit/85b979c8ff7eac5729804978aa176a3851cebe37) docs(dev guide): add info on new docs site ### 📊 Changes **58 files changed** (+423 additions, -2489 deletions) <details> <summary>View changed files</summary> 📝 `Cargo.lock` (+1 -0) 📝 `Cargo.toml` (+1 -1) 📝 `docs/dynamic content/Controlling Ironbar.md` (+0 -0) 📝 `docs/dynamic content/Dynamic values.md` (+0 -0) 📝 `docs/dynamic content/IPC.md` (+0 -0) 📝 `docs/dynamic content/Ironvars.md` (+0 -0) 📝 `docs/dynamic content/Scripts.md` (+0 -0) 📝 `docs/examples/custom/Power-Menu.md` (+0 -156) 📝 `docs/examples/custom/Weather.md` (+0 -317) 📝 `docs/guides/Compiling.md` (+0 -0) 📝 `docs/guides/Configuration guide.md` (+5 -195) 📝 `docs/guides/Development guide.md` (+28 -1) 📝 `docs/guides/GTK4.md` (+0 -0) 📝 `docs/guides/Images.md` (+0 -0) 📝 `docs/guides/Profiles.md` (+0 -0) 📝 `docs/guides/Styling guide.md` (+0 -0) 📝 `docs/modules/Battery.md` (+6 -95) 📝 `docs/modules/Bindmode.md` (+8 -54) 📝 `docs/modules/Bluetooth.md` (+5 -173) 📝 `docs/modules/Cairo.md` (+11 -66) _...and 38 more files_ </details> ### 📄 Description I'm aiming to move away from the GitHub Wiki to a dedicated documentation site that gives some more power and control over the site. The new docs site is built with Astro and Starlight. Markdown files are pulled in from this repo to keep updating docs centralised and simple as possible. They are then automatically converted into `.mdx` with the added functionality added in at build time. Primarily, module configs no longer need to be manually documented. Instead, the JSON schema that Ironbar already generates is used. This is used to generate each page's configuration section and automatically includes all the information that's already present. Config options are now listed out as headers and sections on a page, rather than one large table. This makes some of the more complex module documentation less cramped and provides much more room to provide additional detail inline where appropriate. <img width="948" height="1075" alt="image" src="https://github.com/user-attachments/assets/fd8de5e9-495d-4e1e-a65c-2c941256b34f" /> Configuration examples also do not need to be written out in all 4 supported languages. Instead, only the Corn format needs to be included. The code blocks are pulled out and converted into tabbed views for each format. This is achieved using [corn.js](https://github.com/corn-config/corn.js). <img width="891" height="201" alt="image" src="https://github.com/user-attachments/assets/ebf0c391-f671-4ea0-a664-b7e371ee50cd" /> --- Code can be found here: https://github.com/JakeStanger/ironbar-docs/ The site is live but there's a good few issues to work through before this is stable. My primary focus has been on the module pages, so the others are lacking the new features and still need a good comb through. https://ironb.ar Any immediate feedback is appreciated. --- This PR also includes a few minor fixes to existing documentation I found along the way. In some cases, properties that were not manually documented are now correctly documented on the site. PS: you can also use `https://ironb.ar/gh/*` as a shorthand redirect to this repo. Probs not useful for anybody except me, but I have to get here a lot :P --- Remaining tasks: - [x] Load schema from external source - [x] Add version selection - [ ] Rewrite and split up some of the guides and non-module configuration pages - [x] Reorganise the docs - [ ] Fix all links - [ ] Figure out CI (probably using `repository_dispatch` event) - [x] Document the documentation site - [x] Add homepage and any other nav pages --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

JakeStanger added the

pull-request

label

2026-05-23 02:57:16 +01:00