Skip to content

Migrate bnd docs to just-the-docs Jekyll theme with dark mode toggle#7150

Merged
peterkir merged 16 commits intomasterfrom
copilot/rework-documentation-into-template
Mar 20, 2026
Merged

Migrate bnd docs to just-the-docs Jekyll theme with dark mode toggle#7150
peterkir merged 16 commits intomasterfrom
copilot/rework-documentation-into-template

Conversation

Copy link
Contributor

Copilot AI commented Mar 15, 2026 •
edited
Loading

Converts the bnd documentation site from a custom hand-rolled Jekyll theme to just-the-docs, preserving all existing content.

Theme & Build

  • Replace github-pages gem with jekyll ~> 4.4 + just-the-docs ~> 0.12
  • Add theme: just-the-docs with search, GitHub/bndtools.org aux links, edit-on-GitHub, footer, and back-to-top

Navigation Structure

  • Add 9 section parent pages in _chapters/ (000-getting-started.md, 000-concepts.md, etc.) — just-the-docs resolves parent–child relationships within a collection, so parents must live in the same collection as their children
  • Update front matter in all 44 chapter files with parent: + nav_order:
  • Update front matter in all ~455 reference collection files (_commands, _instructions, _macros, _heads, _plugins, _tools) with matching parent: titles
  • Configure just_the_docs.collections: chapters shown in nav; reference collections registered with nav_exclude: true (keeps sidebar clean while still enabling breadcrumbs)

Layout & Custom Overrides

  • _layouts/bnd.html — wraps just-the-docs default and renders page.summary as a styled callout box; essential for auto-generated reference pages that carry all descriptive content in that field
  • Old custom layouts renamed to bnd-legacy-*.html (not deleted)
  • _includes/components/footer.html — patches a just-the-docs bug: empty collections_dir is "" which is truthy in Liquid, causing a double-slash in GitHub edit URLs (docs//_commands/wrap.md); fixed by adding and site.collections_dir != ""
  • _sass/custom/custom.scss — summary callout box, code-copy button, and theme toggle button styles
  • index.md — replaced minimal stub with a proper home page (Quick Start for CLI, Maven, Gradle, workspace)

Dark Mode Toggle

A three-state color-scheme toggle is added to the header, modelled on the pattern from klibio/apps _doc/_layouts/default.html:

  • Cycle: ◐ Auto → ☀ Light → ☾ Dark → ◐ Auto …
  • Auto follows the OS prefers-color-scheme media query and re-evaluates when it changes
  • No-flash: an inline <script> in <head> reads localStorage('theme-preference') and swaps the just-the-docs stylesheet before the first paint, preventing flash-of-wrong-theme (FOUC)
  • Preference persisted in localStorage under key theme-preference
  • Uses the built-in jtd.setTheme() API to swap just-the-docs-light.css ↔ just-the-docs-dark.css

Screenshots

Home page (light mode):

Hierarchical sidebar with expanded section and breadcrumb:

Command reference page — page.summary rendered as callout:

Dark mode:

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.

Copilot AI changed the title [WIP] Rework documentation to use just-the-docs template Migrate bnd docs to just-the-docs Jekyll theme Mar 15, 2026
Copilot AI requested a review from peterkir March 15, 2026 16:52
@chrisrueger
Copy link
Contributor

chrisrueger commented Mar 15, 2026

Great, Looks ver< nice :) @peterkir

@chrisrueger chrisrueger mentioned this pull request Mar 15, 2026
Closed
@peterkir
Copy link
Contributor

peterkir commented Mar 16, 2026

@copilot add a dark mode toggle as found inside the doc folder of this repo https://github.com/klibio/apps/tree/main/_doc
and published as this jekyll generated github page.

Copy link
Contributor Author

Copilot AI commented Mar 16, 2026 •
edited
Loading

@copilot add a dark mode toggle as found inside the doc folder of this repo https://github.com/klibio/apps/tree/main/_doc
and published as this jekyll generated github page.

Added a three-state dark mode toggle (commit 111f703b) modelled directly on the pattern in klibio/apps/_doc/_layouts/default.html:

  • Cycle: ◐ Auto → ☀ Light → ☾ Dark → ◐ Auto …
  • Auto follows the OS prefers-color-scheme and re-evaluates when it changes
  • No flash: an inline <script> in <head> reads localStorage('theme-preference') and swaps the stylesheet before the first paint
  • Preference is persisted in localStorage under the key theme-preference
  • Uses the built-in jtd.setTheme() API to swap just-the-docs-light.css ↔ just-the-docs-dark.css
Light mode Dark mode
light dark

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

  • https://api.github.com/repos/klibio/apps/contents/_doc
    • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node /home/REDACTED/work/_temp/ghcca-node/node/bin/node --enable-source-maps /home/REDACTED/work/_temp/copilot-developer-action-main/dist/index.js (http block)
  • just-the-docs.com
    • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node /home/REDACTED/work/_temp/ghcca-node/node/bin/node --enable-source-maps /home/REDACTED/work/_temp/copilot-developer-action-main/dist/index.js (dns block)
  • klibio.github.io
    • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node /home/REDACTED/work/_temp/ghcca-node/node/bin/node --enable-source-maps /home/REDACTED/work/_temp/copilot-developer-action-main/dist/index.js (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Copilot AI changed the title Migrate bnd docs to just-the-docs Jekyll theme Migrate bnd docs to just-the-docs Jekyll theme with dark mode toggle Mar 16, 2026
@peterkir peterkir force-pushed the copilot/rework-documentation-into-template branch from 6b59606 to 70daa30 Compare March 18, 2026 05:41
Copilot AI and others added 15 commits March 18, 2026 14:58
@peterkir
Initial plan
57d95e8 
Signed-off-by: Peter Kirschner <peter@klib.io>
@peterkir
Migrate bnd docs to just-the-docs Jekyll theme
6d98add 
- Replace github-pages gem with just-the-docs 0.12.0 and jekyll 4.4
- Add just-the-docs theme config with search, aux links, edit-on-GitHub
- Create custom bnd layout that wraps just-the-docs default and renders page.summary
- Rename old custom layouts to bnd-legacy-* (no longer override theme)
- Create section parent pages in _chapters (Getting Started, Concepts, etc.)
- Update front matter on all 44 chapter files (parent, nav_order)
- Update front matter on all 455 collection files (parent, layout)
- Configure just_the_docs.collections for chapters nav and reference nav_exclude
- Fix double-slash in GitHub edit links (override footer.html)
- Add custom SCSS for summary callout boxes and copy button styling
- Add head_custom.html for favicon and meta tags
- New index.md home page with Quick Start examples
- Regenerate Gemfile.lock for Jekyll 4.4 / just-the-docs 0.12.0

Co-authored-by: peterkir <250545+peterkir@users.noreply.github.com>
Signed-off-by: Peter Kirschner <peter@klib.io>
@peterkir
Update Gemfile version constraints to match installed versions (jekyl…
262f131 
…l ~> 4.4, just-the-docs ~> 0.12)

Co-authored-by: peterkir <250545+peterkir@users.noreply.github.com>
Signed-off-by: Peter Kirschner <peter@klib.io>
@peterkir
Add three-state dark mode toggle (Auto/Light/Dark)
3a96598 
Mirrors the pattern from klibio/apps/_doc/_layouts/default.html:
- Three-state cycle: Auto -> Light -> Dark -> Auto
- Button in header shows current state label (◐ Auto / ☀ Light / ☾ Dark)
- No-flash script in <head> applies stored preference before first paint
- OS preference respected in Auto mode, re-evaluated on media change
- Preference persisted to localStorage under key 'theme-preference'
- Uses built-in jtd.setTheme() to swap just-the-docs stylesheets

Co-authored-by: peterkir <250545+peterkir@users.noreply.github.com>
Signed-off-by: Peter Kirschner <peter@klib.io>
@peterkir
fix light/dark mode toggle switch
5402878 
Signed-off-by: Peter Kirschner <peter@klib.io>
@peterkir
migrate to just-the-docs template
27f105d 
using Just-The-Docs template provides
* integrated search capability
* Nav Bar

additionally added functionalities
* added light/dark mode switch button with browser setting consideration
* included code snippets display with type label e.g. properties, xml, java
* NavBar is updating to selected content (e.g. after search and access)
* GitHub menu bar link navigates directly to page for editing

Signed-off-by: Peter Kirschner <peter@klib.io>
@chrisrueger @peterkir
add back releases dropdown
5d8cabb 
first draft
Signed-off-by: Christoph Rueger <chrisrueger@gmail.com>
Signed-off-by: Peter Kirschner <peter@klib.io>
@chrisrueger @peterkir
fix .md generator
87b6c19 
Signed-off-by: Christoph Rueger <chrisrueger@gmail.com>
Signed-off-by: Peter Kirschner <peter@klib.io>
@peterkir
version button positioning
0d50921 
Signed-off-by: Peter Kirschner <peter@klib.io>
@peterkir
P2 artifact upload and p2 repo publishing for reference PR builds
e5be8d1 
Signed-off-by: Peter Kirschner <peter@klib.io>
@peterkir
Add --workspace/-w support to bnd baseline command for workspace-wide…
a890227 
… baselining

Signed-off-by: Peter Kirschner <peter@klib.io>
@chrisrueger @peterkir
Add branch filter (only master) for workflow_run event
60131f3 
Signed-off-by: Christoph Rueger <chrisrueger@gmail.com>
Signed-off-by: Peter Kirschner <peter@klib.io>
@peterkir
Support eclipse features in p2 repositories
1bccf06 
Signed-off-by: Peter Kirschner <peter@klib.io>
@peterkir
Initial plan
fb2c342 
Signed-off-by: Peter Kirschner <peter@klib.io>
@peterkir
reviewing and fixing
5a6b674 
Signed-off-by: Peter Kirschner <peter@klib.io>
@peterkir peterkir force-pushed the copilot/rework-documentation-into-template branch from 70daa30 to 5a6b674 Compare March 18, 2026 13:58
@chrisrueger
Copy link
Contributor

chrisrueger commented Mar 18, 2026

@peterkir looks like some unrelated things sneaked in again.

@peterkir
Copy link
Contributor

peterkir commented Mar 19, 2026

@chrisrueger
Looks sufficiently mature from my side. What is your opinion?

@peterkir
Merge branch 'master' into copilot/rework-documentation-into-template
d48957a 
Signed-off-by: Peter Kirschner <peter@klib.io>
@chrisrueger
Copy link
Contributor

chrisrueger commented Mar 19, 2026

@chrisrueger Looks sufficiently mature from my side. What is your opinion?

Let's merge :)

@peterkir peterkir marked this pull request as ready for review March 20, 2026 13:43
@peterkir peterkir merged commit bf9e94e into master Mar 20, 2026
25 checks passed
@peterkir peterkir deleted the copilot/rework-documentation-into-template branch March 20, 2026 13:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@chrisrueger chrisrueger chrisrueger approved these changes

@peterkir peterkir Awaiting requested review from peterkir

Assignees

@peterkir peterkir

Copilot code review Copilot

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@chrisrueger @peterkir