Skip to content

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.mjs
index 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.mjs
index 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.mjs
index 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.ts
index 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.ts
index 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);