Skip to content

Conversation

@JakeStanger
Copy link
Owner

@JakeStanger JakeStanger commented Jan 3, 2026

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.

image

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.

image

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/modules/clock

(no homepage yet...)

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

@JakeStanger JakeStanger force-pushed the docs/starlight branch 4 times, most recently from 8683efe to 3873250 Compare January 7, 2026 23:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants