[marc0olo]

Summary

Replaces #337 (dependabot), which could not merge as-is: Astro 7 / Starlight 0.41 need repo-side changes. Dependabot's bump commit is preserved here, with the required fixes on top.

• astro 6.3.2 → 7.1.6, @astrojs/starlight 0.38.1 → 0.41.6 (cherry-picked from chore(deps): bump astro and @astrojs/starlight #337)
• Wrap all autogenerate sidebar configs in items arrays (Starlight 0.39 removed labelled autogenerated groups)
• Normalise the sidebar shape in scripts/postprocess-motoko.mjs so synced Motoko pages keep working
• Fix deriveSections() in plugins/astro-agent-docs.mjs so llms.txt keeps its section labels, and make the same class of failure fail the build in future
• Migrate markdown.remarkPlugins / rehypePlugins to processor: unified({ ... })
• Align validate.yml on Node 22

Why the extra changes

Sidebar (build blocker). Starlight 0.39 requires the autogenerate config to sit inside an items array:

  {
    label: "Backends",
    collapsed: true,
-   autogenerate: { directory: "guides/backends" },
+   items: [{ autogenerate: { directory: "guides/backends", collapsed: true } }],
  }

collapsed is set on the autogenerate config too, because autogenerated subgroups no longer inherit the parent's collapsed state as of 0.39. No autogenerate directory currently has subdirectories, so this is a no-op today and keeps behaviour correct if one is added.

Motoko sidebar (would regress on the next sync). sidebar-motoko.mjs is generated from doc/site/sidebar.mjs in the pinned .sources/motoko submodule, which still uses the pre-0.39 shape. Hand-editing the generated file alone would be undone by the next Motoko sync, breaking the build again. Instead transformEntry() now normalises both shapes, so the output is valid whichever shape upstream emits and no coordination with caffeinelabs/motoko is required. Verified: both shapes produce byte-identical output, and regeneration is idempotent.

llms.txt (silent break, now guarded). deriveSections() read the section label off the autogenerate node. Once nested, that node is unlabelled and the label lives on the parent group, so all 15 autogenerated sections rendered as ## undefined in llms.txt — with a clean build log and a zero exit code. Beyond fixing the derivation, the derived sections are now validated at module load and the build throws with the offending directory and the function to update. Verified by reintroducing the original bug: the build fails immediately instead of shipping. This guards the whole class of failure, since these labels are inferred from the sidebar's shape and future Starlight majors can change it again.

Markdown processor. Astro 7 defaults to the Sätteri processor and deprecates the top-level plugin arrays (the build warned about it). processor: unified({ ... }) opts back into the remark/rehype pipeline the 5 remark and 2 rehype plugins need. @astrojs/markdown-remark is declared as a direct dependency instead of relying on Astro's transitive copy; only the root dependency entry is added to the lockfile.

Node 22 in validate.yml. Astro 7 requires ^20.19.0 || >=22.12.0. The previous '20' pin resolved to a satisfying 20.x and that job does not run Astro, so this aligns it with the other five workflows rather than fixing a break.

Verification

Built against a main baseline and compared output:

• 209 pages build clean, no errors, no deprecation warnings
• Sidebar identical: 38 groups, same labels, same collapsed states, 196 nav links
• llms.txt, llms-full.txt, feed.xml and all 209 markdown endpoints byte-identical
• Rendered article content identical on 204 of 208 pages; the 4 differences are 3 smart-quote corrections (”Canister is not ready” → “Canister is not ready”) and one whitespace change between flex items in a Starlight LinkCard on the homepage, which does not render
• Confirmed on the deployed preview: the submodule-sourced Motoko pages that use file= includes render in full, and llms.txt is byte-identical to the local build
• Build time 33s → 28s

Notes

• Starlight 0.41 drops support for Chromium < 111 and Safari < 16.4.
• Upstream caffeinelabs/motoko pins Starlight ^0.41.3 in doc/site/package.json while its sidebar.mjs still uses the pre-0.39 shape, and no workflow there builds doc/site, so their own preview site hits this same error unnoticed. Worth a separate upstream PR; this branch does not depend on it.