chore(deps): upgrade documentation dependencies for Astro 7 (DOCSDEV-75) by Infi-Knight · Pull Request #3974 · interledger/rafiki

Infi-Knight · 2026-09-04T19:05:09Z

Summary

Move packages/documentation to Astro 7 and Starlight 0.42, part of the DOCSDEV-75 cycle.

Only packages/documentation/ changes, plus the lockfile.

Code changes

1. Markdown pipeline moves to `unified()`

Astro 7 replaces the remark and rehype pipeline with Satteri, a Rust processor. Satteri cannot
run remark or rehype plugins. This package needs four of them, so the config now wraps them in
the unified() escape hatch from @astrojs/markdown-remark.

2. Remove an unused `Badge` import

signing-admin-api-requests.mdx imported Badge from the design system. The design system
has never exported Badge. Astro 6 tolerated the missing export. Astro 7 fails the build with
[MISSING_EXPORT]. Badge was never used in the file, so the import is gone.

3. Remove six dead `client:load` directives

Two on MermaidWrapper and four on Tooltip, across both locales and both doc versions. Both
are Astro components, so a hydration directive does nothing on them. All six only produced a
build warning.

This is not an Astro 7 regression. Astro 6.3.8 emits the identical warning.

The rendered HTML does not change. I rebuilt and diffed all six pages. Two are byte
identical. The other four differ only in the random UUID that Tooltip.astro generates on
every build, and they are byte identical once that UUID is normalized.

4. Turn on the accessibility rules

eslint-plugin-astro 3 exposes the jsx-a11y rule set, so eslint.config.js now extends
flat/jsx-a11y-recommended.

Result: 34 rules active, 0 findings. The rules are confirmed to run against .astro files,
so the zero is a real result.

Verification

Node 24.18.1, pnpm 10.33.0.

Check	Result
`pnpm --filter documentation run build:docs`	Passes. 174 pages
`starlight-links-validator`	All internal links valid
`pnpm lint:docs`	Passes, `--max-warnings=0`
`pnpm checks` at root	Passes
`pnpm --filter documentation run build:docs:graphql`	Passes. spectaql stays at 3.0.9
Heading anchors and table of contents	Work. 28 wrapped anchors on the accounting page
Math through rehype-mathjax	Renders in both locales
`/llms.txt`, `/llms-full.txt`, `/llms-small.txt`	All generate
Pagefind search	Works
All 35 Mermaid diagrams	35 of 35 render, zero syntax errors
Mermaid view and download buttons	Both work
Header, PageSidebar and Footer overrides	All three render. `Astro.locals.starlightRoute` still works
`expressiveCode` border overrides	Identical to production
Version switcher and `v1-beta` pages	Work. The sidebar stays scoped to the version
Both locales	Work
Console errors	Zero across 8 pages
`compressHTML` default change to `'jsx'`	No visible effect. Rendered text is identical to production on 3 pages, so the option is left at its new default

One thing to know about the lockfile

packages/frontend and localenv/mock-account-servicing-entity each changed exactly one line.
The @remix-run/dev@2.17.5 peer resolution key gained (lightningcss@1.33.0). Astro 7 and
Vite 8 pull lightningcss into the workspace, and vite@6.4.1 declares it an optional peer,
so pnpm folds it into the key.

The installed version of @remix-run/dev does not change. It stays 2.17.5.
Vite uses lightningcss only when css.transformer: 'lightningcss' is set. No config in
either package sets it.

This leak cannot be avoided without adding root pnpm.overrides, which is out of scope here.

Test plan

CI passes
Deploy preview renders, including diagrams, both locales and both doc versions

Move the documentation package to Astro 7 and Starlight 0.42. Dependency changes, documentation package only: - astro ~6.3.8 to ~7.2.10 - @astrojs/starlight ^0.39.2 to ^0.42.0 - @astrojs/markdown-remark ^7.1.2 to ^7.3.0 - @interledger/docs-design-system ^0.13.0 to ^0.14.0 - mermaid ^11.15.0 to ^11.17.2 - starlight-links-validator ^0.24.0 to ^0.26.0 - starlight-llms-txt ^0.9.0 to ^0.11.0 - starlight-versions ^0.9.0 to ^0.10.1 - eslint, prettier, typescript-eslint and globals to current - eslint-plugin-astro and astro-eslint-parser to version 3 - add eslint-plugin-jsx-a11y and turn on the accessibility rules Code changes: - Astro 7 replaces the remark and rehype pipeline with Satteri. Wrap the four existing plugins in the unified() processor from @astrojs/markdown-remark. The plugin order stays the same, so heading anchors still work. - Drop the unused Badge import in signing-admin-api-requests.mdx. The design system never exported Badge. Astro 6 tolerated the missing export. Astro 7 rejects it. - Remove six dead client:load directives from MermaidWrapper and Tooltip. Both are Astro components, so the directive did nothing. It only produced a build warning. The rendered HTML does not change. The root tooling stays on ESLint 8.57 and TypeScript 5.4 on purpose. Only the documentation package moves.

netlify · 2026-09-04T19:05:15Z

✅ Deploy Preview for brilliant-pasca-3e80ec ready!

Name	Link
🔨 Latest commit	`136f051`
🔍 Latest deploy log	https://app.netlify.com/projects/brilliant-pasca-3e80ec/deploys/6aa56da975582e0008a098b5
😎 Deploy Preview	https://deploy-preview-3974--brilliant-pasca-3e80ec.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

github-actions · 2026-09-04T19:10:24Z

🚀 Performance Test Results

Test Configuration:

VUs: 4
Duration: 1m0s

Test Metrics:

Requests/s: 41.67
Iterations/s: 13.89
Failed Requests: 0.00% (0 of 2506)

