An open source design system that's fully customizable and agent ready
TypeScript
docsite: bring back the CLI Integrations and Writing docs pages (#7230)
Joey951ef200bf77
diff --git a/apps/docsite/next.config.mjs b/apps/docsite/next.config.mjsindex 68dd42ab18..16f15b1036 100644--- a/apps/docsite/next.config.mjs+++ b/apps/docsite/next.config.mjs@@ -64,21 +64,12 @@ const nextConfig = {],};},- // The CLI's integration guide became short guides under cli/integrations,- // each with its own page (/docs/cli-integrations-<name>). The old guide- // pages redirect to where their content now starts.+ // Slugs that are not pages of their own redirect to where their text is+ // shown (docRedirects, from generate-data.mjs): each guide of a docs-tree+ // namespace to its section on the namespace's page, including the CLI's+ // integration guides on the CLI Integrations and Writing docs pages.async redirects() {return [- {- source: '/docs/cli-integrations',- destination: '/docs/cli-integrations-overview',- permanent: true,- },- {- source: '/docs/cli-writing-docs',- destination: '/docs/cli-integrations-docs-add-a-topic',- permanent: true,- },// Temporary: a later site version may give these guides pages again....Object.entries(docRedirects).map(([slug, destination]) => ({source: `/docs/${slug}`,diff --git a/apps/docsite/scripts/docs-pages.mjs b/apps/docsite/scripts/docs-pages.mjsindex 61b1b765c7..85b557b72d 100644--- a/apps/docsite/scripts/docs-pages.mjs+++ b/apps/docsite/scripts/docs-pages.mjs@@ -17,13 +17,43 @@*//**- * Root namespaces that keep one page per guide instead of one full page.- * `cli` is the CLI's own reference: /docs/cli is the @astryxdesign/cli package- * page, and each integration guide under it already has its own page and- * sidebar entry.+ * Root namespaces that have no page of their own at their slug: /docs/cli is+ * the @astryxdesign/cli package page. Their pages are listed in+ * GUIDE_NAMESPACE_PAGES; a guide below them that no such page holds keeps a+ * page of its own.*/export const GUIDE_PAGE_NAMESPACES = new Set(['cli']);+/**+ * The pages a root namespace in GUIDE_PAGE_NAMESPACES shows, as the docsite+ * listed them before the CLI's integration guide was split into short guides:+ * "CLI Integrations" and "Writing docs". Each is one full page of the+ * namespace at `route` (minus the routes in `except`, which another page+ * holds), at `slug`, so every guide slug below it redirects to its section+ * there. `aliases` are older slugs that redirect to the page.+ * @type {Map<string, Array<{route: string, slug: string, title: string, except?: string[], aliases?: string[]}>>}+ */+export const GUIDE_NAMESPACE_PAGES = new Map([+ [+ 'cli',+ [+ {+ route: 'cli/integrations',+ slug: 'cli-integrations',+ title: 'CLI Integrations',+ except: ['cli/integrations/building-blocks/docs'],+ aliases: ['cli-integrations-overview'],+ },+ {+ route: 'cli/integrations/building-blocks/docs',+ slug: 'cli-writing-docs',+ title: 'Writing docs',+ aliases: ['cli-integrations-docs-add-a-topic'],+ },+ ],+ ],+]);+/*** Flat topics whose full text the site shows on another topic's page. The* theme split (before namespaces) left `theme` as a short overview and moved@@ -106,7 +136,7 @@ export function namespaceCategory(own, guideCategories) {}/**- * One full page for a root namespace: every guide under it, compiled in tree+ * One full page for a namespace: every guide under it, compiled in tree* order, as `astryx docs <route> --depth all --detail full` reads it. Each* guide and nested namespace keeps its slug as a redirect to where its text* starts on the page. Typed docs (commands, API docs) open only in@@ -116,9 +146,15 @@ export function namespaceCategory(own, guideCategories) {* whose children are flat topics with pages of their own) has no page.* @param {(topic?: string, section?: string, options?: object) => Promise<any>} readDocs* @param {string} route+ * @param {{slug?: string, title?: string, except?: string[], aliases?: string[]}} [options]+ * the page's slug and title when they are not the route's, routes below it+ * that another page holds, and older slugs that redirect to it* @returns {Promise<{page: object, redirects: Record<string, string>} | null>}*/-export async function namespacePage(readDocs, route) {+export async function namespacePage(readDocs, route, options = {}) {+ const {slug = route, title, except = [], aliases = []} = options;+ const excluded = child =>+ except.some(skip => child === skip || child.startsWith(`${skip}/`));const read = await readDocs(route, undefined, {depth: 'all', detail: 'full'});if (read?.type !== 'docs.node' || read.data.kind !== 'namespace') return null;const node = read.data;@@ -133,6 +169,7 @@ export async function namespacePage(readDocs, route) {for (const slot of slots ?? []) {for (const child of slot.children) {if (!child.route.startsWith(`${route}/`)) continue;+ if (excluded(child.route)) continue;if (child.kind === 'generic') {const detail = await readDocs(child.route);guideCategories.push(detail?.data?.category ?? null);@@ -152,16 +189,19 @@ export async function namespacePage(readDocs, route) {if (guideCategories.length === 0) return null;const anchors = sectionAnchors(sections);- const href = `/docs/${route}`;+ const href = `/docs/${slug}`;const redirects = {};- for (const [slug, index] of starts) {- redirects[slug] =+ for (const [guideSlug, index] of starts) {+ redirects[guideSlug] =index < sections.length ? `${href}#${anchors[index]}` : href;}+ for (const alias of [routeSlug(route), ...aliases]) {+ if (alias !== slug) redirects[alias] = href;+ }return {page: {- topic: route,- title: node.title || route,+ topic: slug,+ title: title || node.title || route,description: node.summary || '',category: namespaceCategory(node.category, guideCategories),sections,diff --git a/apps/docsite/scripts/generate-data.mjs b/apps/docsite/scripts/generate-data.mjsindex e5e5d55ab6..182981e365 100644--- a/apps/docsite/scripts/generate-data.mjs+++ b/apps/docsite/scripts/generate-data.mjs@@ -26,6 +26,7 @@ import {createRequire} from 'node:module';import {fileURLToPath, pathToFileURL} from 'node:url';import {resolveContentRoot} from './resolve-content-root.mjs';import {+ GUIDE_NAMESPACE_PAGES,GUIDE_PAGE_NAMESPACES,mergeFlatTopics,namespacePage,@@ -1691,8 +1692,9 @@ export const templateMetadataCount = ${templateMetadata.length};* The docsite pages of the CLI's docs tree, read through the CLI's public docs* API. Every root namespace is one full page at its own slug (docs-pages.mjs),* so splitting a flat topic into a namespace keeps its URL, sidebar spot and- * text; the guides under it redirect to their sections on that page. Root- * namespaces in GUIDE_PAGE_NAMESPACES keep one page per guide instead.+ * text; the guides under it redirect to their sections on that page. A root+ * namespace in GUIDE_PAGE_NAMESPACES shows the pages GUIDE_NAMESPACE_PAGES+ * lists, the same way one level down, and its other guides keep a page each.*/async function docsTreePages() {const pages = [];@@ -1702,9 +1704,19 @@ async function docsTreePages() {const routes = [];const list = await readDocs();const pending = [];+ // Routes a page of a GUIDE_PAGE_NAMESPACES root holds, so their guides get+ // no page of their own.+ const held = new Set();for (const {topic: root} of list.meta?.namespaces ?? []) {if (GUIDE_PAGE_NAMESPACES.has(root)) {pending.push(root);+ for (const spec of GUIDE_NAMESPACE_PAGES.get(root) ?? []) {+ for (const route of await treeRoutes(spec.route)) held.add(route);+ const full = await namespacePage(readDocs, spec.route, spec);+ if (!full) continue;+ pages.push(full.page);+ Object.assign(redirects, full.redirects);+ }continue;}routes.push(...(await treeRoutes(root)));@@ -1723,7 +1735,11 @@ async function docsTreePages() {if (child.kind !== 'namespace') routes.push(child.route);if (child.kind === 'namespace') {pending.push(child.route);- } else if (child.kind === 'generic' && child.route.includes('/')) {+ } else if (+ child.kind === 'generic' &&+ child.route.includes('/') &&+ !held.has(child.route)+ ) {const doc = (await readDocs(child.route)).data;pages.push({topic: routeSlug(child.route),diff --git a/apps/docsite/src/__tests__/docs-pages.test.ts b/apps/docsite/src/__tests__/docs-pages.test.tsindex e4030be1eb..97157e5950 100644--- a/apps/docsite/src/__tests__/docs-pages.test.ts+++ b/apps/docsite/src/__tests__/docs-pages.test.ts@@ -133,6 +133,75 @@ describe('a flat topic split into a docs-tree namespace', () => {});});+describe('a page for part of a namespace', () => {+ const nested = async (+ route?: string,+ _section?: string,+ options: {depth?: number | 'all'} = {},+ ) => {+ const guideNode = (r: string, title: string) => ({+ route: r,+ kind: 'generic',+ title,+ sections: [section(title)],+ });+ if (route === 'kit/guides' && options.depth === 'all') {+ return {+ type: 'docs.node',+ data: {+ route: 'kit/guides',+ kind: 'namespace',+ title: 'Guides',+ summary: 'Kit guides.',+ content: [],+ slots: [+ {+ name: 'guides',+ children: [+ guideNode('kit/guides/start', 'Start'),+ {+ route: 'kit/guides/docs',+ kind: 'namespace',+ title: 'Docs',+ content: [],+ slots: [+ {+ name: 'guides',+ children: [guideNode('kit/guides/docs/write', 'Write')],+ },+ ],+ },+ ],+ },+ ],+ },+ };+ }+ return {type: 'docs.detail', data: {category: 'guide', sections: []}};+ };++ it('takes its own slug and title, leaves out what another page holds, and redirects older slugs', async () => {+ const result = await namespacePage(nested, 'kit/guides', {+ slug: 'kit-guide',+ title: 'Kit Guide',+ except: ['kit/guides/docs'],+ aliases: ['kit-overview'],+ });+ expect(result?.page).toMatchObject({+ topic: 'kit-guide',+ title: 'Kit Guide',+ category: 'guide',+ });+ const page = result?.page as {sections: Array<{title: string}>};+ expect(page.sections.map(s => s.title)).toEqual(['Start']);+ expect(result?.redirects).toEqual({+ 'kit-guides-start': '/docs/kit-guide#start',+ 'kit-guides': '/docs/kit-guide',+ 'kit-overview': '/docs/kit-guide',+ });+ });+});+describe('namespaceCategory', () => {it('prefers the namespace, then foundations only when every guide is', () => {expect(namespaceCategory('guide', ['foundations'])).toBe('guide');diff --git a/apps/docsite/src/__tests__/route-resolution.test.ts b/apps/docsite/src/__tests__/route-resolution.test.tsindex fca9d025c1..64762df889 100644--- a/apps/docsite/src/__tests__/route-resolution.test.ts+++ b/apps/docsite/src/__tests__/route-resolution.test.ts@@ -14,12 +14,15 @@ import {buildOutline} from '../components/docs/docOutline';* Every topic page the site had before the CLI's docs were split into* docs-tree namespaces, with its sidebar group. A split changes how agents* read a topic, never where a reader finds it: each slug keeps one page in the- * same group. Guides under the `cli` namespace keep their own pages and are- * not listed here.+ * same group. The CLI's integration guides were split earlier, from the CLI+ * Integrations and Writing docs pages; those two pages are back too.*/const PAGES_BEFORE_THE_SPLITS: Record<string, 'guide' | 'foundations'> = {authoring: 'guide','browser-support': 'guide',+ 'cli-component-lookups': 'guide',+ 'cli-integrations': 'guide',+ 'cli-writing-docs': 'guide',color: 'foundations',elevation: 'foundations','getting-started': 'guide',@@ -85,6 +88,48 @@ describe('route resolution', () => {}});+ it('lists the guides the sidebar listed before the splits, plus new topics only', () => {+ // The Guide section as it was before the CLI integration guide and the+ // other topics were split into short guides. `styling-overview` is a+ // topic added since.+ const sidebarGuides = docTopics+ .filter(d => d.category === 'guide' && d.topic !== 'getting-started')+ .map(d => d.topic)+ .sort();+ expect(sidebarGuides).toEqual(+ [+ 'authoring',+ 'browser-support',+ 'cli-component-lookups',+ 'cli-integrations',+ 'cli-writing-docs',+ 'internationalization',+ 'layout',+ 'migration',+ 'principles',+ 'styling',+ 'styling-libraries',+ 'styling-overview',+ 'theme',+ 'working-with-ai',+ ].sort(),+ );+ });++ it('opens every CLI integration guide at its section on a full page', () => {+ for (const route of docsTreeRoutes) {+ if (!route.startsWith('cli/integrations/')) continue;+ const slug = route.replaceAll('/', '-');+ expect(pageBySlug.has(slug), slug).toBe(false);+ expect(docRedirects[slug], slug).toMatch(+ /^\/docs\/cli-(integrations|writing-docs)(#|$)/,+ );+ }+ expect(docRedirects['cli-integrations-overview']).toBe(+ '/docs/cli-integrations',+ );+ });+it('keeps /docs/cli the CLI package page', () => {expect(pageBySlug.has('cli')).toBe(false);expect(packages.some(pkg => pkg.name === '@astryxdesign/cli')).toBe(true);