feat: migrate to nimbus 🧹

.github/dependabot.yml

@@ -16,11 +16,10 @@ updates:
         patterns:
           - "astro"
           - "@astrojs/*"
-          - "starlight-*"
-      expressive-code:
+          - "@cloudflare/nimbus-docs"
+      docs-search:
         patterns:
-          - "@expressive-code/*"
-          - "*expressive-code*"
+          - "pagefind"
       eslint:
         patterns:
           - "eslint"

.github/workflows/ci.yaml

@@ -24,30 +24,20 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
 
       - name: Setup Node
         uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version-file: ".nvmrc"
           cache: npm
 
-      - name: Run rumdl
-        uses: rvben/rumdl@a7a8434abe60f64239ea05624885f9bad66a1026 # v0.2.79
-        with:
-          version: 0.2.9
-          path: "."
-          fail-on-error: true
+      - name: Setup npm
+        run: npm install --global npm@12.1.0
 
       - name: Install dependencies
         run: npm ci
 
-      - name: Run Check
-        run: npm run check
-
-      - name: Run linter
-        # npm run lint includes lint:markdown which is already handled bby the rumdl
-        # step above
-        run: npm run lint:src
-
-      - name: Run linkcheck
-        run: npm run linkcheck
+      - name: Validate
+        run: npm run validate

.github/workflows/codeql.yml

@@ -41,6 +41,9 @@ jobs:
           node-version-file: ".nvmrc"
           cache: npm
 
+      - name: Setup npm
+        run: npm install --global npm@12.1.0
+
       - name: Install dependencies
         run: npm ci
 

.gitignore

@@ -4,6 +4,7 @@ dist/
 
 # generated types
 .astro/
+.nimbus/
 
 # dependencies
 node_modules/

.prettierignore

@@ -2,7 +2,8 @@ dist/
 .rumdl_cache/
 .wrangler/
 .astro/
-# css files are linted by biome
-**/*.css
+.nimbus/
 openapi.yaml
 openapi.json
+# Imported verbatim from the pinned upstream skills tree.
+skills/

.rumdl.toml

@@ -1,4 +1,6 @@
 [global]
+# Imported upstream content is maintained in sumup-skills.
+exclude = ["skills/**"]
 # Keep legacy long lines and preserve alignment in code examples.
 disable = ["MD013", "MD034", "MD064"]
 

AGENTS.md

@@ -2,20 +2,21 @@
 
 ## Project Structure & Organization
 
-The portal uses Astro with the Starlight theme. Application source sits in `src/`, with `pages/` for route entry points, `content/` for MDX docs, `components/` for reusable UI (React, Astro, and Circuit UI), and `utils/`/`lib/` for shared logic. Assets live in `src/assets` and `public/`. Build outputs go to `dist/`. Configuration resides in `astro.config.ts`, `ec.config.mjs`, and `wrangler.jsonc`; adjust them when adding new content types or deployment targets. API documentation is based on `openapi.yaml`, this file is synchronized from outside this repository, do not edit it.
+The portal uses Astro with Nimbus. Application source sits in `src/`, with `pages/` for route entry points, `content/` for MDX docs, `layouts/` and `components/` for repository-owned UI (React, Astro, and Circuit UI), and `utils/`/`lib/` for shared logic. Assets live in `src/assets` and `public/`. Build outputs go to `dist/`. Configuration resides in `astro.config.ts`, `nimbus.json`, and `wrangler.jsonc`; adjust them when adding new content types or deployment targets. API documentation is based on `openapi.yaml`, this file is synchronized from outside this repository, do not edit it.
 
 ## Build, Test, and Development Commands
 
 - `npm run dev` — watch mode with Hot Module Reloading; use when authoring docs or components.
 - `npm run build` — production Astro build targeting Cloudflare; ensure it succeeds before merging.
-- `npm run check` — runs `astro check` for type and content schema validation after `astro sync`.
-- `npm run lint` — ESLint across Astro/TSX files; required before pushing structural changes.
-- `npm run format` — Prettier write for source and content; run after bulk edits.
-- `npm run linkcheck` — builds with `CHECK_LINKS=true` to surface broken internal/external links.
+- `npm run check` — runs `astro check` for Astro, TypeScript, and content schema validation.
+- `npm run lint` — runs ESLint and `rumdl`; required before pushing structural changes.
+- `npm run format` — formats source, styles, and data files with Prettier.
+- `npm run linkcheck` — builds, runs Nimbus's internal-link checks, and validates rendered API links.
+- `npm run validate` — runs the complete CI validation sequence.
 
 ## Coding Style & Naming Conventions
 
-Prettier (project defaults) handles whitespace, so commit formatted files rather than manual styling. Stick to TypeScript where possible; Astro islands may embed React components. Name components and directories in PascalCase (`src/components/LogoSlider`), utility modules in camelCase (`src/utils/formats.ts`), and content files in kebab-case (`src/content/docs/payments-overview.mdx`). Favor SumUp design tokens and Circuit UI primitives; extend `src/base.css` sparingly.
+Prettier (project defaults) handles whitespace, so commit formatted files rather than manual styling. Stick to TypeScript where possible; Astro islands may embed React components. Name components and directories in PascalCase (`src/components/LogoSlider`), utility modules in camelCase (`src/utils/formats.ts`), and content files in kebab-case (`src/content/docs/payments-overview.mdx`). Favor SumUp design tokens and Circuit UI primitives; extend `src/styles/portal.css` and `src/styles/prose.css` sparingly. Do not add Tailwind.
 
 ## Docs Frontmatter Requirements
 
@@ -40,7 +41,7 @@ For files in `src/content/docs/`, include frontmatter at the top of every page.
 
 ## Testing Guidelines
 
-CI relies on `npm run check`. When editing MDX content, preview via `npm run dev` to verify navigation, sidebar ordering, and snippet rendering. There is no Jest-style test suite; document any manual verification steps in the pull request if behavior changes or APIs are added.
+CI runs `npm run validate`. When editing MDX content, preview via `npm run dev` to verify navigation, sidebar ordering, and snippet rendering. The repository has a focused Vitest suite for runtime helpers; document any additional manual verification steps in the pull request when UI behavior changes.
 
 ## Markdown Linting Guidelines
 

CONTRIBUTING.md

@@ -1,7 +1,7 @@
 # Contributing
 
-SumUp Developer portal built using [Starlight](https://starlight.astro.build/), a documentation theme built on top of [Astro](https://astro.build/). Our theme is modified to rely on SumUp's design system - [Circuit UI](https://github.com/sumup-oss/circuit-ui) - wherever possible.
+SumUp Developer portal is built with [Nimbus](https://nimbus-docs.com/), a documentation framework for [Astro](https://astro.build/). The repository owns its visible components and plain CSS, using SumUp's [Circuit UI](https://github.com/sumup-oss/circuit-ui) design system wherever possible. Tailwind is not used.
 
 ## Codeblocks
 
-Codeblocks are rendered using [Expressive Code](https://expressive-code.com/), the configuration can be found in `./ec.config.mjs`.
+Code blocks are highlighted by Nimbus's Shiki pipeline. Site-wide docs behavior is configured in `astro.config.ts`; visible layouts and styles live in `src/layouts/`, `src/components/nimbus/`, and `src/styles/`.

README.md

@@ -7,7 +7,7 @@
 [![License](https://img.shields.io/github/license/sumup/sumup-developer)](./LICENSE)
 [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v2.1%20adopted-ff69b4.svg)](https://github.com/sumup/sumup-developer/tree/main/CODE_OF_CONDUCT.md)
 
-The SumUp Developer Portal documents the integrations, SDKs, and public APIs that external developers use to build payment-acceptance solutions. The site is built with [Astro](https://astro.build/) and the [Starlight](https://starlight.astro.build/) documentation theme. Documentation pages are written in Markdown and MDX.
+The SumUp Developer Portal documents the integrations, SDKs, and public APIs that external developers use to build payment-acceptance solutions. The site is built with [Astro](https://astro.build/) and [Nimbus](https://nimbus-docs.com/). Documentation pages are written in Markdown and MDX, while the visible theme uses plain CSS and SumUp's Circuit UI design tokens.
 
 </div>
 
@@ -16,7 +16,7 @@ The SumUp Developer Portal documents the integrations, SDKs, and public APIs tha
 ### Prerequisites
 
 - Node.js 24.x, as specified in `.nvmrc` and `package.json`
-- npm 11.x
+- npm 12.x
 
 Using a Node version manager such as [nvm](https://github.com/nvm-sh/nvm) makes it easier to use the version required by the repository.
 
@@ -63,9 +63,59 @@ Run the checks that match your change before opening a pull request:
 | `npm run test`      | Run the Vitest test suite                       |
 | `npm run build`     | Create the production Cloudflare build          |
 | `npm run linkcheck` | Build the site and validate internal links      |
+| `npm run validate`  | Run the complete CI validation sequence         |
 
 ## API Specs
 
 The OpenAPI definition used by the [API Reference](https://developer.sumup.com/api/) is managed in another repository and synchronized into `openapi.yaml`. Do not edit this file directly. If you find a mistake or have an improvement to suggest, [open an issue](https://github.com/sumup/sumup-developer/issues/new).
 
 [docs-badge]: https://img.shields.io/badge/SumUp-documentation-white.svg?logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgY29sb3I9IndoaXRlIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPgogICAgPHBhdGggZD0iTTIyLjI5IDBIMS43Qy43NyAwIDAgLjc3IDAgMS43MVYyMi4zYzAgLjkzLjc3IDEuNyAxLjcxIDEuN0gyMi4zYy45NCAwIDEuNzEtLjc3IDEuNzEtMS43MVYxLjdDMjQgLjc3IDIzLjIzIDAgMjIuMjkgMFptLTcuMjIgMTguMDdhNS42MiA1LjYyIDAgMCAxLTcuNjguMjQuMzYuMzYgMCAwIDEtLjAxLS40OWw3LjQ0LTcuNDRhLjM1LjM1IDAgMCAxIC40OSAwIDUuNiA1LjYgMCAwIDEtLjI0IDcuNjlabTEuNTUtMTEuOS03LjQ0IDcuNDVhLjM1LjM1IDAgMCAxLS41IDAgNS42MSA1LjYxIDAgMCAxIDcuOS03Ljk2bC4wMy4wM2MuMTMuMTMuMTQuMzUuMDEuNDlaIiBmaWxsPSJjdXJyZW50Q29sb3IiLz4KPC9zdmc+
+
+## Documentation for agents
+
+Nimbus publishes `/llms.txt`, section indexes, `/llms-full.txt`, and an
+`index.md` alternate for each guide. The index also links to `/openapi.json`,
+which publishes the synchronized API contract without modifying it.
+
+Keep reference tables in Markdown. `SearchableTable.astro` adds browser filtering
+without hiding the source data from agents or requiring JavaScript to read it.
+Project components that generate content use `src/lib/markdownComponents.ts`;
+shared data drives both their HTML and Markdown representations.
+Every component used in docs must have a renderer or an explicit preservation
+policy in that module. Agent validation checks component coverage and compares
+rendered code blocks, including generated examples, with both Markdown outputs.
+Bump a renderer's revision when its output logic changes; generated renderers
+should include their source data in the revision to invalidate cached output.
+
+`npm run check:agent-docs` checks the built output against every authored code
+example and verifies the full bundle, canonical URLs, and API contract. It runs
+as part of `npm run validate`. Nimbus owns Markdown conversion, sitemap dates,
+and skill archive generation. The postbuild
+discovery step adds our OpenAPI and MCP routes to Nimbus's generated catalogs.
+Nimbus owns discovery-file CORS and content types. Keep owner header rules
+disjoint from those generated rules: Cloudflare combines overlapping values.
+Agent validation rejects duplicated CORS/content types in the built output.
+
+`npm run check:redirects` validates every explicit redirect destination and
+fragment, including rules unused by current pages, and rejects duplicate sources,
+loops, and static rules after dynamic rules. It runs in `npm run linkcheck`.
+Remove redirects for retired endpoints without a documented replacement instead
+of pointing them at an unrelated API operation.
+
+With Nimbus 0.18 and our Cloudflare/Node development environment, Markdown
+alternates remain cached after content edits. Restart the dev server to refresh
+them. HTML changes refresh normally; production builds regenerate all alternates.
+
+Skills are imported verbatim from the commit in `agent-skills.source.json`.
+Run `npm run sync:agent-skills` to reproduce them, or add
+`-- --source /path/to/sumup-skills` to use an existing Git checkout offline.
+The command reads the pinned Git tree and ignores uncommitted source edits.
+To publish an upstream change, review and update the pinned revision, sync, and
+commit the lock and imported `skills/` files together. Builds need no source
+checkout or network access: Nimbus packages the checked-in sources into
+deterministic archives and publishes their discovery index and SHA-256 digests.
+
+Security overrides: Satori's `fflate` is pinned to 0.8.3 for the ZIP64 fix;
+Mermaid's KaTeX is pinned to 0.18.2 for its trust-handling fix, until Mermaid's
+supported dependency range includes a patched release. Validate Mermaid diagrams
+when updating that override.

agent-skills.source.json

@@ -0,0 +1,4 @@
+{
+  "repository": "https://github.com/sumup/sumup-skills.git",
+  "revision": "6922c7052ae9d0be834f27361b785bd80e0829cc"
+}