[docs] v5 changes docs: what's new, world upgrade guide, migration skills (#3100)

Author: VaguelySerious

.changeset/docs-v5-whats-new-pages.md

@@ -0,0 +1,2 @@
+---
+---

AGENTS.md

@@ -333,7 +333,7 @@ Linting, formatting, and typechecking (`pnpm lint`, `pnpm format`, `pnpm typeche
 When a PR adds or updates docs pages (anything under `docs/content/`), add a "Docs Preview" section to the PR description with direct links to each changed page on the `workflow-docs` preview deployment:
 
 - Get the preview base URL from the `vercel[bot]` comment on the PR — use the Preview link from the `workflow-docs` project row (e.g. `https://workflow-docs-git-<branch-slug>.vercel.sh`). Don't construct the URL by hand; Vercel's branch-slug normalization is not a simple substitution.
-- Map content paths to routes: `docs/content/docs/v4/<path>.mdx` is served at `/docs/<path>` (v4 is the default/latest version) and `docs/content/docs/v5/<path>.mdx` at `/v5/docs/<path>`.
+- Map content paths to routes: `docs/content/docs/v5/<path>.mdx` is served at `/docs/<path>` (v5 is the default/latest version) and `docs/content/docs/v4/<path>.mdx` at `/v4/docs/<path>` (v4 is the maintenance version).
 - When a change is scoped to a specific section of a page, link to its heading anchor (e.g. `/docs/foundations/hooks#checking-for-token-conflicts`) and verify the anchor matches a real heading in the MDX.
 - A simple table with one row per page (and one column per docs version, when both v4 and v5 were updated) works well.
 - The preview deployment sits behind deployment protection, so the links require Vercel team access — that's expected; include them anyway for reviewers.

docs/app/[lang]/docs/layout.tsx …s/app/[lang]/docs/[[...slug]]/layout.tsxdocs/app/[lang]/docs/layout.tsx renamed to docs/app/[lang]/docs/[[...slug]]/layout.tsx docs/app/[lang]/docs/layout.tsx renamed to docs/app/[lang]/docs/[[...slug]]/layout.tsx

@@ -2,12 +2,19 @@ import { DocsLayout } from '@/components/geistdocs/docs-layout';
 import { getDocsTreeForVersion } from '@/lib/geistdocs/version-source';
 import { LATEST_VERSION } from '@/lib/geistdocs/versions';
 
-const Layout = async ({ children, params }: LayoutProps<'/[lang]/docs'>) => {
-  const { lang } = await params;
+// This layout lives inside `[[...slug]]` rather than next to it so that
+// `params.slug` is available: the sidebar needs the active page to decide
+// whether to drill into a section. See `DocsLayout`.
+const Layout = async ({
+  children,
+  params,
+}: LayoutProps<'/[lang]/docs/[[...slug]]'>) => {
+  const { lang, slug } = await params;
 
   return (
     <div className="bg-background-200">
       <DocsLayout
+        activeSlug={slug}
         currentVersion={LATEST_VERSION.id}
         lang={lang}
         tree={getDocsTreeForVersion(lang, LATEST_VERSION)}

docs/app/[lang]/v5/docs/layout.tsx …pp/[lang]/v5/docs/[[...slug]]/layout.tsxdocs/app/[lang]/v5/docs/layout.tsx renamed to docs/app/[lang]/v5/docs/[[...slug]]/layout.tsx docs/app/[lang]/v5/docs/layout.tsx renamed to docs/app/[lang]/v5/docs/[[...slug]]/layout.tsx

@@ -3,12 +3,19 @@ import { PreReleaseBanner } from '@/components/geistdocs/pre-release-banner';
 import { getDocsTreeForVersion } from '@/lib/geistdocs/version-source';
 import { PRE_RELEASE_VERSION } from '@/lib/geistdocs/versions';
 
-const Layout = async ({ children, params }: LayoutProps<'/[lang]/v5/docs'>) => {
-  const { lang } = await params;
+// This layout lives inside `[[...slug]]` rather than next to it so that
+// `params.slug` is available: the sidebar needs the active page to decide
+// whether to drill into a section. See `DocsLayout`.
+const Layout = async ({
+  children,
+  params,
+}: LayoutProps<'/[lang]/v5/docs/[[...slug]]'>) => {
+  const { lang, slug } = await params;
   return (
     <div className="bg-background-200">
       <PreReleaseBanner pathname={`/${lang}/v5/docs`} />
       <DocsLayout
+        activeSlug={slug}
         currentVersion={PRE_RELEASE_VERSION.id}
         lang={lang}
         tree={getDocsTreeForVersion(lang, PRE_RELEASE_VERSION)}

docs/app/[lang]/v5/worlds/building-a-world/page.tsx

@@ -1,13 +1,13 @@
 import type { Metadata } from 'next';
 import {
-  BuildingAWorldPage,
-  generateBuildingAWorldMetadata,
-} from '@/components/worlds/building-a-world-page';
+  generateWorldsGuideMetadata,
+  WorldsGuidePage,
+} from '@/components/worlds/worlds-guide-page';
 
 export function generateMetadata(): Promise<Metadata> {
-  return generateBuildingAWorldMetadata('v5');
+  return generateWorldsGuideMetadata('building-a-world', 'v5');
 }
 
 export default function Page() {
-  return <BuildingAWorldPage version="v5" />;
+  return <WorldsGuidePage slug="building-a-world" version="v5" />;
 }

docs/app/[lang]/v5/worlds/upgrading-to-v5/page.tsx

@@ -0,0 +1,13 @@
+import type { Metadata } from 'next';
+import {
+  generateWorldsGuideMetadata,
+  WorldsGuidePage,
+} from '@/components/worlds/worlds-guide-page';
+
+export function generateMetadata(): Promise<Metadata> {
+  return generateWorldsGuideMetadata('upgrading-to-v5', 'v5');
+}
+
+export default function Page() {
+  return <WorldsGuidePage slug="upgrading-to-v5" version="v5" />;
+}

docs/app/[lang]/worlds/building-a-world/page.tsx

@@ -1,13 +1,13 @@
 import type { Metadata } from 'next';
 import {
-  BuildingAWorldPage,
-  generateBuildingAWorldMetadata,
-} from '@/components/worlds/building-a-world-page';
+  generateWorldsGuideMetadata,
+  WorldsGuidePage,
+} from '@/components/worlds/worlds-guide-page';
 
 export function generateMetadata(): Promise<Metadata> {
-  return generateBuildingAWorldMetadata('v4');
+  return generateWorldsGuideMetadata('building-a-world', 'v4');
 }
 
 export default function Page() {
-  return <BuildingAWorldPage version="v4" />;
+  return <WorldsGuidePage slug="building-a-world" version="v4" />;
 }

docs/components/geistdocs/docs-layout.tsx

@@ -88,19 +88,57 @@ const withFallbackFolderIndex = (nodes: DocsTreeNode[]): DocsTreeNode[] =>
     };
   });
 
+// `/docs` permanently redirects here, so this is the page every bare link to
+// the documentation lands on.
+const DOCS_HOME_SECTION = 'getting-started';
+
+/**
+ * geistdocs' sidebar has two panes: the top-level menu, and a section pane it
+ * drills into for the first root folder containing the active page. On the docs
+ * home that drill-in is unhelpful — arriving from a `/docs` link would replace
+ * the top-level menu with the framework list, hiding the rest of the docs.
+ *
+ * `findActiveRootSection` only matches folders that have children, so emptying
+ * the section's children on its own landing page keeps the root menu visible
+ * with the row highlighted as the current page. Nothing is lost: the page body
+ * is a card grid of exactly those children, and every other page in the section
+ * still drills in normally.
+ */
+const collapseDocsHomeSection = (
+  tree: DocsTree,
+  activeSlug?: string[]
+): DocsTree => {
+  if (activeSlug?.join('/') !== DOCS_HOME_SECTION) {
+    return tree;
+  }
+
+  return {
+    ...tree,
+    children: tree.children.map((node) =>
+      node.type === 'folder' &&
+      node.index?.url.endsWith(`/docs/${DOCS_HOME_SECTION}`)
+        ? { ...node, children: [] }
+        : node
+    ),
+  };
+};
+
 const addSidebarBadgesToTree = (tree: DocsTree): DocsTree => ({
   ...tree,
   children: addSidebarBadges(withFallbackFolderIndex(tree.children)),
 });
 
 interface DocsLayoutProps {
+  /** Slug of the active page, used to tune sidebar drill-in behavior. */
+  activeSlug?: string[];
   children: ReactNode;
   currentVersion?: string;
   lang: string;
   tree: ComponentProps<typeof PackageDocsLayout>['tree'];
 }
 
 export const DocsLayout = ({
+  activeSlug,
   tree,
   currentVersion = config.versions?.current,
   lang,
@@ -123,7 +161,7 @@ export const DocsLayout = ({
         />
       ) : null
     }
-    tree={addSidebarBadgesToTree(tree)}
+    tree={collapseDocsHomeSection(addSidebarBadgesToTree(tree), activeSlug)}
   >
     {children}
   </PackageDocsLayout>

…ponents/worlds/building-a-world-page.tsx …/components/worlds/worlds-guide-page.tsxdocs/components/worlds/building-a-world-page.tsx renamed to docs/components/worlds/worlds-guide-page.tsx docs/components/worlds/building-a-world-page.tsx renamed to docs/components/worlds/worlds-guide-page.tsx

@@ -10,8 +10,6 @@ import type { DocsVersionId } from '@/lib/geistdocs/versions';
 import { WorldDetailToc } from './WorldDetailToc';
 import { WorldVersionSelect } from './WorldVersionSelect';
 
-const PAGE_SLUGS = ['building-a-world'];
-
 const VERSION_SOURCES = {
   v4: worldsSource,
   v5: v5WorldsSource,
@@ -22,13 +20,19 @@ const VERSION_PREFIXES = {
   v5: '/v5',
 } as const;
 
-export async function generateBuildingAWorldMetadata(
+/**
+ * Standalone guide pages in the worlds tree — the ones that are not a world
+ * detail page. They render outside the docs sidebar, so each is a bespoke
+ * route passing its own slug.
+ */
+export async function generateWorldsGuideMetadata(
+  slug: string,
   version: DocsVersionId
 ): Promise<Metadata> {
-  const page = VERSION_SOURCES[version].getPage(PAGE_SLUGS);
+  const page = VERSION_SOURCES[version].getPage([slug]);
 
   if (!page) {
-    return { title: 'Building a World | Workflow SDK' };
+    return { title: 'Worlds | Workflow SDK' };
   }
 
   const versionPrefix = VERSION_PREFIXES[version];
@@ -41,9 +45,9 @@ export async function generateBuildingAWorldMetadata(
       images: ['/og/worlds'],
     },
     alternates: {
-      canonical: '/worlds/building-a-world',
+      canonical: `/worlds/${slug}`,
       types: {
-        'text/markdown': `${versionPrefix}/worlds/building-a-world.md`,
+        'text/markdown': `${versionPrefix}/worlds/${slug}.md`,
       },
     },
     ...(isPreRelease
@@ -57,14 +61,16 @@ export async function generateBuildingAWorldMetadata(
   };
 }
 
-export async function BuildingAWorldPage({
+export async function WorldsGuidePage({
+  slug,
   version,
 }: {
+  slug: string;
   version: DocsVersionId;
 }) {
   const source = VERSION_SOURCES[version];
   const versionPrefix = VERSION_PREFIXES[version];
-  const page = source.getPage(PAGE_SLUGS);
+  const page = source.getPage([slug]);
 
   if (!page) {
     notFound();

docs/content/docs/v4/deploying.mdx

@@ -55,7 +55,7 @@ vercel deploy
 </Callout>
 
 <Callout type="info">
-  Starting with `workflow` version 5.0.0-beta.33, the Vercel World supports
+  Starting with `workflow` version 5.0.0, the Vercel World supports
   **multi-region**: runs are pinned to the region that creates them, keeping
   workflow data, queuing, and streaming close to your users. See
   [Multi-region](/v5/worlds/vercel#multi-region).