Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(docsite): suggest matching pages on 404s (#5669)

nynexman4464d7bb4bff3b07
diff --git a/apps/docsite/src/__tests__/did-you-mean.test.ts b/apps/docsite/src/__tests__/did-you-mean.test.ts
new file mode 100644
index 0000000000..f31b2481a8
--- /dev/null
+++ b/apps/docsite/src/__tests__/did-you-mean.test.ts
@@ -0,0 +1,71 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Tests for docsite DidYouMean matching.
+ * @input Representative missing paths and canonical sitemap page candidates
+ * @output Confidence, ranking, normalization, deduplication, and limit guarantees
+ * @position Unit coverage for the pure similar-page matcher
+ */
+
+import {describe, expect, it} from 'vitest';
+import {findSimilarPages, type PageCandidate} from '../lib/didYouMean';
+
+const pages: PageCandidate[] = [
+ {path: '/', title: 'Home'},
+ {path: '/docs', title: 'Docs'},
+ {path: '/docs/getting-started', title: 'Getting Started'},
+ {path: '/components', title: 'Components'},
+ {path: '/components/AppShell', title: 'App Shell'},
+ {path: '/components/Button', title: 'Button'},
+ {path: '/changelog', title: "What's New"},
+ {path: '/templates/dashboard', title: 'Dashboard'},
+];
+
+function suggestedPaths(pathname: string, limit?: number): string[] {
+ return findSimilarPages(pathname, pages, limit).map(page => page.path);
+}
+
+describe('findSimilarPages', () => {
+ it('finds a page whose final segment exactly matches the missing path', () => {
+ expect(suggestedPaths('/getting-started')[0]).toBe('/docs/getting-started');
+ });
+
+ it('matches a partial page title', () => {
+ expect(suggestedPaths('/start')[0]).toBe('/docs/getting-started');
+ });
+
+ it('matches a word from the canonical page title', () => {
+ expect(suggestedPaths('/new')[0]).toBe('/changelog');
+ });
+
+ it('corrects typos in a full nested path', () => {
+ expect(suggestedPaths('/doc/geting-started')[0]).toBe(
+ '/docs/getting-started',
+ );
+ });
+
+ it('normalizes case and punctuation', () => {
+ expect(suggestedPaths('/components/app-shell')[0]).toBe(
+ '/components/AppShell',
+ );
+ });
+
+ it('does not offer low-confidence matches', () => {
+ expect(suggestedPaths('/nothing-like-a-real-page')).toEqual([]);
+ });
+
+ it('deduplicates pages and respects the result limit', () => {
+ const duplicatePages = [
+ ...pages,
+ {path: '/components/Button', title: 'Button duplicate'},
+ ];
+
+ expect(findSimilarPages('/components/Buton', duplicatePages, 1)).toEqual([
+ {path: '/components/Button', title: 'Button'},
+ ]);
+ });
+
+ it('ignores unusually long input rather than doing fuzzy work', () => {
+ expect(suggestedPaths(`/${'x'.repeat(129)}`)).toEqual([]);
+ });
+});
diff --git a/apps/docsite/src/__tests__/sitemap.test.ts b/apps/docsite/src/__tests__/sitemap.test.ts
index 14fbf4460a..c7c4a85336 100644
--- a/apps/docsite/src/__tests__/sitemap.test.ts
+++ b/apps/docsite/src/__tests__/sitemap.test.ts
@@ -16,7 +16,7 @@ import {describe, it, expect, vi} from 'vitest';
// cache scope to configure. Stub it so the sitemap can run under vitest.
vi.mock('next/cache', () => ({cacheLife: () => {}}));
-import sitemap from '../app/sitemap';
+import sitemap, {getSitemapPages} from '../app/sitemap';
import {SITE_URL} from '../lib/siteConfig';
import {flattenComponentSidebarEntries} from '../components/componentSidebarData';
import {docTopics} from '../generated/docsRegistry';
@@ -25,6 +25,7 @@ import {templates} from '../generated/templateRegistry';
import {blogPosts} from '../generated/blogRegistry';
const entries = await sitemap();
+const pages = await getSitemapPages();
const urls = entries.map(e => e.url);
describe('docsite sitemap', () => {
@@ -44,6 +45,12 @@ describe('docsite sitemap', () => {
}
});
+ it('exports canonical page titles for route recovery', () => {
+ expect(
+ pages.find(page => new URL(page.url).pathname === '/changelog')?.title,
+ ).toBe("What's New");
+ });
+
it('includes every component detail page', () => {
for (const c of flattenComponentSidebarEntries()) {
expect(urls).toContain(
diff --git a/apps/docsite/src/app/(docs)/changelog/page.tsx b/apps/docsite/src/app/(docs)/changelog/page.tsx
index a006398f2e..de44cb67b1 100644
--- a/apps/docsite/src/app/(docs)/changelog/page.tsx
+++ b/apps/docsite/src/app/(docs)/changelog/page.tsx
@@ -1,5 +1,12 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
+/**
+ * @file Changelog route for published Astryx packages.
+ * @input Generated package changelogs, component names, and URL selection state
+ * @output The canonical What's New page with package-filtered release notes
+ * @position Public docsite page at /changelog
+ */
+
import {Suspense} from 'react';
import type {Metadata} from 'next';
import {
@@ -9,9 +16,10 @@ import {
import {components} from '../../../generated/componentRegistry';
import {packages} from '../../../generated/packageRegistry';
import {pageMetadata} from '../../../lib/pageMetadata';
+import {CHANGELOG_PAGE_TITLE} from '../../../lib/pageTitles';
export const metadata: Metadata = pageMetadata({
- title: 'Changelog',
+ title: CHANGELOG_PAGE_TITLE,
description:
'Release notes and version history for Astryx packages and components.',
path: '/changelog',
diff --git a/apps/docsite/src/app/(site)/community/page.tsx b/apps/docsite/src/app/(site)/community/page.tsx
index 2489351115..cf7f6f322a 100644
--- a/apps/docsite/src/app/(site)/community/page.tsx
+++ b/apps/docsite/src/app/(site)/community/page.tsx
@@ -4,6 +4,10 @@
* Astryx community page — channels + contribution paths + live
* contributors.
*
+ * @input Static community content plus an hourly-cached GitHub contributor list
+ * @output Community landing page with contribution paths and contributor wall
+ * @position Public docsite page at /community
+ *
* Three roles in one page (modeled after how Astro, Svelte, and
* GitHub Primer balance the same trio):
*
@@ -22,6 +26,7 @@
import type {ReactNode} from 'react';
import type {Metadata} from 'next';
+import {cacheLife} from 'next/cache';
import {FileText, Scale} from 'lucide-react';
import {NavSurfaceMode} from './NavSurfaceMode';
import {TemplatesPreview} from '../_landing/TemplatesPreview';
@@ -731,10 +736,12 @@ interface Contributor {
// Astryx contributor set. Falls back to Unsplash placeholders if the
// request fails.
async function fetchContributors(): Promise<Contributor[]> {
+ 'use cache';
+ cacheLife('hours');
+
try {
const res = await fetch(
'https://api.github.com/repos/facebook/stylex/contributors?per_page=50',
- {next: {revalidate: 3600}},
);
if (!res.ok) {
return [];
diff --git a/apps/docsite/src/app/not-found.tsx b/apps/docsite/src/app/not-found.tsx
index f4ebf82373..38e4c472cc 100644
--- a/apps/docsite/src/app/not-found.tsx
+++ b/apps/docsite/src/app/not-found.tsx
@@ -1,18 +1,32 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
+/**
+ * @file Global not-found page for the Astryx docsite.
+ * @input Shared shell chrome, sitemap pages, and the current request pathname
+ * @output Branded 404 page with high-confidence destination suggestions
+ * @position Fallback route rendered whenever no static or dynamic docsite page matches
+ */
+
import {AppShell} from '@astryxdesign/core/AppShell';
import {Center} from '@astryxdesign/core/Center';
import {VStack} from '@astryxdesign/core/Layout';
import {Heading, Text} from '@astryxdesign/core/Text';
import {SharedTopNav} from '../components/SharedTopNav';
import {CanaryBanner} from '../components/CanaryBanner';
+import {DidYouMean} from '../components/DidYouMean';
import {CURRENT_TARGET} from '../lib/docsVersions';
import {SiteFooter} from '../components/SiteFooter';
import {getCopyrightYear} from '../lib/copyrightYear';
+import {getSitemapPages} from './sitemap';
import styles from './not-found.module.css';
export default async function NotFound() {
const year = await getCopyrightYear();
+ const sitemapPages = await getSitemapPages();
+ const pages = sitemapPages.map(({url, title}) => ({
+ path: new URL(url).pathname,
+ title,
+ }));
return (
<AppShell
@@ -31,6 +45,7 @@ export default async function NotFound() {
<Text type="body" color="secondary">
This page could not be found.
</Text>
+ <DidYouMean pages={pages} />
</VStack>
</Center>
</div>
diff --git a/apps/docsite/src/app/sitemap.ts b/apps/docsite/src/app/sitemap.ts
index 243275a088..69182bebfb 100644
--- a/apps/docsite/src/app/sitemap.ts
+++ b/apps/docsite/src/app/sitemap.ts
@@ -9,11 +9,8 @@
* template, or blog post and it appears in the sitemap with no manual edit.
*
* Mirrors the `generateStaticParams` of each dynamic route so the sitemap and
- * the actual rendered pages never drift:
- * - /components/[name] ← flattenComponentSidebarEntries()
- * - /docs/[topic] ← docTopics + non-theme packages
- * - /templates/[slug] ← templates
- * - /blog/[slug] ← blogPosts
+ * the actual rendered pages never drift. `getSitemapPages()` exposes the same
+ * entries with their canonical page titles for 404 recovery.
*
* @output MetadataRoute.Sitemap consumed by Next.js to emit /sitemap.xml
*/
@@ -21,14 +18,15 @@
import type {MetadataRoute} from 'next';
import {cacheLife} from 'next/cache';
import {SITE_URL} from '../lib/siteConfig';
+import {CHANGELOG_PAGE_TITLE} from '../lib/pageTitles';
import {flattenComponentSidebarEntries} from '../components/componentSidebarData';
import {docTopics} from '../generated/docsRegistry';
import {packages} from '../generated/packageRegistry';
import {templates} from '../generated/templateRegistry';
import {blogPosts} from '../generated/blogRegistry';
-// Theme packages don't get a /docs/[topic] reference page (see the docs route's
-// own filter); keep the sitemap aligned with what actually renders.
+export type SitemapPage = MetadataRoute.Sitemap[number] & {title: string};
+
function isThemePackage(name: string): boolean {
return name.includes('theme-');
}
@@ -43,52 +41,102 @@ async function getLastModified(): Promise<Date> {
return new Date();
}
-export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
+export async function getSitemapPages(): Promise<SitemapPage[]> {
const now = await getLastModified();
- // Static, hand-authored pages. `priority` is a relative hint to crawlers;
- // the home page and primary galleries rank highest.
- const staticEntries: MetadataRoute.Sitemap = [
- {url: url('/'), changeFrequency: 'weekly', priority: 1},
- {url: url('/components'), changeFrequency: 'weekly', priority: 0.9},
- {url: url('/docs'), changeFrequency: 'weekly', priority: 0.9},
- {url: url('/templates'), changeFrequency: 'weekly', priority: 0.8},
- {url: url('/themes'), changeFrequency: 'weekly', priority: 0.8},
- {url: url('/blog'), changeFrequency: 'weekly', priority: 0.8},
- {url: url('/changelog'), changeFrequency: 'weekly', priority: 0.6},
- {url: url('/community'), changeFrequency: 'monthly', priority: 0.5},
- {url: url('/playground'), changeFrequency: 'monthly', priority: 0.6},
- {url: url('/llms.txt'), changeFrequency: 'weekly', priority: 0.5},
+ const staticEntries: SitemapPage[] = [
+ {url: url('/'), title: 'Home', changeFrequency: 'weekly', priority: 1},
+ {
+ url: url('/components'),
+ title: 'Components',
+ changeFrequency: 'weekly',
+ priority: 0.9,
+ },
+ {
+ url: url('/docs'),
+ title: 'Docs',
+ changeFrequency: 'weekly',
+ priority: 0.9,
+ },
+ {
+ url: url('/templates'),
+ title: 'Templates',
+ changeFrequency: 'weekly',
+ priority: 0.8,
+ },
+ {
+ url: url('/themes'),
+ title: 'Themes',
+ changeFrequency: 'weekly',
+ priority: 0.8,
+ },
+ {
+ url: url('/blog'),
+ title: 'Blog',
+ changeFrequency: 'weekly',
+ priority: 0.8,
+ },
+ {
+ url: url('/changelog'),
+ title: CHANGELOG_PAGE_TITLE,
+ changeFrequency: 'weekly',
+ priority: 0.6,
+ },
+ {
+ url: url('/community'),
+ title: 'Community',
+ changeFrequency: 'monthly',
+ priority: 0.5,
+ },
+ {
+ url: url('/playground'),
+ title: 'Playground',
+ changeFrequency: 'monthly',
+ priority: 0.6,
+ },
+ {
+ url: url('/llms.txt'),
+ title: 'LLMs.txt',
+ changeFrequency: 'weekly',
+ priority: 0.5,
+ },
];
- const componentEntries: MetadataRoute.Sitemap =
- flattenComponentSidebarEntries().map(c => ({
- url: url(`/components/${c.name}`),
+ const componentEntries: SitemapPage[] = flattenComponentSidebarEntries().map(
+ component => ({
+ url: url(`/components/${component.name}`),
+ title: component.displayName,
changeFrequency: 'weekly',
priority: 0.7,
- }));
+ }),
+ );
- const docTopicEntries: MetadataRoute.Sitemap = [
- ...docTopics.map(d => d.topic),
+ const docTopicEntries: SitemapPage[] = [
+ ...docTopics.map(topic => ({slug: topic.topic, title: topic.title})),
...packages
- .filter(p => !isThemePackage(p.name))
- .map(p => p.name.replace('@astryxdesign/', '')),
- ].map(topic => ({
- url: url(`/docs/${topic}`),
+ .filter(pkg => !isThemePackage(pkg.name))
+ .map(pkg => ({
+ slug: pkg.name.replace('@astryxdesign/', ''),
+ title: pkg.displayName,
+ })),
+ ].map(({slug, title}) => ({
+ url: url(`/docs/${slug}`),
+ title,
changeFrequency: 'weekly' as const,
priority: 0.7,
}));
- const templateEntries: MetadataRoute.Sitemap = templates.map(t => ({
- url: url(`/templates/${t.slug}`),
+ const templateEntries: SitemapPage[] = templates.map(template => ({
+ url: url(`/templates/${template.slug}`),
+ title: template.name,
changeFrequency: 'monthly',
priority: 0.6,
}));
- const blogEntries: MetadataRoute.Sitemap = blogPosts.map(p => ({
- url: url(`/blog/${p.slug}`),
- // Use the post's own publish date as lastModified when present.
- lastModified: p.date ? new Date(p.date) : now,
+ const blogEntries: SitemapPage[] = blogPosts.map(post => ({
+ url: url(`/blog/${post.slug}`),
+ title: post.title,
+ lastModified: post.date ? new Date(post.date) : now,
changeFrequency: 'monthly',
priority: 0.6,
}));
@@ -101,3 +149,8 @@ export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
...blogEntries,
];
}
+
+export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
+ const pages = await getSitemapPages();
+ return pages.map(({title: _title, ...entry}) => entry);
+}
diff --git a/apps/docsite/src/components/ChangelogView.tsx b/apps/docsite/src/components/ChangelogView.tsx
index 4ed633c460..31fd4e0731 100644
--- a/apps/docsite/src/components/ChangelogView.tsx
+++ b/apps/docsite/src/components/ChangelogView.tsx
@@ -18,6 +18,7 @@ import {TabList, Tab} from '@astryxdesign/core/TabList';
import {Carousel} from '@astryxdesign/core/Carousel';
import {typeScaleVars} from '@astryxdesign/core/theme/tokens.stylex';
import {layout} from '../layout.stylex';
+import {CHANGELOG_PAGE_TITLE} from '../lib/pageTitles';
import {
linkifyPRs,
linkifyContributors,
@@ -128,7 +129,7 @@ export function ChangelogView({
<VStack gap={8}>
<VStack gap={4}>
<Heading level={1} type="display-1">
- What&apos;s New
+ {CHANGELOG_PAGE_TITLE}
</Heading>
<Text type="large" weight="normal" color="secondary">
Release notes and changelog for all packages.
diff --git a/apps/docsite/src/components/DidYouMean.tsx b/apps/docsite/src/components/DidYouMean.tsx
new file mode 100644
index 0000000000..9e0603d3c3
--- /dev/null
+++ b/apps/docsite/src/components/DidYouMean.tsx
@@ -0,0 +1,42 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Suggested destinations for a missing docsite page.
+ * @input Current pathname and canonical pages exported by the sitemap
+ * @output High-confidence navigation links when a likely destination exists
+ * @position Client-side recovery UI within the server-rendered 404 page
+ */
+
+'use client';
+
+import {usePathname} from 'next/navigation';
+import {VStack} from '@astryxdesign/core/Layout';
+import {Link} from '@astryxdesign/core/Link';
+import {Text} from '@astryxdesign/core/Text';
+import {findSimilarPages, type PageCandidate} from '../lib/didYouMean';
+
+interface DidYouMeanProps {
+ pages: readonly PageCandidate[];
+}
+
+export function DidYouMean({pages}: DidYouMeanProps) {
+ const pathname = usePathname();
+ const suggestions = findSimilarPages(pathname, pages);
+
+ if (suggestions.length === 0) {
+ return null;
+ }
+
+ return (
+ <VStack gap={1} hAlign="center">
+ <Text type="body" color="secondary">
+ Did you mean?
+ </Text>
+ {suggestions.map(suggestion => (
+ <Link key={suggestion.path} href={suggestion.path} isStandalone>
+ {suggestion.title}
+ </Link>
+ ))}
+ </VStack>
+ );
+}
diff --git a/apps/docsite/src/lib/didYouMean.ts b/apps/docsite/src/lib/didYouMean.ts
new file mode 100644
index 0000000000..1d09527dfb
--- /dev/null
+++ b/apps/docsite/src/lib/didYouMean.ts
@@ -0,0 +1,181 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Similar-page ranking for the docsite 404 experience.
+ * @input The missing pathname and canonical sitemap paths and page titles
+ * @output Up to three high-confidence pages ordered by similarity
+ * @position Pure matching logic behind the DidYouMean component
+ */
+
+const MAX_INPUT_LENGTH = 128;
+const MAX_NORMALIZED_DISTANCE = 0.34;
+
+export interface PageCandidate {
+ path: string;
+ title: string;
+}
+
+interface NormalizedPath {
+ full: string;
+ leaf: string;
+}
+
+interface Comparison {
+ distance: number;
+ ratio: number;
+ length: number;
+}
+
+interface RankedPage {
+ page: PageCandidate;
+ matchTier: number;
+ comparison: Comparison;
+}
+
+function decodePath(path: string): string {
+ try {
+ return decodeURIComponent(path);
+ } catch {
+ return path;
+ }
+}
+
+function normalizeSegment(segment: string): string {
+ return segment.toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+
+function normalizeWords(value: string): string[] {
+ return value
+ .toLowerCase()
+ .replace(/[’']/g, '')
+ .split(/[^a-z0-9]+/)
+ .filter(Boolean);
+}
+
+function normalizePath(path: string): NormalizedPath {
+ const pathname = decodePath(path).split(/[?#]/, 1)[0];
+ const segments = pathname
+ .split('/')
+ .filter(Boolean)
+ .map(normalizeSegment)
+ .filter(Boolean);
+
+ return {
+ full: segments.join('/'),
+ leaf: segments.at(-1) ?? '',
+ };
+}
+
+function levenshteinDistance(a: string, b: string): number {
+ if (a === b) {
+ return 0;
+ }
+ if (a.length === 0) {
+ return b.length;
+ }
+ if (b.length === 0) {
+ return a.length;
+ }
+
+ let previous = Array.from({length: b.length + 1}, (_, index) => index);
+
+ for (let i = 1; i <= a.length; i++) {
+ const current = [i];
+ for (let j = 1; j <= b.length; j++) {
+ current[j] = Math.min(
+ current[j - 1] + 1,
+ previous[j] + 1,
+ previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1),
+ );
+ }
+ previous = current;
+ }
+
+ return previous[b.length];
+}
+
+function compare(a: string, b: string): Comparison {
+ const length = Math.max(a.length, b.length);
+ if (length === 0) {
+ return {distance: Number.POSITIVE_INFINITY, ratio: 1, length};
+ }
+
+ const distance = levenshteinDistance(a, b);
+ return {distance, ratio: distance / length, length};
+}
+
+function isHighConfidence(comparison: Comparison): boolean {
+ const maxDistance = Math.max(1, Math.floor(comparison.length * 0.34));
+ return (
+ comparison.distance <= maxDistance &&
+ comparison.ratio <= MAX_NORMALIZED_DISTANCE
+ );
+}
+
+export function findSimilarPages(
+ pathname: string,
+ pages: readonly PageCandidate[],
+ limit = 3,
+): PageCandidate[] {
+ if (pathname.length > MAX_INPUT_LENGTH || limit <= 0) {
+ return [];
+ }
+
+ const requested = normalizePath(pathname);
+ if (!requested.leaf) {
+ return [];
+ }
+
+ const seen = new Set<string>();
+ const ranked: RankedPage[] = [];
+
+ for (const page of pages) {
+ if (seen.has(page.path)) {
+ continue;
+ }
+ seen.add(page.path);
+
+ const candidate = normalizePath(page.path);
+ if (!candidate.leaf || page.path === pathname) {
+ continue;
+ }
+
+ const terms = [
+ candidate.leaf,
+ normalizeSegment(page.title),
+ ...normalizeWords(page.title),
+ ].filter(Boolean);
+ const termComparisons = terms.map(term => compare(requested.leaf, term));
+ const fullComparison = compare(requested.full, candidate.full);
+ const comparison = [...termComparisons, fullComparison].sort(
+ (a, b) => a.ratio - b.ratio || a.distance - b.distance,
+ )[0];
+ const exactTerm = termComparisons.some(result => result.distance === 0);
+ const partialTerm = terms.some(
+ term =>
+ requested.leaf.length >= 4 &&
+ term.length >= 4 &&
+ (term.includes(requested.leaf) || requested.leaf.includes(term)),
+ );
+ const matchTier = exactTerm ? 0 : partialTerm ? 1 : 2;
+
+ if (matchTier === 2 && !isHighConfidence(comparison)) {
+ continue;
+ }
+
+ ranked.push({page, matchTier, comparison});
+ }
+
+ return ranked
+ .sort((a, b) => {
+ return (
+ a.matchTier - b.matchTier ||
+ a.comparison.ratio - b.comparison.ratio ||
+ a.comparison.distance - b.comparison.distance ||
+ a.page.path.length - b.page.path.length ||
+ a.page.title.localeCompare(b.page.title)
+ );
+ })
+ .slice(0, limit)
+ .map(match => match.page);
+}
diff --git a/apps/docsite/src/lib/pageTitles.ts b/apps/docsite/src/lib/pageTitles.ts
new file mode 100644
index 0000000000..0fcdbb7dc5
--- /dev/null
+++ b/apps/docsite/src/lib/pageTitles.ts
@@ -0,0 +1,9 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Canonical titles for hand-authored docsite pages.
+ * @output Shared page-title constants for metadata, headings, and route recovery
+ * @position Lightweight source of truth consumed by server and client modules
+ */
+
+export const CHANGELOG_PAGE_TITLE = "What's New";