Centralize docs site configuration into single source of truth#1115
Open
r33drichards wants to merge 5 commits intomainfrom
Open
Centralize docs site configuration into single source of truth#1115r33drichards wants to merge 5 commits intomainfrom
r33drichards wants to merge 5 commits intomainfrom
Conversation
Swap Lume and Cua-Bot in the dropdown menu's docsSites array so both the header dropdown and the left sidebar show products in the same order: Cua, Cua Bench, Cua-Bot, Lume. https://claude.ai/code/session_012xmdj4JSbSFBDTUmvKMmfL
Move the docsSites array from custom-header.tsx into a shared config at src/lib/docs-sites.ts. The header component now imports from this config and maps logos onto it. A new sync script generates content/docs/meta.json from the same config, run automatically via prebuild/predev hooks. To change site order or add a new site, edit src/lib/docs-sites.ts — both the dropdown and sidebar will update automatically. https://claude.ai/code/session_012xmdj4JSbSFBDTUmvKMmfL
Contributor
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the Use the checkbox below for a quick retry:
📝 WalkthroughWalkthroughThe changes introduce a centralized documentation sites configuration module and add a synchronization mechanism to generate metadata. A new Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
🧹 Nitpick comments (3)
docs/scripts/sync-docs-meta.ts (2)
1-1: Consider simplifying the shebang.Since
tsxis already a devDependency and the script is invoked viapnpm(which resolves local binaries), thenpxprefix is unnecessary overhead. You could simplify to#!/usr/bin/env tsxor rely solely on the package.json script invocation.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/scripts/sync-docs-meta.ts` at line 1, The shebang in the script currently uses "/usr/bin/env npx tsx"; update it to the simpler "/usr/bin/env tsx" (or remove the shebang and rely on the package.json script) so the script uses the locally installed tsx binary without the unnecessary npx wrapper; change the shebang line at the top of docs/scripts/sync-docs-meta.ts accordingly.
19-19: Consider adding error handling for file write operations.If the
content/docsdirectory doesn't exist (e.g., after a fresh clone or accidental deletion),writeFileSyncwill throw. A defensive check or try-catch with a helpful error message would improve developer experience.🛡️ Proposed fix to add directory check
+import { dirname } from 'node:path'; + const metaPath = path.resolve(__dirname, '..', 'content', 'docs', 'meta.json'); + +// Ensure directory exists +const dir = dirname(metaPath); +if (!fs.existsSync(dir)) { + fs.mkdirSync(dir, { recursive: true }); +} + const meta = {🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/scripts/sync-docs-meta.ts` at line 19, The fs.writeFileSync(metaPath, ...) call can throw if the target directory is missing; before calling fs.writeFileSync ensure the directory exists (e.g., call fs.mkdirSync(path.dirname(metaPath), { recursive: true })) or wrap the write in a try-catch that creates the directory on ENOENT and rethrows/logs a clear error; update the code around the fs.writeFileSync invocation (referencing metaPath and fs.writeFileSync) to perform the directory check/create or add the try-catch with a helpful error message.docs/src/components/custom-header.tsx (1)
24-34: Consider enforcing type alignment betweensiteLogoskeys anddocsSitesConfigslugs.If a new site is added to
docsSitesConfigwithout a corresponding entry insiteLogos, the merged object will haveundefinedlogo properties. While the component handles missing logos gracefully (lines 80, 134), you could catch configuration drift at compile time:💡 Optional: Type-safe slug keys
// In docs-sites.ts, export the slug union: export type DocsSiteSlug = typeof docsSites[number]['slug']; // In custom-header.tsx: import type { DocsSiteSlug } from '@/lib/docs-sites'; const siteLogos: Record<DocsSiteSlug, { logoBlack: typeof LogoBlack; logoWhite: typeof LogoWhite }> = { cua: { logoBlack: LogoBlack, logoWhite: LogoWhite }, // ... TypeScript will error if a slug is missing };🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/src/components/custom-header.tsx` around lines 24 - 34, Ensure the keys of siteLogos are type-locked to the slugs in docsSitesConfig to catch missing logo entries at compile time: export a slug union type (e.g., DocsSiteSlug = typeof docsSites[number]['slug']) from the module that defines docsSitesConfig, import that type into custom-header.tsx, and change the siteLogos declaration to Record<DocsSiteSlug, { logoBlack: typeof LogoBlack; logoWhite: typeof LogoWhite }>, so TypeScript will raise an error if any docsSitesConfig slug lacks a matching siteLogos entry; keep the existing docsSites mapping (which spreads ...siteLogos[site.slug]) unchanged.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@docs/scripts/sync-docs-meta.ts`:
- Line 1: The shebang in the script currently uses "/usr/bin/env npx tsx";
update it to the simpler "/usr/bin/env tsx" (or remove the shebang and rely on
the package.json script) so the script uses the locally installed tsx binary
without the unnecessary npx wrapper; change the shebang line at the top of
docs/scripts/sync-docs-meta.ts accordingly.
- Line 19: The fs.writeFileSync(metaPath, ...) call can throw if the target
directory is missing; before calling fs.writeFileSync ensure the directory
exists (e.g., call fs.mkdirSync(path.dirname(metaPath), { recursive: true })) or
wrap the write in a try-catch that creates the directory on ENOENT and
rethrows/logs a clear error; update the code around the fs.writeFileSync
invocation (referencing metaPath and fs.writeFileSync) to perform the directory
check/create or add the try-catch with a helpful error message.
In `@docs/src/components/custom-header.tsx`:
- Around line 24-34: Ensure the keys of siteLogos are type-locked to the slugs
in docsSitesConfig to catch missing logo entries at compile time: export a slug
union type (e.g., DocsSiteSlug = typeof docsSites[number]['slug']) from the
module that defines docsSitesConfig, import that type into custom-header.tsx,
and change the siteLogos declaration to Record<DocsSiteSlug, { logoBlack: typeof
LogoBlack; logoWhite: typeof LogoWhite }>, so TypeScript will raise an error if
any docsSitesConfig slug lacks a matching siteLogos entry; keep the existing
docsSites mapping (which spreads ...siteLogos[site.slug]) unchanged.
ℹ️ Review info
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (5)
docs/content/docs/meta.jsondocs/package.jsondocs/scripts/sync-docs-meta.tsdocs/src/components/custom-header.tsxdocs/src/lib/docs-sites.ts
Extend the sync script to write section-level meta.json files too, not just the root one. This fixes the naming inconsistency where the sidebar showed "Cua-Bench" but the dropdown showed "Cua Bench" — now both derive titles, descriptions, and page order from docs-sites.ts. https://claude.ai/code/session_012xmdj4JSbSFBDTUmvKMmfL
Add --exclude '^/' to the lychee external link checker so it skips root-relative paths like /cua/guide/fundamentals/agent-loops. These are internal links already validated by the next-validate-link job. The --scheme http/https flags alone don't prevent lychee from extracting bare paths from href attributes in MDX files. This was broken in ebe9f88 which removed the original --exclude '^file://' without accounting for root-relative paths. https://claude.ai/code/session_012xmdj4JSbSFBDTUmvKMmfL
The previous --exclude '^/' approach failed because lychee errors during URL construction before exclusion filters apply. Using --base 'https://cua.ai' lets lychee resolve root-relative paths to full URLs, which are then excluded by the existing cua\.ai pattern. https://claude.ai/code/session_012xmdj4JSbSFBDTUmvKMmfL
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Extracted the hardcoded documentation site configuration from the custom header component into a centralized, reusable configuration file. This establishes a single source of truth for docs site metadata and enables automatic generation of related configuration files.
Key Changes
New file:
docs/src/lib/docs-sites.ts- Created a centralized configuration module that exports:DocsSiteConfiginterface defining the structure for documentation sitesdocsSitesarray containing configuration for all four documentation sites (Cua, Cua Bench, Cua-Bot, Lume)sidebarPagesderived from the main configuration for sidebar navigationUpdated:
docs/src/components/custom-header.tsx- Refactored to:siteLogoslookup object keyed by site slugNew file:
docs/scripts/sync-docs-meta.ts- Created a build script that:content/docs/meta.jsonfrom the centralized configurationprebuildandpredevhookspnpm docs:sync-metaUpdated:
docs/package.json- Added:prebuildandpredevhooks to auto-sync metadatadocs:sync-metascript for manual synchronizationUpdated:
docs/content/docs/meta.json- Reformatted with proper JSON spacing (no functional change)Implementation Details
The configuration is now maintainable from a single location. Logo assets remain as imports in the header component but are mapped to site slugs, eliminating duplication while keeping asset imports colocated with their usage. The sync script ensures the sidebar metadata stays in sync with the source configuration automatically.
https://claude.ai/code/session_012xmdj4JSbSFBDTUmvKMmfL
Summary by CodeRabbit