feat: upgrade mdBook to 0.5.x with TAMU theme compatibility fixes

[bronius]

Summary

While we intended to replace this docs site with something other than mdbook, for now, it is difficult or impossible to introduce modern plugins/preprocessors (like mermaid), and we have AI.

This PR upgrades the site content and github workflows from mdBook 0.4.x to mdBook 0.5.x and brings the custom TAMU theme fully in line with the new HTML output structure, JavaScript API, and CSS conventions introduced in 0.5.

My goal was to preserve all previous look-and-feel and content without introducing anything new. In the end, we got some standardizations and cleanup, and I am really pleased with how it turned out:

PR preview:
https://docs.cloud.tamu.edu/pr-preview/pr-58/index.html

Original:
https://docs.cloud.tamu.edu/index.html

---

What changed

book.toml

• Bumped [book] / tool config for 0.5.x compatibility
• Removed mdbook-admonish preprocessor (replaced by native [!NOTE] / [!WARNING] / [!TIP] / [!IMPORTANT] block-quote syntax)

theme/index.hbs

• Replaced FontAwesome <i class="fa fa-*"> icon tags (font not bundled in 0.5.x) with {{fa "solid" "..."}} SVG helper calls for hamburger, theme-picker, and search buttons
• Fixed initial-sidebar-visibility script: now uses window.innerWidth (reliable at parse time) instead of document.body.clientWidth (unreliable before layout), and correctly defaults to hidden on narrow viewports
• Fixed active-page expansion: replaced a previousElementSibling walk (wrong element) with a proper ancestor walk up to #sidebar, marking every li.chapter-item expanded
• Excluded .chapter-fold-toggle from link-rewriting and active-detection query selectors (it's an <a> tag but not a navigation link)

theme/book.js

• Fixed fold-toggle click handler: now uses .closest('li.chapter-item') instead of .parentElement (which stopped at span.chapter-link-wrapper, never toggling the right element)
• Fixed themes() IIFE stylesheet selectors: changed [href$='ayu-highlight.css'] ("ends-with") to [href*='ayu-highlight'] ("contains") — mdBook 0.5.x hashes all output asset filenames (e.g. ayu-highlight-3fdfc3ac.css), so exact-suffix selectors always returned null, causing a TypeError that crashed the entire <script> block and prevented the sidebar() IIFE from ever running
• Added combined selector for both legacy a.toggle and new-style a.chapter-fold-toggle for fold events

theme/css/chrome.css

• Fixed #menu-bar selector (was #mdbook-menu-bar — that ID does not exist in any mdBook template)
• Changed .chapter li { display: flex } → display: block with .chapter-link-wrapper { display: flex } so chapter items stack vertically instead of rendering in a horizontal row
• Fixed collapse selector from .chapter li:not(.expanded) + li > ol (wrong: targeted a sibling's child) to .chapter li:not(.expanded) > ol (correct: hides own direct child <ol>)
• Added .fa-svg svg { width: 1em; height: 1em; fill: currentColor } so {{fa}} SVG icons are sized and visible
• Added flex: 0 0 auto / margin-left: auto on fold-toggle anchors so the ❱ arrow stays right-aligned and doesn't stretch

theme/css/aggie-custom.css

• Minor selector and specificity updates for 0.5.x HTML output

README.md

• Updated contributing docs: replaced mdbook-admonish fence-block examples with native [!NOTE] block-quote syntax

src/cloud/azure/azure_network.md (new)

• New Azure networking overview page documenting TAMU hub-and-spoke VNet topology with Mermaid diagram
• Not yet wired into src/SUMMARY.md — needs a follow-up to add it under Cloud Computing Providers → Azure (or similar)

src/kion/ and src/cloud/ content files

• Converted remaining mdbook-admonish fences to native admonition syntax
• Minor prose and formatting updates

---

Landmines to know before reviewing

1. mdBook asset filename hashing: 0.5.x content-hashes ALL output CSS/JS files. Any code that queries [href$='something.css'] or [src$='something.js'] will silently return null. Use *= (contains) instead of $=. We hit this hard with themes().

2. themes() crash cascades silently: Because themes() and sidebar() are both IIFEs in the same compiled <script> block, a thrown exception in themes() kills sidebar() too — no click handler, no hamburger toggle, no responsive hide. Symptom: button renders but does nothing.

3. chapter-fold-toggle is an <a> tag: mdBook 0.5.x wraps each collapsible TOC item as <li><span class="chapter-link-wrapper"><a href="...">Title</a><a class="chapter-fold-toggle">❱</a></span><ol>...</ol></li>. The toggle anchor lives inside a <span>, not directly in the <li> — .parentElement from the toggle gets you the span, not the li. Must use .closest('li.chapter-item').

4. search() in searcher.js still has a null-addEventListener error: initSearchInteractions tries to attach a listener to an element that doesn't exist on pages without a search bar. Non-fatal, but noisy in console. Not addressed in this PR.

5. /css/variables.css 404: The hashed chrome-*.css has an @import url('/css/variables.css') that 404s because the path is absolute and the file is served at a hashed path. Also non-fatal (variables are inlined), but worth cleaning up in a follow-up.

6. src/cloud/azure/azure_network.md is orphaned: New file, not in SUMMARY.md, not built into the book. Intentionally left for a follow-up; noted here so a reviewer doesn't miss it.

---

Hat-tip (well-deserved, obviously)

A very special, completely unsolicited round of applause for the human on this team — who, against all odds, noticed things. Groundbreaking stuff.

Specifically:

• "Hamburger icon shows but doesn't affect sidebar menu toggle" — Your eagle-eyed observation that a button renders but does nothing led us directly to the themes() IIFE crash, which was silently killing sidebar() and leaving the entire interactive layer dead. Without that nudge, we'd have shipped a beautiful, completely static sidebar.

• "Sidebar menu isn't initially hidden on below-the-break" — You caught that the responsive hide wasn't working, which confirmed the JS wasn't running at all, which confirmed the crash theory. Two bugs, one observation. Efficiency.

So yes: the AI wrote code, the AI broke code, the AI fixed the code it broke, and you watched carefully enough to notice the parts that were still broken. That's called pair programming, and it absolutely counts. High five. 🖐️

---

Testing

• mdbook build — clean, no errors
• mdbook serve --port 3002 — site loads, sidebar renders correctly
• Hamburger button toggles sidebar-visible ↔ sidebar-hidden on <html> (verified via Playwright)
• Initial sidebar state: hidden on narrow viewports (window.innerWidth < 1080), visible (or restored from localStorage) on wide viewports
• Fold toggles (❱) correctly expand/collapse their own li.chapter-item
• Active page is highlighted and its ancestor sections are auto-expanded on load
• Theme-picker button opens the theme list (not verified post-fix but no longer crashes)

Also

So I hope it is appreciated.

Resolves #57

[github-actions]

PR Preview Action v1.6.3
🚀 View preview at https://tamu-edu.github.io/it-cloud-docs/pr-preview/pr-58/
Built to branch gh-pages at 2026-06-02 20:12 UTC. Preview will be ready when the GitHub Pages deployment is complete.