feat(docs): migrate documentation site from Docus to Nimbus by amondnet · Pull Request #43 · pleaseai/code-style

amondnet · 2026-10-12T09:15:07Z

Summary

Moves the docs site from docs/ (Docus/Nuxt) to apps/docs/ (Cloudflare Nimbus on Astro 7, static output). It deploys to the existing Cloudflare Pages project pleaseai-code-style. The rationale and trade-offs are in docs/adr/0003-migrate-docs-to-nimbus.md, which supersedes ADR-0001 and ADR-0002.

Changes

Migrated all 20 en/ko pages from MDC to MDX, with no prose changes.
Wired Astro i18n by hand: prefixed /en and /ko, / redirects to /en, language switcher, hreflang, per-locale sidebar and Pagefind search.
Used file-style URLs (build.format: 'file', trailingSlash: 'never'), so every existing URL is preserved.
Dropped D1, nodejs_compat, and the NUXT vars from wrangler.jsonc.
Pinned Nimbus dependencies exactly: @cloudflare/nimbus-docs 0.17.0 and astro 7.3.1.
Set root workspaces to packages/* and apps/*; the docs:* scripts now point at apps/docs.
Enabled ESLint astro: true, ignoring the vendored components/ui/** and DocsLayout.astro.
Added agent outputs: /llms.txt, /llms-full.txt, /{en,ko}/llms.txt, and per-page .md/.mdx.
Redirected /sitemap.xml to /sitemap-index.xml.
Updated CLAUDE.md and CONTRIBUTING.md.

Verification

bun run build, bun run lint, and bun run test pass (237 CLI tests, 3 ast-grep-config tests).
astro check reports 0 errors, and lint:docs reports 20 files clean.
astro preview returns 200 for /, /en, /ko, /en/cli, /ko/cli, /en/eslint-config, and /llms.txt.
/cli stays 404, as it does today.

Deployment action required (maintainer)

In the Cloudflare Pages dashboard, set the root directory to apps/docs, the build command to bun run build, and the output directory to dist. Optionally delete the now-unused D1 database pleaseai-code-style-db. The Cloudflare Pages check on this PR may fail until the build settings are updated.

Known follow-ups

Nimbus UI chrome strings stay English on Korean pages.
Old Docus /raw/<locale>/*.md paths now return 404. The new path is /<locale>/<page>/index.md.
.mdx files are covered by lint:docs, not root ESLint.

Related issue

None.

Checklist

PR title follows Conventional Commits
Packages build (bun run build)
Lint/format pass (bun run lint)
Documentation updated if behavior changed
No breaking change, or a BREAKING CHANGE: note is included

Summary by cubic

Migrates the documentation site from docs/ (Docus/Nuxt) to apps/docs/ (Nimbus on Astro 7, static output) while preserving every existing URL. The site deploys to the existing Cloudflare Pages project pleaseai-code-style, and ADR-0003 supersedes ADR-0001 and ADR-0002.

Changes

Migrated all 20 en/ko pages from MDC to MDX with no prose changes.
Hand-wired Astro i18n: /en and /ko prefixes, / redirects to /en, language switcher, hreflang, per-locale sidebar and Pagefind search.
Used file-style URLs so every existing URL stays live; /sitemap.xml now redirects to /sitemap-index.xml.
Dropped the D1 binding, nodejs_compat, and NUXT vars from wrangler.jsonc and pinned Nimbus dependencies exactly.
Added agent outputs (/llms.txt, /llms-full.txt, per-locale llms.txt, per-page .md/.mdx) and enabled ESLint for Astro sources.
Localized Aside, pagination, search dialog, and search load-error strings via a shared ui table; remaining Nimbus chrome stays English on Korean pages, and old /raw/<locale>/*.md paths now return 404.

Deployment

In Cloudflare Pages, set the root directory to apps/docs, the build command to bun run build, and the output directory to dist.
Optionally delete the now-unused D1 database; the Pages check may fail until build settings are updated.

^{Written for commit a464514. Summary will update on new commits.}

Move the docs site from docs/ (Docus on Nuxt) to apps/docs/, a Nimbus (Astro 7) static site deployed to the existing Cloudflare Pages project. - Migrate all 20 en/ko pages from MDC to MDX with Nimbus components - Wire Astro i18n routing by hand: prefixed /en and /ko URLs, / redirects to /en, language switcher, hreflang alternates, per-locale sidebar/search - Keep file-style URLs (build.format: file) so every live URL still works - Drop the D1 binding, nodejs_compat and NUXT_* vars from wrangler.jsonc - Lint Astro sources via pleaseai({ astro: true }); ignore vendored UI - Add ADR-0003 superseding ADR-0001 and ADR-0002; update CLAUDE.md

socket-security · 2026-10-12T09:15:51Z

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	@iconify-json/ph@1.2.2
	@astrojs/check@0.9.10
	clsx@2.1.1
	@astrojs/language-server@2.16.13
	@fontsource-variable/jetbrains-mono@5.3.0
	@fontsource-variable/inter@5.3.0
	pagefind@1.5.2
	astro@7.3.1
	astro-eslint-parser@1.4.0
	canvaskit-wasm@0.41.1
	eslint-plugin-astro@1.7.0
	astro-og-canvas@0.13.2
	@cloudflare/nimbus-docs@0.17.0

View full report

codacy-production · 2026-10-12T09:16:21Z

Not up to standards ⛔

🔴 Issues 3 critical · 45 high · 12 medium · 7 minor

Alerts:
⚠ 67 issues (≤ 0 issues of at least minor severity)

Results:
67 new issues

Category Results

Compatibility 7 minor

ErrorProne 12 medium
26 high

Security 3 critical
19 high

View in Codacy

🟢 Metrics 454 complexity · 0 duplication

Metric Results

Complexity 454

Duplication 0

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer}
_{TIP This summary will be updated as you push new changes.}

gemini-code-assist

Code Review

This pull request migrates the documentation site from Docus (Nuxt) to Nimbus (Astro 7 + Tailwind v4) in apps/docs/, transitioning it to a fully static build deployed on Cloudflare Pages. It introduces a comprehensive set of UI components, configures Astro's built-in i18n routing for English and Korean locales, and updates the MDX content to use the new components. Feedback on the changes highlights a high-severity security concern regarding custom regex-based HTML sanitization in the Banner component, advising the use of a standard library like DOMPurify. Additionally, several medium-severity localization improvements are requested to avoid hardcoded English strings in the Aside, Pagination, and SearchDialog components by leveraging the locale utilities.

cubic-dev-ai

All reported issues were addressed across 152 files

Architecture diagram

sequenceDiagram
    participant Dev as Developer
    participant Turbo as Turborepo (Root)
    participant Docs as Nimbus Docs (apps/docs)
    participant Astro as Astro 7 Build
    participant Pages as Cloudflare Pages
    participant CDN as Edge/CDN
    participant Browser as User Browser
    participant Agent as AI Agents

    Note over Dev,Pages: Build Time Flow

    Dev->>Turbo: bun run build (workspaces: packages/*, apps/*)
    Turbo->>Docs: Trigger astro build (output: static)
    
    Note over Docs: Source: src/content/docs/{en,ko}/*.mdx
    
    Docs->>Astro: Process MDX via Nimbus (Sätteri)
    Astro->>Astro: Apply i18n routing (/en, /ko prefixes)
    Astro->>Astro: Generate file-style URLs (en/cli.html)
    Astro->>Astro: Build Pagefind search index (per-locale)
    Astro->>Astro: Generate llms.txt, llms-full.txt, per-page .md/.mdx
    
    Note over Astro: Sidebar scoped per locale (scope: 'section')
    
    Astro-->>Docs: dist/ output
    Docs->>Pages: wrangler pages deploy (project: pleaseai-code-style)

    Note over Pages,CDN: Runtime Request Flow

    Browser->>CDN: GET / (no locale prefix)
    CDN->>Pages: Serve meta-refresh to /en
    Pages-->>Browser: 302/meta-refresh to /en
    Browser->>CDN: GET /en/cli
    CDN->>Pages: Serve en/cli.html (200)
    
    alt Locale-specific page
        Browser->>CDN: GET /ko/cli
        CDN->>Pages: Serve ko/cli.html (200)
    end
    
    alt Sitemap request
        Browser->>CDN: GET /sitemap.xml
        CDN->>Pages: _redirects rule (301 to /sitemap-index.xml)
    end

    Browser->>CDN: GET /llms.txt
    CDN-->>Browser: Plain text index for AI consumption

    Note over Browser: Client-side interactivity (after hydration)
    
    Browser->>Browser: Language switcher (full reload, data-astro-reload)
    Browser->>Browser: Pagefind search (per-<html lang> index)
    Browser->>Browser: Theme toggle (localStorage: ui-mode)
    Browser->>Browser: Sidebar filter/persistence (sessionStorage)

    Agent->>CDN: GET /llms.txt (AI discovery)
    Agent->>CDN: GET /en/cli/index.md (per-page markdown)
    CDN-->>Agent: Markdown content for AI consumption

    Note over CDN: Static hosting only - no D1, no nodejs_compat, no server runtime

_{Reply with feedback, questions, or to request a fix.

Turn on auto-fix | Re-trigger cubic}

greptile-apps · 2026-10-12T12:24:46Z

Confidence Score: 5/5

[Medium impact] The PR appears safe to merge, with the documented Cloudflare Pages settings required before deployment.

Summary

Moves the documentation site from Docus in docs/ to static Nimbus/Astro pages in apps/docs/.

The docs site now runs as a static Nimbus and Astro app.
Readers can switch languages and use language-specific docs navigation.
Agents can get a full or per-page text version of the docs.
English and Korean documentation pages now live as MDX in the Astro app.
Workspace commands and linting now point to the Astro docs app.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A["English and Korean MDX pages"] --> B["Nimbus + Astro static build"]
  B --> C["HTML pages and locale navigation"]
  B --> D["Pagefind search indexes"]
  B --> E["Markdown and llms.txt outputs"]
  C --> F["apps/docs/dist"]
  D --> F
  E --> F
  F --> G["Cloudflare Pages"]

_{Reviews (4) · Last reviewed commit: "ci: retrigger Cloudflare Pages build" · Reviewed by Greptile}

- Localize Aside labels, pagination and search dialog strings through the shared ui table in src/i18n/locales.ts - Point docs pages at their locale's llms.txt index - Normalize the current slug with toPagePath in [...slug].astro - Fix Nimbus CLI invocation and locale guidance in CLAUDE.md and AGENT.md - Reference superseded ADR files and add a date to ADR-0003

cloudflare-workers-and-pages · 2026-10-12T12:26:43Z

Deploying code-style with Cloudflare Pages

Latest commit:	`a464514`
Status:	✅ Deploy successful!
Preview URL:	https://ea12c888.code-style.pages.dev
Branch Preview URL:	https://feat-docs-nimbus.code-style.pages.dev

View logs

amondnet · 2026-10-12T12:26:53Z

/gemini review

cubic-dev-ai

All reported issues were addressed across 12 files (changes from recent commits).

_{Reply with feedback, questions, or to request a fix.

Turn on auto-fix | Re-trigger cubic}

gemini-code-assist

Code Review

This pull request migrates the documentation site from Docus (Nuxt) to Nimbus (Astro), restructuring the documentation infrastructure into the apps/docs/ directory and removing the legacy docs/ directory. The reviewer identified a high-severity security vulnerability in the new Banner.astro component regarding insecure regex-based HTML sanitization, recommending the use of a robust sanitization library or refactoring to use slots to prevent potential Cross-Site Scripting (XSS) attacks.

# Conflicts: # CLAUDE.md # bun.lock # docs/package.json # package.json

sonarqubecloud · 2026-10-12T17:27:27Z

Quality Gate passed

Issues
29 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

gemini-code-assist Bot reviewed Oct 12, 2026

View reviewed changes

amondnet marked this pull request as ready for review October 12, 2026 12:14

cubic-dev-ai Bot reviewed Oct 12, 2026

View reviewed changes

greptile-apps Bot reviewed Oct 12, 2026

View reviewed changes

Comment thread apps/docs/src/components/ui/code-group/CodeGroup.astro

Comment thread apps/docs/src/styles/prose.css

Comment thread apps/docs/src/components/ui/search/search.client.ts

amondnet mentioned this pull request Oct 12, 2026

docs: track upstream Nimbus starter defects flagged on #43 #46

Open

cubic-dev-ai Bot reviewed Oct 12, 2026

View reviewed changes

Comment thread apps/docs/src/i18n/locales.ts

Comment thread apps/docs/src/components/ui/search/SearchDialog.astro

gemini-code-assist Bot reviewed Oct 12, 2026

View reviewed changes

Comment thread apps/docs/src/components/ui/banner/Banner.astro

amondnet added 3 commits October 12, 2026 21:35

chore(docs): localize pagination landmark and search load error

de4e714

Merge remote-tracking branch 'origin/main' into feat/docs-nimbus

67d46b2

# Conflicts: # CLAUDE.md # bun.lock # docs/package.json # package.json

ci: retrigger Cloudflare Pages build

a464514

amondnet merged commit d39eb6d into main Oct 12, 2026
12 of 13 checks passed

amondnet deleted the feat/docs-nimbus branch October 12, 2026 17:35

amondnet mentioned this pull request Oct 13, 2026

docs: correct Cloudflare Pages project name and root redirect #47

Merged

4 of 5 tasks

Conversation

amondnet commented Oct 12, 2026 • edited by cubic-dev-ai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Verification

Deployment action required (maintainer)

Known follow-ups

Related issue

Checklist

Summary by cubic

Uh oh!

socket-security Bot commented Oct 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codacy-production Bot commented Oct 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Not up to standards ⛔

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

greptile-apps Bot commented Oct 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Confidence Score: 5/5

Summary

Diagram

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cloudflare-workers-and-pages Bot commented Oct 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying code-style with Cloudflare Pages

Uh oh!

amondnet commented Oct 12, 2026

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

sonarqubecloud Bot commented Oct 12, 2026

Quality Gate passed

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

amondnet commented Oct 12, 2026 •

edited by cubic-dev-ai Bot

Loading

socket-security Bot commented Oct 12, 2026 •

edited

Loading

codacy-production Bot commented Oct 12, 2026 •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

greptile-apps Bot commented Oct 12, 2026 •

edited

Loading

cloudflare-workers-and-pages Bot commented Oct 12, 2026 •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading