docs: make v8 the default docs version#1032
Conversation
Serve v8 docs at the bare /docs path and archive v7.1.1 under /docs/7.1.1, reachable via the version dropdown. - Flip currentDocsVersion to v8 and point v8DocsBasePath at /docs - Bare /docs/[slug] serves v8; legacy-only slugs redirect to the /docs/7.1.1 archive so v7 never renders at a canonical bare URL - Redirect /docs/8.0.0/* to the bare path to avoid duplicate content - Rewrite v8 MDX cross-links from /docs/8.0.0/* to /docs/* - Version dropdown lists v8.0.0 (latest) first, then v7.1.1 The sitemap continues to emit only the bare v8 slugs, so the v7.1.1 archive stays out of sitemap.xml. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
CodeAnt AI is reviewing your PR. |
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (2)
✅ Files skipped from review due to trivial changes (1)
🚧 Files skipped from review as they are similar to previous changes (1)
📝 WalkthroughWalkthroughThis PR migrates docs routing so v8 is served at /docs (unversioned), archives v7.1.1 under /docs/7.1.1, updates routing helpers and page redirects, simplifies navigation base-path selection, retargets internal doc links, updates tests, and removes legacy redirect generation from next.config. ChangesDocumentation Versioning Migration
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 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 |
codeant-ai
Bot
added
the
size:M
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6378aa10ac
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| export const currentDocsVersion: DocsVersionId = 'v8'; | ||
| export const legacyDocsBasePath = '/docs/7.1.1'; | ||
| export const v8DocsBasePath = '/docs/8.0.0'; | ||
| export const v8DocsBasePath = '/docs'; |
There was a problem hiding this comment.
With the v8 base path now set to /docs, current v8 pages such as /docs/cli-messaging, /docs/cli-agent-management, /docs/cli-broker-lifecycle, and /docs/reference-cli collide with the existing legacyDocRedirects in web/next.config.mjs lines 16-21. Those redirects are evaluated before the app route can render, so the new v8 nav/content links to these canonical pages bounce to unrelated destinations like /docs/cli-overview or /docs/harness-driver instead of showing the v8 pages. Please remove or retarget the conflicting bare redirects when promoting v8 to /docs.
Useful? React with 👍 / 👎.
![codeant-ai[bot]](https://avatars.githubusercontent.com/in/646884?s=60&v=4){kind=small}
| if (getDefaultDocsVersionForSlug(slug) === 'v7.1.1') { | ||
| redirect(`/docs/7.1.1/${slug}`); |
There was a problem hiding this comment.
Suggestion: This new redirect branch does not consistently take effect because many legacy bare slugs are already intercepted by existing top-level redirects in web/next.config.mjs (for example /docs/spawning-an-agent, /docs/channels, /docs/dms, etc.). As a result, those URLs still redirect into v8 pages instead of the /docs/7.1.1/* archive, so the new routing intent is only partially implemented. Update or remove the conflicting config redirects so legacy-only slugs reliably reach the archive route. [incomplete implementation]
Severity Level: Major ⚠️
- ❌ Legacy v7 doc URLs resolve to unintended v8 pages.
- ⚠️ Archival `/docs/7.1.1/*` routing not consistently honored.
- ⚠️ SEO/canonical behavior for legacy slugs becomes inconsistent.
- ⚠️ Users following old links see updated content, not archive.Steps of Reproduction ✅
1. Configure and run the Next.js app using the PR code in `web/` so that routing and
config from `web/next.config.mjs` are active.
2. Request the legacy bare docs URL `GET /docs/spawning-an-agent` (an example mentioned in
the suggestion). Next.js evaluates redirects defined in `web/next.config.mjs:7-48` and
`web/next.config.mjs:66-78`, and matches the entry `{ source: '/docs/spawning-an-agent',
destination: '/docs/harness-driver', permanent: false }` at `web/next.config.mjs:9`.
3. Observe that the framework issues an HTTP redirect from `/docs/spawning-an-agent` to
`/docs/harness-driver` at the config level; the route handler `DocsPage` in
`web/app/docs/[slug]/page.tsx:103-154` is never invoked for slug `spawning-an-agent`, so
the new branch:
`if (getDefaultDocsVersionForSlug(slug) === 'v7.1.1') {
redirect(\`/docs/7.1.1/${slug}\`); }`
at `web/app/docs/[slug]/page.tsx:107-108` does not run.
4. Independently verify intent: `getDefaultDocsVersionForSlug(slug)` in
`web/lib/docs-versions.ts:15-20` returns `'v7.1.1'` for slugs that are legacy-only (i.e.,
not in `currentDocsSlugs` but present in `legacyDocsSlugs`), meaning
`/docs/spawning-an-agent` is expected to go to `/docs/7.1.1/spawning-an-agent`. Because of
the conflicting redirect in `web/next.config.mjs`, those legacy slugs are instead
redirected to various `/docs/*` v8 destinations (e.g., `/docs/harness-driver`), so the
archival redirect logic in `web/app/docs/[slug]/page.tsx:107-108` is partially bypassed.Fix in Cursor | Fix in VSCode Claude
(Use Cmd/Ctrl + Click for best experience)
Prompt for AI Agent 🤖
This is a comment left during a code review.
**Path:** web/app/docs/[slug]/page.tsx
**Line:** 107:108
**Comment:**
*Incomplete Implementation: This new redirect branch does not consistently take effect because many legacy bare slugs are already intercepted by existing top-level redirects in `web/next.config.mjs` (for example `/docs/spawning-an-agent`, `/docs/channels`, `/docs/dms`, etc.). As a result, those URLs still redirect into v8 pages instead of the `/docs/7.1.1/*` archive, so the new routing intent is only partially implemented. Update or remove the conflicting config redirects so legacy-only slugs reliably reach the archive route.
Validate the correctness of the flagged issue. If correct, How can I resolve this? If you propose a fix, implement it and please make it concise.
Once fix is implemented, also check other comments on the same PR, and ask user if the user wants to fix the rest of the comments as well. if said yes, then fetch all the comments validate the correctness and implement a minimal fix
|
CodeAnt AI finished reviewing your PR. |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request promotes Version 8.0.0 (v8) of the documentation to be the default, serving it from the bare /docs path instead of /docs/8.0.0, while archiving Version 7.1.1 (v7.1.1) under /docs/7.1.1. This involves updating path resolution, navigation components, markdown links, and setting up redirects from the old /docs/8.0.0/[slug] paths to /docs/[slug]. Feedback on the changes suggests keeping generateStaticParams in the redirect page at web/app/docs/8.0.0/[slug]/page.tsx to ensure Next.js can statically generate these redirect pages during build time, preventing potential build failures and optimizing edge redirects.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
| import { redirect } from 'next/navigation'; | ||
|
|
||
| type PageProps = { | ||
| params: Promise<{ slug: string }>; | ||
| }; | ||
|
|
||
| export async function generateStaticParams() { | ||
| return getAllDocSlugs().map((slug) => ({ slug })); | ||
| } | ||
|
|
||
| export async function generateMetadata({ params }: PageProps): Promise<Metadata> { | ||
| export default async function V8DocsSlugRedirectPage({ params }: PageProps) { | ||
| const { slug } = await params; | ||
| const doc = getDoc(slug, 'v8'); | ||
|
|
||
| if (!doc) { | ||
| return { title: 'Not Found' }; | ||
| } | ||
|
|
||
| return { | ||
| title: `${doc.frontmatter.title} - Version 8.0.0`, | ||
| description: doc.frontmatter.description, | ||
| alternates: { | ||
| canonical: absoluteUrl(`/docs/8.0.0/${slug}`), | ||
| }, | ||
| openGraph: { | ||
| title: `${doc.frontmatter.title} - Version 8.0.0`, | ||
| description: doc.frontmatter.description, | ||
| url: absoluteUrl(`/docs/8.0.0/${slug}`), | ||
| type: 'article', | ||
| }, | ||
| }; | ||
| } | ||
|
|
||
| export default async function V8DocsPage({ params }: PageProps) { | ||
| const { slug } = await params; | ||
| const doc = getDoc(slug, 'v8'); | ||
|
|
||
| if (!doc) { | ||
| notFound(); | ||
| } | ||
|
|
||
| const { default: MDXContent } = await evaluate(doc.content, { | ||
| Fragment, | ||
| jsx, | ||
| jsxs, | ||
| remarkPlugins: [remarkGfm], | ||
| } as Parameters<typeof evaluate>[1]); | ||
|
|
||
| const pageUrl = absoluteUrl(`/docs/8.0.0/${slug}`); | ||
| const markdownPath = `/docs/markdown/${slug}.md`; | ||
| const markdownUrl = getDocMarkdownUrl(slug); | ||
|
|
||
| return ( | ||
| <div className={styles.articleWrapper}> | ||
| <article className={styles.article}> | ||
| <div className={styles.articleHeader}> | ||
| <div className={styles.articleHeading}> | ||
| <h1>{doc.frontmatter.title}</h1> | ||
| </div> | ||
| <DocsPageActions | ||
| title={doc.frontmatter.title} | ||
| pageUrl={pageUrl} | ||
| markdownPath={markdownPath} | ||
| markdownUrl={markdownUrl} | ||
| /> | ||
| </div> | ||
| {doc.frontmatter.description && ( | ||
| <p className={styles.articleDescription}>{doc.frontmatter.description}</p> | ||
| )} | ||
| <div className={styles.articleBody}> | ||
| <MDXContent components={components} /> | ||
| </div> | ||
| </article> | ||
| <aside className={styles.tocSidebar}> | ||
| <TableOfContents items={doc.toc} /> | ||
| </aside> | ||
| </div> | ||
| ); | ||
| redirect(`/docs/${slug}`); | ||
| } |
There was a problem hiding this comment.
Removing generateStaticParams from this dynamic route file will prevent Next.js from statically generating the redirect pages during build time. If the project is deployed as a static export (output: 'export'), the build will fail. Even with dynamic server rendering, statically generating these redirects is highly recommended for performance and SEO to ensure instant redirects at the CDN edge without invoking serverless functions.
| import { redirect } from 'next/navigation'; | |
| type PageProps = { | |
| params: Promise<{ slug: string }>; | |
| }; | |
| export async function generateStaticParams() { | |
| return getAllDocSlugs().map((slug) => ({ slug })); | |
| } | |
| export async function generateMetadata({ params }: PageProps): Promise<Metadata> { | |
| export default async function V8DocsSlugRedirectPage({ params }: PageProps) { | |
| const { slug } = await params; | |
| const doc = getDoc(slug, 'v8'); | |
| if (!doc) { | |
| return { title: 'Not Found' }; | |
| } | |
| return { | |
| title: `${doc.frontmatter.title} - Version 8.0.0`, | |
| description: doc.frontmatter.description, | |
| alternates: { | |
| canonical: absoluteUrl(`/docs/8.0.0/${slug}`), | |
| }, | |
| openGraph: { | |
| title: `${doc.frontmatter.title} - Version 8.0.0`, | |
| description: doc.frontmatter.description, | |
| url: absoluteUrl(`/docs/8.0.0/${slug}`), | |
| type: 'article', | |
| }, | |
| }; | |
| } | |
| export default async function V8DocsPage({ params }: PageProps) { | |
| const { slug } = await params; | |
| const doc = getDoc(slug, 'v8'); | |
| if (!doc) { | |
| notFound(); | |
| } | |
| const { default: MDXContent } = await evaluate(doc.content, { | |
| Fragment, | |
| jsx, | |
| jsxs, | |
| remarkPlugins: [remarkGfm], | |
| } as Parameters<typeof evaluate>[1]); | |
| const pageUrl = absoluteUrl(`/docs/8.0.0/${slug}`); | |
| const markdownPath = `/docs/markdown/${slug}.md`; | |
| const markdownUrl = getDocMarkdownUrl(slug); | |
| return ( | |
| <div className={styles.articleWrapper}> | |
| <article className={styles.article}> | |
| <div className={styles.articleHeader}> | |
| <div className={styles.articleHeading}> | |
| <h1>{doc.frontmatter.title}</h1> | |
| </div> | |
| <DocsPageActions | |
| title={doc.frontmatter.title} | |
| pageUrl={pageUrl} | |
| markdownPath={markdownPath} | |
| markdownUrl={markdownUrl} | |
| /> | |
| </div> | |
| {doc.frontmatter.description && ( | |
| <p className={styles.articleDescription}>{doc.frontmatter.description}</p> | |
| )} | |
| <div className={styles.articleBody}> | |
| <MDXContent components={components} /> | |
| </div> | |
| </article> | |
| <aside className={styles.tocSidebar}> | |
| <TableOfContents items={doc.toc} /> | |
| </aside> | |
| </div> | |
| ); | |
| redirect(`/docs/${slug}`); | |
| } | |
| import { redirect } from 'next/navigation'; | |
| import { getAllDocSlugs } from '../../../../lib/docs-nav'; | |
| type PageProps = { | |
| params: Promise<{ slug: string }>; | |
| }; | |
| export async function generateStaticParams() { | |
| return getAllDocSlugs().map((slug) => ({ slug })); | |
| } | |
| export default async function V8DocsSlugRedirectPage({ params }: PageProps) { | |
| const { slug } = await params; | |
| redirect(`/docs/${slug}`); | |
| } |
|
Preview deployed!
This preview will be cleaned up when the PR is merged or closed. |
|
Fixed the PR issues I found. Changed:
Verification:
|
|
✅ pr-reviewer applied fixes — committed and pushed Fixed the PR issues I found. Changed:
Verification:
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (2)
web/app/docs/8.0.0/page.tsx (1)
3-5: 💤 Low valueConsider using a permanent redirect for consistency.
Same as the slug redirect page - this permanent URL change would benefit from a 308 redirect:
redirect('/docs/introduction', 'permanent').🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@web/app/docs/8.0.0/page.tsx` around lines 3 - 5, The redirect in V8DocsRedirectPage currently issues a temporary redirect; update the redirect call inside function V8DocsRedirectPage to perform a permanent (308) redirect by passing the 'permanent' option as the second argument to redirect (i.e., change the redirect invocation so it calls redirect('/docs/introduction', 'permanent') within V8DocsRedirectPage).web/app/docs/8.0.0/[slug]/page.tsx (1)
7-10: 💤 Low valueConsider using a permanent redirect for better SEO.
The default
redirect()issues a 307 (temporary) redirect. Since the/docs/8.0.0/*→/docs/*migration is permanent, a 308 redirect would signal to search engines that this change is permanent, improving crawl efficiency and link equity transfer.Suggested change
export default async function V8DocsSlugRedirectPage({ params }: PageProps) { const { slug } = await params; - redirect(`/docs/${slug}`); + redirect(`/docs/${slug}`, 'permanent'); }🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@web/app/docs/8.0.0/`[slug]/page.tsx around lines 7 - 10, The redirect in V8DocsSlugRedirectPage currently issues a temporary 307; change the call so it issues a permanent 308 redirect (e.g. pass a 308 status option to redirect(`/docs/${slug}`) or use NextResponse.redirect with status 308) so the migration from /docs/8.0.0/* to /docs/* is permanent for SEO; update the import/usage (redirect vs NextResponse) if necessary to support providing the 308 status.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@web/app/docs/8.0.0/`[slug]/page.tsx:
- Around line 7-10: The redirect in V8DocsSlugRedirectPage currently issues a
temporary 307; change the call so it issues a permanent 308 redirect (e.g. pass
a 308 status option to redirect(`/docs/${slug}`) or use NextResponse.redirect
with status 308) so the migration from /docs/8.0.0/* to /docs/* is permanent for
SEO; update the import/usage (redirect vs NextResponse) if necessary to support
providing the 308 status.
In `@web/app/docs/8.0.0/page.tsx`:
- Around line 3-5: The redirect in V8DocsRedirectPage currently issues a
temporary redirect; update the redirect call inside function V8DocsRedirectPage
to perform a permanent (308) redirect by passing the 'permanent' option as the
second argument to redirect (i.e., change the redirect invocation so it calls
redirect('/docs/introduction', 'permanent') within V8DocsRedirectPage).
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 2856df27-56d6-4ce4-8874-b3b48d8bcf60
📒 Files selected for processing (11)
web/app/docs/8.0.0/[slug]/page.tsxweb/app/docs/8.0.0/page.tsxweb/app/docs/[slug]/page.tsxweb/components/docs/DocsNav.tsxweb/content/docs/cli-agent-management.mdxweb/content/docs/cli-broker-lifecycle.mdxweb/content/docs/cli-messaging.mdxweb/content/docs/cli-overview.mdxweb/content/docs/reference-cli.mdxweb/lib/docs-versions.tsweb/lib/test/docs-markdown-components.test.ts
1 participant
User description
Summary
Flips the published docs so v8 is the default (served at the bare
/docs/*paths) and v7.1.1 becomes the archive at/docs/7.1.1/*, reachable only via the version dropdown. The old docs stay out ofsitemap.xml.Changes
Version logic —
web/lib/docs-versions.tscurrentDocsVersion:v7.1.1→v8v8DocsBasePath:/docs/8.0.0→/docsgetDocsVersionForPath/getDocsVersionHref/getDefaultDocsVersionForSlugresolve the/docs/7.1.1prefix first, then default to v8Routing
app/docs/[slug]/page.tsx— bare path serves v8 only; legacy-only slugs 307-redirect to/docs/7.1.1/{slug}so v7 content never renders at a canonical bare URLapp/docs/8.0.0/*— now redirects to the bare path (mirrorspre-v8→7.1.1), keeping old preview links working without duplicate contentNav —
components/docs/DocsNav.tsx/docs, v7.1.1 →/docs/7.1.1Content
/docs/8.0.0/*cross-links →/docs/*in the 5 CLI MDX files; updateddocs-markdown-components.test.tsexpectationsSitemap
sitemap.tsalready emits only the bare v8 slugs, so the/docs/7.1.1archive is excludedTesting
npx tsc --noEmit— cleannpx vitest run— 12/12 pass🤖 Generated with Claude Code
CodeAnt-AI Description
Make v8 the default docs experience and move v7.1.1 into the archive
What Changed
/docs/*paths, and v7.1.1 is served from/docs/7.1.1/*/docs/8.0.0/*links now redirect to the current v8 pages, and internal docs links were updated to use the new bare/docs/*pathsImpact
✅ Clearer docs links✅ Fewer broken version paths✅ Easier access to the current docs💡 Usage Guide
Checking Your Pull Request
Every time you make a pull request, our system automatically looks through it. We check for security issues, mistakes in how you're setting up your infrastructure, and common code problems. We do this to make sure your changes are solid and won't cause any trouble later.
Talking to CodeAnt AI
Got a question or need a hand with something in your pull request? You can easily get in touch with CodeAnt AI right here. Just type the following in a comment on your pull request, and replace "Your question here" with whatever you want to ask:
This lets you have a chat with CodeAnt AI about your pull request, making it easier to understand and improve your code.
Example
Preserve Org Learnings with CodeAnt
You can record team preferences so CodeAnt AI applies them in future reviews. Reply directly to the specific CodeAnt AI suggestion (in the same thread) and replace "Your feedback here" with your input:
This helps CodeAnt AI learn and adapt to your team's coding style and standards.
Example
Retrigger review
Ask CodeAnt AI to review the PR again, by typing:
Check Your Repository Health
To analyze the health of your code repository, visit our dashboard at https://app.codeant.ai. This tool helps you identify potential issues and areas for improvement in your codebase, ensuring your repository maintains high standards of code health.