📜 Logs


> performance@1.0.0 run-tests:testenv /home/runner/work/rafiki/rafiki/test/performance
> ./scripts/run-tests.sh -e test -k -q --vus 4 --duration 1m

Cloud Nine GraphQL API is up: http://localhost:3101/graphql
Cloud Nine Wallet Address is up: http://localhost:3100/
Happy Life Bank Address is up: http://localhost:4100/
cloud-nine-wallet-test-backend already set
cloud-nine-wallet-test-auth already set
happy-life-bank-test-backend already set
happy-life-bank-test-auth already set
     data_received..................: 904 kB 15 kB/s
     data_sent......................: 1.9 MB 32 kB/s
     http_req_blocked...............: avg=7.99µs   min=2.45µs   med=5.74µs   max=778.91µs p(90)=7.16µs   p(95)=8.29µs  
     http_req_connecting............: avg=570ns    min=0s       med=0s       max=727.6µs  p(90)=0s       p(95)=0s      
     http_req_duration..............: avg=95.27ms  min=8.05ms   med=76.18ms  max=452.84ms p(90)=170.9ms  p(95)=193.1ms 
       { expected_response:true }...: avg=95.27ms  min=8.05ms   med=76.18ms  max=452.84ms p(90)=170.9ms  p(95)=193.1ms 
     http_req_failed................: 0.00%  ✓ 0         ✗ 2506
     http_req_receiving.............: avg=102.66µs min=25.8µs   med=88.28µs  max=1.46ms   p(90)=132.01µs p(95)=177.04µs
     http_req_sending...............: avg=42.96µs  min=9.48µs   med=27.21µs  max=2.36ms   p(90)=51.27µs  p(95)=80.78µs 
     http_req_tls_handshaking.......: avg=0s       min=0s       med=0s       max=0s       p(90)=0s       p(95)=0s      
     http_req_waiting...............: avg=95.12ms  min=7.84ms   med=76.05ms  max=452.75ms p(90)=170.79ms p(95)=192.83ms
     http_reqs......................: 2506   41.673493/s
     iteration_duration.............: avg=287.78ms min=179.12ms med=274.84ms max=968.37ms p(90)=359.04ms p(95)=389.59ms
     iterations.....................: 835    13.885621/s
     vus............................: 4      min=4       max=4 
     vus_max........................: 4      min=4       max=4

0.14.0 imports mermaid with a bare specifier. That resolves to a build which expects a bundler to fix the CommonJS interop for dayjs. The Vite dev server does not do that, so the module throws and no diagram renders. Production was never affected. 0.14.1 imports the pre-bundled mermaid build instead. Verified on the dev server, not on astro preview.

Anca2022 · 2026-09-10T09:41:27Z

Same issue you already flagged on WM:

This PR also needs to wait for interledger/docs-design-system v0.14.2 before merging please 😄

Anca2022

Just need to update interledger/docs-design-system to v0.14.2 for the stylistic fix you already flagged.
The rest looks good! 😁

Astro 7 removes the whitespace text node between a sidebar link and its external-link icon. The design system rule declared no spacing of its own, so the icon touched the last letter of the link text. 0.14.2 declares the gap with margin-inline-start. This repo has 320 external sidebar links across 160 of its 174 pages. Verified on the built output: the icon sits 3.5px clear of the text, and all 35 mermaid diagrams still render.

github-actions Bot added the pkg: documentation Changes in the documentation package. label Sep 4, 2026

Infi-Knight self-assigned this Sep 7, 2026

Infi-Knight requested a review from Anca2022 September 9, 2026 10:19

Anca2022 previously approved these changes Sep 10, 2026

View reviewed changes

Infi-Knight dismissed Anca2022’s stale review via 136f051 September 12, 2026 15:20

Infi-Knight requested review from JoblersTune and sidvishnoi September 14, 2026 08:45

mkurapov approved these changes Sep 14, 2026

View reviewed changes

mkurapov merged commit 6fd9e3a into main Sep 14, 2026
38 of 58 checks passed

mkurapov deleted the chore/docsdev-75-rafiki-docs-dep-upgrade branch September 14, 2026 11:10

Navigation Menu

chore(deps): upgrade documentation dependencies for Astro 7 (DOCSDEV-75) - #3974

chore(deps): upgrade documentation dependencies for Astro 7 (DOCSDEV-75)#3974
mkurapov merged 3 commits into
mainfrom
chore/docsdev-75-rafiki-docs-dep-upgrade

Infi-Knight commented Sep 4, 2026 •

edited

Loading

Uh oh!

netlify Bot commented Sep 4, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Sep 4, 2026 •

edited

Loading

Uh oh!

Anca2022 commented Sep 10, 2026 •

edited

Loading

Uh oh!

Anca2022 left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

Infi-Knight commented Sep 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Code changes

1. Markdown pipeline moves to unified()

2. Remove an unused Badge import

3. Remove six dead client:load directives

4. Turn on the accessibility rules

Verification

One thing to know about the lockfile

Test plan

Uh oh!

netlify Bot commented Sep 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for brilliant-pasca-3e80ec ready!

Uh oh!

github-actions Bot commented Sep 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🚀 Performance Test Results

Uh oh!

Anca2022 commented Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Anca2022 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Infi-Knight commented Sep 4, 2026 •

edited

Loading

1. Markdown pipeline moves to `unified()`

2. Remove an unused `Badge` import

3. Remove six dead `client:load` directives

netlify Bot commented Sep 4, 2026 •

edited

Loading

github-actions Bot commented Sep 4, 2026 •

edited

Loading

Anca2022 commented Sep 10, 2026 •

edited

Loading