docs(openspec): update the docs-starlight-preview change

Marks the CI task done after the first green run of the preview workflow and records in the design why the preview needs the js-yaml bundling, the satteri override and the raised pixel limit, and that sharp comes with Astro.

Author: d-biehl

openspec/changes/docs-starlight-preview/design.md

@@ -27,7 +27,7 @@ See proposal.md. The switch of the published site is `migrate-docs-to-starlight`
 
 ### D1: A standalone Astro project in `docs-next/`
 
-`docs-next/` has its own `package.json` and `package-lock.json` with `astro`, `@astrojs/starlight`, `@astrojs/markdown-satteri`, `sharp`, `starlight-blog`, `starlight-links-validator`, `starlight-llms-txt` and `lite-youtube-embed`, plus `js-yaml` and `github-slugger` for the conversion script, pinned to the minors verified during exploration (Astro 7.3, Starlight 0.42), and is not added to the root `workspaces`. `js-yaml` stays on major 4, the one Astro uses, because Astro's prerendered server code resolves `js-yaml` from the project root. An `overrides` entry pins `@astrojs/markdown-satteri` to the direct dependency: the `@astrojs/mdx` 7 that `starlight-blog` brings declares it as a `^0.3` peer, which npm 10 (Node 22, the CI) and npm 12 resolve differently, so without the entry a lockfile written by one fails `npm ci` in the other. A `vite.build.rolldownOptions.onwarn` filter drops rolldown's `MODULE_LEVEL_DIRECTIVE` warning about the `use astro:head-inject` directive Astro 7.3 still prepends to MDX pages but no longer reads (withastro/astro#18087), once per MDX page; the filter goes when the fix is released. Root scripts `docs-next:install|dev|build|preview` call `npm --prefix docs-next …` for convenience. Layout: `astro.config.mjs`, `src/pages/404.astro` (the not-found page, D9), `src/content.config.ts` (with Starlight's optional `i18n` collection; `src/content/i18n/en.json` overrides no UI string but keeps the collection from being empty, which Astro 7 reports as a warning on every build), `scripts/convert.mjs`, `content/` (hand-written pages), `src/components/`, `src/styles/custom.css`, `README.md`; `src/content/docs/`, `src/assets/` and `public/` are generated.
+`docs-next/` has its own `package.json` and `package-lock.json` with `astro`, `@astrojs/starlight`, `@astrojs/markdown-satteri`, `starlight-blog`, `starlight-links-validator`, `starlight-llms-txt` and `lite-youtube-embed`, plus `js-yaml` and `github-slugger` for the conversion script, pinned to the minors verified during exploration (Astro 7.3, Starlight 0.42) and otherwise on their newest versions, and is not added to the root `workspaces`. `sharp` needs no entry: Astro brings it as an optional dependency. `@astrojs/markdown-satteri` is listed because `astro.config.mjs` imports it to set the processor options (D9); Astro has no other setting for them. Starlight imports js-yaml 4 with a default import, and Astro's prerender build keeps that import external, so it would load the `js-yaml` 5 of the conversion script from the project root and fail; `environments.prerender.resolve.noExternal: ["js-yaml"]` bundles it with Starlight's own copy, as Astro does for `neotraverse` (withastro/astro#17508). An `overrides` entry pins `@astrojs/markdown-satteri` to the direct dependency: `starlight-blog` 0.30 still depends on `@astrojs/mdx` 7, which declares it as a `^0.3` peer, and npm 10 (Node 22, the CI) and npm 12 resolve that differently, so without the entry a lockfile written by one fails `npm ci` in the other; the entry goes when `starlight-blog` moves to `@astrojs/mdx` 8. A `vite.build.rolldownOptions.onwarn` filter drops rolldown's `MODULE_LEVEL_DIRECTIVE` warning about the `use astro:head-inject` directive Astro 7.3 still prepends to MDX pages but no longer reads (withastro/astro#18087), once per MDX page; the filter goes when the fix is released. Root scripts `docs-next:install|dev|build|preview` call `npm --prefix docs-next …` for convenience. Layout: `astro.config.mjs`, `src/pages/404.astro` (the not-found page, D9), `src/content.config.ts` (with Starlight's optional `i18n` collection; `src/content/i18n/en.json` overrides no UI string but keeps the collection from being empty, which Astro 7 reports as a warning on every build), `scripts/convert.mjs`, `content/` (hand-written pages), `src/components/`, `src/styles/custom.css`, `README.md`; `src/content/docs/`, `src/assets/` and `public/` are generated.
 
 Rejected: a root workspace — the root `npm install` of every contributor and of the Node-20 CI jobs would pull about 375 more packages and print `EBADENGINE` for Astro; a branch — it would fall behind `docs/` and need regular merges; a one-time copy of the content — see D3.
 
@@ -132,7 +132,7 @@ The April Fools post invents options (`prediction-depth`, `sponsored-keywords`,
 - [Starlight 0.x ships breaking changes in minors (0.38–0.42 each had some); Astro majors came 104 days apart.] → Pinned minors; the copied `Header.astro` is diffed against upstream on upgrades.
 - [Plugins with one npm maintainer (`starlight-blog`, `starlight-links-validator`, `starlight-llms-txt`).] → Each is replaceable by little own code.
 - [Previewers need Node ≥22.12.] → Stated in the README; the current site's tooling is unaffected.
-- [Two 1920×1080 GIFs exceed sharp's pixel limit and are shipped unoptimized (Astro writes the original GIF under a `.webp` name; browsers detect the format and animate it).] → Acceptable; re-encoding them is independent work.
+- [Sharp counts the pixels of all frames of an animated GIF, so the two 1920×1080 screencasts of the home page exceed its default limit.] → `image.service.config.limitInputPixels: false` lets it convert them to animated WebP; that adds about 15 s to a build without image cache and gives files about as large as the GIFs.
 - [`.mdx` pages treat `{` and `<word>` as JSX; a later edit in `docs/` could break one.] → Only pages that need components become `.mdx`; the CI build catches it.
 - [Last-change dates come from git; a shallow clone would give every page the same date.] → The conversion sets them only in full clones; pages of a shallow clone show no date, and the CI build does not need them.
 - [A new page in `docs/` without a page-map entry turns the preview CI red, although the VitePress build passes.] → The failure names the file; CONTRIBUTING.md, AGENTS.md and the tasks of the three changes that plan pages say what to add.

openspec/changes/docs-starlight-preview/proposal.md

@@ -29,7 +29,7 @@ The documentation site is to move from VitePress 1.6.4, whose 1.x line gets no f
 
 ## Impact
 
-- New `docs-next/`: `package.json` and `package-lock.json` (`astro`, `@astrojs/starlight`, `@astrojs/markdown-satteri`, `sharp`, `starlight-blog`, `starlight-links-validator`, `starlight-llms-txt`, `lite-youtube-embed`, `js-yaml`, `github-slugger`), `astro.config.mjs`, `src/content.config.ts`, `scripts/convert.mjs` (page map and rules), `content/` (hand-written pages), `src/components/`, `src/styles/`, `README.md`, `.gitignore` (generated `src/content/docs/` and `src/assets/`, `dist/`, `.astro/`, `node_modules/`).
+- New `docs-next/`: `package.json` and `package-lock.json` (`astro`, `@astrojs/starlight`, `@astrojs/markdown-satteri`, `starlight-blog`, `starlight-links-validator`, `starlight-llms-txt`, `lite-youtube-embed`, `js-yaml`, `github-slugger`), `astro.config.mjs`, `src/content.config.ts`, `scripts/convert.mjs` (page map and rules), `content/` (hand-written pages), `src/components/`, `src/styles/`, `README.md`, `.gitignore` (generated `src/content/docs/` and `src/assets/`, `dist/`, `.astro/`, `node_modules/`).
 - New `.github/workflows/docs-next.yml` (build only). `.github/workflows/build-test-package-publish.yml` (`paths-ignore` gets `docs-next/**`), `.vscodeignore`, `eslint.config.mjs`, root `package.json` (scripts only), `CONTRIBUTING.md` (a short section on the preview), `AGENTS.md` (task routing and commands for `docs-next/`).
 - The documentation tasks of `doc-cli` (7.1), `library-keyword-set-declaration` (5.1) and `library-index` (8.1) get a page-map entry and a preview build check.
 - `docs/03_reference/repl.md` and `docs/03_reference/robot-debug.md`: the two broken anchor links.

openspec/changes/docs-starlight-preview/tasks.md

@@ -2,7 +2,7 @@
 
 ## 1. Project
 
-- [x] 1.1 Create `docs-next/` as a standalone npm project (D1): `package.json` with `astro`, `@astrojs/starlight`, `@astrojs/markdown-satteri`, `sharp`, `starlight-blog`, `starlight-links-validator`, `starlight-llms-txt`, `lite-youtube-embed`, `js-yaml`, `github-slugger` (minors verified during exploration: Astro 7.3, Starlight 0.42, starlight-blog 0.30, starlight-links-validator 0.26, starlight-llms-txt 0.12), the scripts `predev`/`prebuild` (conversion) and `dev`/`build`/`preview` (`astro`), its own `package-lock.json`, `tsconfig.json` from `astro/tsconfigs/strict`, and a `.gitignore` for `node_modules/`, `dist/`, `.astro/`, `.generated/`, `src/content/docs/`, `src/assets/` and `public/`; verify that `npm ci` in `docs-next/` succeeds and that the root `package.json` `workspaces` still lists only `docs`
+- [x] 1.1 Create `docs-next/` as a standalone npm project (D1): `package.json` with `astro`, `@astrojs/starlight`, `@astrojs/markdown-satteri`, `starlight-blog`, `starlight-links-validator`, `starlight-llms-txt`, `lite-youtube-embed`, `js-yaml`, `github-slugger` (minors verified during exploration: Astro 7.3, Starlight 0.42, starlight-blog 0.30, starlight-links-validator 0.26, starlight-llms-txt 0.12), the scripts `predev`/`prebuild` (conversion) and `dev`/`build`/`preview` (`astro`), its own `package-lock.json`, `tsconfig.json` from `astro/tsconfigs/strict`, and a `.gitignore` for `node_modules/`, `dist/`, `.astro/`, `.generated/`, `src/content/docs/`, `src/assets/` and `public/`; verify that `npm ci` in `docs-next/` succeeds and that the root `package.json` `workspaces` still lists only `docs`
 - [x] 1.2 Write `docs-next/astro.config.mjs` and `docs-next/src/content.config.ts` (D2, D5, D6, D7, D9): `site: "https://robotcode.io"`, Sätteri with `smartPunctuation: false` and `headingAttributes: true`, Starlight with title, logo, favicons, Open Graph image via `head`, social links (`github`, `seti:python`, `vscode`, `jetbrains`, `openCollective`), `lastUpdated: true`, table of contents levels 2–4, `customCss` (a stub `src/styles/custom.css` for now), Expressive Code with the Robot grammar from `../syntaxes/robotframework.tmLanguage.json` and the themes `material-theme-darker`/`material-theme-lighter`, the sidebar (`about`, Getting Started/Guides/Reference with `autogenerate`, `contributing`), `starlight-blog` (`prefix: "news"`, `title: "News"`, `navigation: "none"`, the global author), `starlight-links-validator` with the `exclude` of D6, `starlight-llms-txt` with `details` from `.generated/llms-index.md`, and the content schema extended with `blogSchema`; verified by the build in 2.2
 - [x] 1.3 Add skeletons of the hand-written pages in `docs-next/content/` (`index.mdx`, `getting-started/index.mdx` with the requirements marker, `guides/index.mdx`, `reference/index.mdx`) and of the not-found page `src/pages/404.astro`, each with title and description; verified by the build in 2.2
 - [x] 1.4 Add the root scripts `docs-next:install`, `docs-next:dev`, `docs-next:build`, `docs-next:preview` (`npm --prefix docs-next …`); verify each from the repository root once 2.2 builds
@@ -29,7 +29,7 @@
 ## 5. Preview workflow, CI and isolation
 
 - [x] 5.1 Write `docs-next/README.md`, the preview section in `CONTRIBUTING.md` and the `docs-next` entries in `AGENTS.md` (D10); verify that the commands they name work from a fresh clone on Node 22
-- [ ] 5.2 Add `.github/workflows/docs-next.yml` (build only, on changes to `docs/**`, `docs-next/**` and the workflow itself, Node 22, `ASTRO_TELEMETRY_DISABLED=1`) (D10); verify by running its steps locally (`npm ci` and `npm run build` in `docs-next/`) and, once pushed by the maintainer, by a green run
+- [x] 5.2 Add `.github/workflows/docs-next.yml` (build only, on changes to `docs/**`, `docs-next/**` and the workflow itself, Node 22, `ASTRO_TELEMETRY_DISABLED=1`) (D10); verify by running its steps locally (`npm ci` and `npm run build` in `docs-next/`) and, once pushed by the maintainer, by a green run
 - [x] 5.3 Add `docs-next/**` to `paths-ignore` of `build-test-package-publish.yml`, `docs-next/` to `.vscodeignore` and `**/docs-next/` to the ignores of `eslint.config.mjs` (D10); verify that `npx @vscode/vsce ls` lists no file under `docs-next/` and that `npm run lint` does not lint `docs-next/`
 - [x] 5.4 Add the page-map step and a `npm run docs-next:build` check to the documentation tasks of `doc-cli` (7.1), `library-keyword-set-declaration` (5.1) and `library-index` (8.1) (D10); verify with `openspec validate` for each of the three changes