@terrafirmagreg-team/kit 1.2.10 → 1.2.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terrafirmagreg-team/kit",
-  "version": "1.2.10",
+  "version": "1.2.12",
   "type": "module",
   "description": "Fumadocs content engine",
   "license": "LGPL-3.0-only",
@@ -24,11 +24,11 @@
   "dependencies": {
     "@base-ui/react": "^1.9.0",
     "@icons-pack/react-simple-icons": "13.15.1",
-    "@terrafirmagreg-team/data": "^1.2.2",
-    "@terrafirmagreg-team/mdx": "^1.2.4",
-    "@terrafirmagreg-team/sites": "^1.2.1",
-    "@terrafirmagreg-team/translate": "^1.2.6",
-    "@terrafirmagreg-team/ui": "^1.2.7",
+    "@terrafirmagreg-team/data": "^1.2.3",
+    "@terrafirmagreg-team/mdx": "^1.2.6",
+    "@terrafirmagreg-team/sites": "^1.2.2",
+    "@terrafirmagreg-team/translate": "^1.2.8",
+    "@terrafirmagreg-team/ui": "^1.2.9",
     "fumadocs-core": "16.17.10",
     "lucide-react": "^1.63.0",
     "server-only": "^0.0.1",

package/src/components/layouts/layout.tsx

@@ -21,6 +21,7 @@ import {
 } from '@terrafirmagreg-team/ui/components/blocks/nav/site-menu';
 import { buttonVariants } from '@terrafirmagreg-team/ui/components/ui/button';
 import { cn } from '@terrafirmagreg-team/ui/lib/utils/cn';
+import { skeletonTree } from '@terrafirmagreg-team/ui/lib/tree';
 import { Globe } from 'lucide-react';
 import {
   SiCurseforge,
@@ -92,7 +93,7 @@ export function Layout({
   const pinned = current ? current.version : undefined;
   const meta = sectionDatasets.find((item) => item.id === baseId);
   const failedDatasets = useFailedDatasets();
-  const featureHidden = baseId !== undefined && failedDatasets.includes(baseId);
+  const datasetFailed = baseId !== undefined && failedDatasets.includes(baseId);
   useDatasetAccent(meta?.accent);
   const nav = useNavOptions({ section, catalog });
   const pathname = usePathname();
@@ -110,12 +111,14 @@ export function Layout({
     $id: `${section}:empty`,
   };
   const tree = useTree(serverTree);
+  const effectiveTree =
+    datasetFailed && !tree.children.length ? skeletonTree() : tree;
   const pinnedTree = useMemo(
     () =>
       pinned && baseId
-        ? pinTreeDataset(tree, section, baseId, pinned)
-        : tree,
-    [tree, section, baseId, pinned],
+        ? pinTreeDataset(effectiveTree, section, baseId, pinned)
+        : effectiveTree,
+    [effectiveTree, section, baseId, pinned],
   );
   const locales = meta?.languages ? localeItems(meta.languages) : undefined;
   const links = baseId
@@ -177,7 +180,7 @@ export function Layout({
               <LeftSidebarSearch />
               <Switcher {...nav.section} />
               <Switcher {...nav.dataset} />
-              {Feature && !featureHidden ? (
+              {Feature ? (
                 <>
                   <LeftSidebarSeparator />
                   <Feature />

package/src/components/page-actions.tsx

@@ -20,10 +20,6 @@ import { ItemRow } from '@terrafirmagreg-team/ui/components/blocks/list/row';
 import { useUntranslated } from '@terrafirmagreg-team/ui/hooks/use-lang';
 import { useTranslations } from '@terrafirmagreg-team/translate/hooks/use-translations';
 import { useCopyButton } from '@terrafirmagreg-team/ui/hooks/use-copy-button';
-import {
-  openPageMarkdown,
-  pageMarkdown,
-} from '@terrafirmagreg-team/mdx/lib/markdown';
 import type { TranslationState } from '@terrafirmagreg-team/translate/server';
 
 function ActionButton({
@@ -70,12 +66,10 @@ export function MarkdownCopyButton({
   );
 }
 
-export function CopyPageMarkdown({ title }: { title: string }) {
+export function CopyPageMarkdown({ mdUrl }: { mdUrl: string }) {
   return (
     <MarkdownCopyButton
-      getMarkdown={() =>
-        pageMarkdown(document.querySelector('[data-md-root]'), title)
-      }
+      getMarkdown={() => fetch(mdUrl).then((res) => res.text())}
     />
   );
 }
@@ -107,12 +101,10 @@ export function UntranslatedActions({
 
 export function ViewOptionsPopover({
   githubUrl,
-  title,
   mdUrl,
   ...props
 }: ComponentProps<typeof PopoverTrigger> & {
   githubUrl?: string;
-  title?: string;
   mdUrl?: string;
 }) {
   const t = useTranslations();
@@ -122,17 +114,9 @@ export function ViewOptionsPopover({
       href: githubUrl,
       icon: <SiGithub color="currentColor" className="size-4" />,
     },
-    (mdUrl || title !== undefined) && {
+    mdUrl && {
       title: t('View as Markdown', { note: 'ui.view_markdown' }),
-      ...(mdUrl
-        ? { href: mdUrl }
-        : {
-            onClick: () =>
-              void openPageMarkdown(
-                document.querySelector('[data-md-root]'),
-                title!,
-              ),
-          }),
+      href: mdUrl,
       icon: <TextIcon className="size-4" />,
     },
   ].filter((v) => !!v);
@@ -163,9 +147,9 @@ export function ViewOptionsPopover({
         {items.map((item) => (
           <ItemRow
             key={item.title}
-            {...('href' in item
-              ? { href: item.href, target: '_blank', rel: 'noreferrer noopener' }
-              : { onClick: item.onClick })}
+            href={item.href}
+            target="_blank"
+            rel="noreferrer noopener"
             media={item.icon}
             title={item.title}
             trailing={
@@ -181,20 +165,18 @@ export function ViewOptionsPopover({
 export function PageActions({
   copied,
   crowdinUrl,
-  title,
   mdUrl,
   githubUrl,
 }: {
   copied?: TranslationState;
   crowdinUrl?: string;
-  title: string;
   mdUrl?: string;
   githubUrl?: string;
 }) {
   return (
     <>
-      <CopyPageMarkdown title={title} />
-      <ViewOptionsPopover title={title} mdUrl={mdUrl} githubUrl={githubUrl} />
+      {mdUrl ? <CopyPageMarkdown mdUrl={mdUrl} /> : null}
+      <ViewOptionsPopover mdUrl={mdUrl} githubUrl={githubUrl} />
       <UntranslatedActions copied={copied} crowdinUrl={crowdinUrl} />
     </>
   );

package/src/components/page-features.tsx

@@ -0,0 +1,30 @@
+import type {
+  SectionFeatures,
+  SectionPageContext,
+} from '../types/features.ts';
+import type { ReactNode } from 'react';
+
+export function pageFeatureNodes(
+  ctx: SectionPageContext,
+  features: SectionFeatures,
+  body: ReactNode,
+): {
+  actionsRight: ReactNode;
+  body: ReactNode;
+  footer: ReactNode;
+  comments: ReactNode;
+} {
+  const wrapped = features.wrapBody ? (
+    features.wrapBody(body, ctx)
+  ) : (
+    <div data-md-root className="contents">
+      {body}
+    </div>
+  );
+  return {
+    actionsRight: features.actionsRight?.(ctx),
+    body: wrapped,
+    footer: features.footer?.(ctx),
+    comments: features.comments?.(ctx),
+  };
+}

package/src/components/views/dataset.tsx

@@ -3,13 +3,11 @@ import { notFound } from 'next/navigation';
 import type { Metadata } from 'next';
 import { LangContentSwitch } from '@terrafirmagreg-team/ui/components/blocks/lang/content';
 import {
+  datasetLandingMetadata,
   generateDatasetLandingParams,
-  getDatasetLanding,
   resolveDatasetLanding,
 } from '@terrafirmagreg-team/kit/lib/landing';
 import { sectionDatasets } from '@terrafirmagreg-team/kit/lib/datasets';
-import { sectionUrl } from '@terrafirmagreg-team/sites/location';
-import { canonicalUrl } from '@terrafirmagreg-team/kit/lib/urls';
 import type { DatasetLanding, SectionKey } from '@terrafirmagreg-team/kit/types';
 import {
   localeLoader,
@@ -58,22 +56,11 @@ export function createDatasetLandingPage<S extends SectionKey>(
     params,
   }: DatasetPageParams): Promise<Metadata> {
     const { slug } = await params;
-    const page = getDatasetLanding(
+    return datasetLandingMetadata(
       section,
       slug,
-      'en_us',
       await sectionDatasets(section),
     );
-    if (!page) notFound();
-    return {
-      title: page.title,
-      description: page.description,
-      alternates: {
-        canonical: canonicalUrl(
-          `${sectionUrl(section)}/${(slug ?? []).join('/')}`,
-        ),
-      },
-    };
   }
 
   return { Page, generateStaticParams, generateMetadata };

package/src/components/views/not-found.tsx

@@ -1,8 +1,7 @@
 'use client';
 import { useEffect, useRef } from 'react';
-import { FileQuestion } from 'lucide-react';
-import { useRouter } from 'next/navigation';
-import { sectionUrl } from '@terrafirmagreg-team/sites/location';
+import { usePathname, useRouter } from 'next/navigation';
+import { isSectionKey, sectionUrl } from '@terrafirmagreg-team/sites/location';
 import { useTranslations } from '@terrafirmagreg-team/translate/hooks/use-translations';
 import { LangLink } from '@terrafirmagreg-team/ui/components/blocks/lang/link';
 import { EmptyState } from '@terrafirmagreg-team/ui/components/blocks/page/empty-state';
@@ -10,6 +9,7 @@ import { buttonVariants } from '@terrafirmagreg-team/ui/components/ui/button';
 import { cn } from '@terrafirmagreg-team/ui/lib/utils/cn';
 import { requestDumpRetry } from '@terrafirmagreg-team/data/lib/dump-status';
 import { useDumpStatus } from '@terrafirmagreg-team/kit/hooks/use-dump-status';
+import { useSectionCatalog } from '@terrafirmagreg-team/kit/hooks/use-catalog';
 import type { SectionDataset, SectionKey } from '@terrafirmagreg-team/kit/types';
 
 export function SectionNotFound({
@@ -39,7 +39,7 @@ export function SectionNotFound({
 
   if (!datasets.length)
     return (
-      <div className="flex flex-col items-center gap-3 py-16">
+      <div className="mx-2 flex min-w-0 flex-1 flex-col items-center justify-center gap-3 bg-background [grid-area:main] md:my-2 md:overflow-clip md:rounded-2xl md:border md:shadow-sm">
         <EmptyState variant="missing">
           {t('Section data is temporarily unavailable. Try again later.', {
             note: 'kit.section_unavailable',
@@ -55,13 +55,27 @@ export function SectionNotFound({
       </div>
     );
   return (
-    <div className="flex flex-col items-center gap-3 py-16 text-muted-foreground">
-      <FileQuestion className="size-10" />
-      <p>{t('Page not found', { note: 'ui.not_found' })}</p>
+    <div className="mx-2 flex min-w-0 flex-1 flex-col items-center justify-center gap-6 bg-background [grid-area:main] md:my-2 md:overflow-clip md:rounded-2xl md:border md:shadow-sm">
+      <div className="flex flex-col items-center gap-2 text-center">
+        <span
+          aria-hidden
+          className="select-none text-6xl leading-none font-semibold tracking-tighter text-muted-foreground/25"
+        >
+          404
+        </span>
+        <p className="font-medium text-foreground">
+          {t('Page not found', { note: 'ui.not_found' })}
+        </p>
+        <p className="max-w-sm text-sm text-balance text-muted-foreground">
+          {t("The page you're looking for doesn't exist or was moved.", {
+            note: 'ui.not_found_description',
+          })}
+        </p>
+      </div>
       <LangLink
         href={sectionUrl(section, datasets[0].id)}
         className={cn(
-          buttonVariants({ variant: 'outline', size: 'xs' }),
+          buttonVariants({ variant: 'outline', size: 'sm' }),
           'no-underline',
         )}
       >
@@ -70,3 +84,55 @@ export function SectionNotFound({
     </div>
   );
 }
+
+export function RootNotFound() {
+  const pathname = usePathname();
+  const catalog = useSectionCatalog();
+  const t = useTranslations();
+  const parts = pathname.split('/').filter(Boolean);
+  const section = isSectionKey(parts[0]) ? parts[0] : undefined;
+  const datasets = section ? catalog[section] : undefined;
+  const known = datasets?.some((dataset) => dataset.id === parts[1]);
+  const href =
+    section && datasets?.length
+      ? `/${section}/${known ? parts[1] : datasets[0].id}`
+      : '/';
+
+  return (
+    <main className="flex min-h-dvh flex-col items-center justify-center gap-8 p-8">
+      <div className="flex flex-col items-center gap-3 text-center">
+        <span
+          aria-hidden
+          className="select-none bg-gradient-to-b from-muted-foreground/40 to-muted-foreground/10 bg-clip-text text-[8rem] leading-none font-semibold tracking-tighter text-transparent"
+        >
+          404
+        </span>
+        <h1 className="text-xl font-semibold text-foreground">
+          {t('Page not found', { note: 'ui.not_found' })}
+        </h1>
+        <p className="max-w-sm text-sm text-balance text-muted-foreground">
+          {t("The page you're looking for doesn't exist or was moved.", {
+            note: 'ui.not_found_description',
+          })}
+        </p>
+      </div>
+      <div className="flex items-center gap-2">
+        <LangLink
+          href={href}
+          className={cn(buttonVariants({ size: 'sm' }), 'no-underline')}
+        >
+          {t('Back', { note: 'ui.back' })}
+        </LangLink>
+        <LangLink
+          href="/"
+          className={cn(
+            buttonVariants({ variant: 'ghost', size: 'sm' }),
+            'no-underline',
+          )}
+        >
+          {t('Go home', { note: 'ui.go_home' })}
+        </LangLink>
+      </div>
+    </main>
+  );
+}

package/src/components/views/routes.tsx

@@ -20,6 +20,7 @@ import {
   sectionDatasets,
 } from '@terrafirmagreg-team/kit/lib/datasets';
 import {
+  datasetLandingMetadata,
   generateDatasetLandingParams,
   getDatasetLanding,
 } from '@terrafirmagreg-team/kit/lib/landing';
@@ -33,7 +34,6 @@ import {
   localeLoader,
   registerLocaleRenderer,
 } from '@terrafirmagreg-team/kit/lib/locale/renderer';
-import { canonicalUrl } from '@terrafirmagreg-team/kit/lib/urls';
 import { sectionUrl } from '@terrafirmagreg-team/sites/location';
 import { langContent, loadLocaleRegistry } from '@terrafirmagreg-team/translate/server';
 import type {
@@ -170,6 +170,7 @@ export function createSectionRoutes<
     }
     if (!PageView) return null;
     return renderSectionWorkspace({
+      section,
       source: src as SectionSource,
       slug,
       contentDir: source.contentDir ?? `content/${section}`,
@@ -275,22 +276,12 @@ export function createSectionRoutes<
 
   async function generateMetadata({ params }: RouteParams): Promise<Metadata> {
     const { slug } = await params;
-    if (slug?.length === 1 && landing) {
-      const page = getDatasetLanding(
+    if (slug?.length === 1 && landing)
+      return datasetLandingMetadata(
         section,
         slug,
-        'en_us',
         await sectionDatasets(section),
       );
-      if (!page) notFound();
-      return {
-        title: page.title,
-        description: page.description,
-        alternates: {
-          canonical: canonicalUrl(`${sectionUrl(section)}/${slug.join('/')}`),
-        },
-      };
-    }
     if (!PageView) return {};
     const src = (await source.getSource()) as SectionSource | undefined;
     if (src) {

package/src/components/views/section.tsx

@@ -10,11 +10,13 @@ import {
 import { loadLocaleRegistry } from '@terrafirmagreg-team/translate/server';
 import { readPageSource, translationState } from '@terrafirmagreg-team/translate/server';
 import { resolvePage, type SectionSource } from '@terrafirmagreg-team/kit/lib/page';
+import { pageJsonLd } from '@terrafirmagreg-team/kit/lib/jsonld';
 import { findNeighbour } from 'fumadocs-core/page-tree';
 import { stripLangFromUrl } from '@terrafirmagreg-team/translate/lib/slug';
 import { sectionConfig } from '@terrafirmagreg-team/kit/lib/config';
 import type {
   DatasetCatalog,
+  SectionKey,
   SectionPage,
   SectionTrees,
 } from '@terrafirmagreg-team/kit/types';
@@ -53,6 +55,7 @@ export type SectionPageViewFn = (
 ) => SectionPageView | Promise<SectionPageView>;
 
 export async function renderSectionWorkspace({
+  section,
   source,
   slug,
   contentDir,
@@ -64,6 +67,7 @@ export async function renderSectionWorkspace({
   page,
   lang,
 }: {
+  section: SectionKey;
   source: SectionSource;
   slug: string[] | undefined;
   contentDir: string;
@@ -117,6 +121,18 @@ export async function renderSectionWorkspace({
     history,
     features,
   });
-  return renderSectionView(view);
+  const jsonLd = JSON.stringify(pageJsonLd({ section, page, crumbs, lang }));
+  return renderSectionView({
+    ...view,
+    node: (
+      <>
+        <script
+          type="application/ld+json"
+          dangerouslySetInnerHTML={{ __html: jsonLd }}
+        />
+        {view.node}
+      </>
+    ),
+  });
 }
 

package/src/components/views/unavailable.tsx

@@ -1,22 +1,23 @@
 'use client';
 
 import type { ReactNode } from 'react';
+import { CloudOff } from 'lucide-react';
 import { useTranslations } from '@terrafirmagreg-team/translate/hooks/use-translations';
 import { requestDumpRetry } from '@terrafirmagreg-team/data/lib/dump-status';
-import { EmptyState } from '@terrafirmagreg-team/ui/components/blocks/page/empty-state';
 import { buttonVariants } from '@terrafirmagreg-team/ui/components/ui/button';
 import { cn } from '@terrafirmagreg-team/ui/lib/utils/cn';
 
 export function DumpUnavailable({ children }: { children?: ReactNode }) {
   const t = useTranslations();
   return (
-    <div className="flex flex-col items-center gap-3 py-10">
-      <EmptyState variant="missing">
+    <div className="pointer-events-auto flex max-w-xs flex-col items-center gap-2.5 rounded-lg border border-border bg-popover px-5 py-4 text-center shadow-lg">
+      <CloudOff className="size-5 text-muted-foreground" />
+      <p className="text-sm text-muted-foreground">
         {children ??
           t('Section data is temporarily unavailable. Try again later.', {
             note: 'kit.section_unavailable',
           })}
-      </EmptyState>
+      </p>
       <button
         type="button"
         onClick={requestDumpRetry}
@@ -27,3 +28,11 @@ export function DumpUnavailable({ children }: { children?: ReactNode }) {
     </div>
   );
 }
+
+export function DumpUnavailableOverlay({ children }: { children?: ReactNode }) {
+  return (
+    <div className="pointer-events-none absolute inset-0 z-20 flex items-center justify-center p-6">
+      {children ?? <DumpUnavailable />}
+    </div>
+  );
+}

package/src/lib/config.ts

@@ -43,6 +43,7 @@ export type SectionConfigInput = {
         url: string;
         icon?: string;
       }[];
+      sections?: readonly SectionKey[];
       guide?: { bookOrder?: readonly string[] };
     }
   >;

package/src/lib/datasets.ts

@@ -4,6 +4,7 @@ import { sectionConfig } from './config';
 import { sections } from './sources';
 import { datasetId } from './tree';
 import { createAsyncCache } from '@terrafirmagreg-team/data/lib/async-cache';
+import { dumpStatusSnapshot } from '@terrafirmagreg-team/data/lib/dump-status';
 import { loadLocaleRegistry, sortLangCodes } from '@terrafirmagreg-team/translate/server';
 import type { DatasetRef } from '@terrafirmagreg-team/sites/location';
 import { sectionTabs } from '@terrafirmagreg-team/sites/sections';
@@ -79,6 +80,30 @@ async function datasetMeta(
   return meta ? metaFields(meta) : {};
 }
 
+async function sectionDatasetMeta(
+  section: SectionKey,
+  id: string,
+): Promise<Omit<SectionDataset, 'id' | 'languages'>> {
+  const meta = await datasetMeta(section, id);
+  return Object.values(meta).some((value) => value !== undefined)
+    ? meta
+    : datasetMeta('docs', id);
+}
+
+const lastGoodDatasets = new Map<SectionKey, Map<string, SectionDataset>>();
+
+function rememberDataset(section: SectionKey, row: SectionDataset) {
+  let good = lastGoodDatasets.get(section);
+  if (!good) lastGoodDatasets.set(section, (good = new Map()));
+  good.set(row.id, row);
+}
+
+function datasetMembership(section: SectionKey, id: string): boolean {
+  const declared = sectionConfig().datasetConfig[id]?.sections;
+  if (declared) return declared.includes(section);
+  return lastGoodDatasets.get(section)?.has(id) === true;
+}
+
 function metaFields(
   meta: Record<string, unknown>,
 ): Omit<SectionDataset, 'id' | 'languages'> {
@@ -144,47 +169,59 @@ async function dumpDatasets(
 ): Promise<SectionDataset[]> {
   const dump = sectionConfig().dump;
   if (!dump) return [];
-  const refs = await dump.discoverDatasets();
+  const refs = await dump.discoverDatasets().catch(() => [] as DatasetRef[]);
   const versions = new Map<string, string[]>();
-  for (const ref of refs) {
-    const { id, version } = ref;
-    if (version) {
-      const list = versions.get(id) ?? [];
-      list.push(version);
-      versions.set(id, list);
+  const ids: string[] = [];
+  if (refs.length) {
+    for (const ref of refs) {
+      const { id, version } = ref;
+      if (version) {
+        const list = versions.get(id) ?? [];
+        list.push(version);
+        versions.set(id, list);
+      } else {
+        ids.push(id);
+      }
+    }
+  } else {
+    for (const id of Object.keys(sectionConfig().datasetConfig)) {
+      if (datasetMembership(section, id)) ids.push(id);
     }
   }
-  const ids = refs.filter((ref) => !ref.version);
-  const usable = await Promise.all(
-    ids.map(async (ref) => {
-      const { id } = ref;
-      const index = await dump.loadDataset(ref).catch(() => null);
-      if (!index || !hasContent(index)) return null;
-      return {
-        id,
-        languages: datasetLanguages(index.manifest.languages ?? []),
-      };
-    }),
-  );
   return (
     await Promise.all(
-      usable
-        .filter((row): row is { id: string; languages: Lang[] } => row !== null)
-        .map(async ({ id, languages }) => ({
+      ids.map(async (id): Promise<SectionDataset | null> => {
+        const index = await dump.loadDataset({ id }).catch(() => null);
+        if (!index) {
+          if (dumpStatusSnapshot().statuses[id]?.status !== 'failed')
+            return null;
+          const good = lastGoodDatasets.get(section)?.get(id);
+          if (good) return good;
+          if (!datasetMembership(section, id)) return null;
+          return {
+            id,
+            languages: datasetLanguages([]),
+            ...(await sectionDatasetMeta(section, id)),
+            ...datasetAppearance(id),
+          };
+        }
+        if (!hasContent(index)) return null;
+        const row: SectionDataset = {
           id,
-          languages,
+          languages: datasetLanguages(index.manifest.languages ?? []),
           ...(versions.get(id)?.length
             ? { versions: versions.get(id)!.sort(compareVersions).reverse() }
             : {}),
-          ...(await datasetMeta(section, id).then((meta) =>
-            Object.values(meta).some((value) => value !== undefined)
-              ? meta
-              : datasetMeta('docs', id),
-          )),
+          ...(await sectionDatasetMeta(section, id)),
           ...datasetAppearance(id),
-        })),
-      )
-  ).sort(datasetOrder);
+        };
+        rememberDataset(section, row);
+        return row;
+      }),
+    )
+  )
+    .filter((row): row is SectionDataset => row !== null)
+    .sort(datasetOrder);
 }
 
 export function sectionDatasets(

package/src/lib/jsonld.ts

@@ -0,0 +1,46 @@
+import 'server-only';
+import { stripLangFromUrl } from '@terrafirmagreg-team/translate/lib/slug';
+import { sectionConfig } from './config';
+import { canonicalUrl } from './urls';
+import type { SectionCrumb } from './breadcrumb';
+import type { SectionKey, SectionPage } from '@terrafirmagreg-team/kit/types';
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
+
+export function pageJsonLd({
+  section,
+  page,
+  crumbs,
+  lang,
+}: {
+  section: SectionKey;
+  page: SectionPage;
+  crumbs: readonly SectionCrumb[];
+  lang: Lang;
+}): Record<string, unknown>[] {
+  const languages = [...sectionConfig().knownLanguages];
+  const url = canonicalUrl(stripLangFromUrl(page.url, languages));
+  const items = crumbs.length ? crumbs : [{ name: page.data.title }];
+  return [
+    {
+      '@context': 'https://schema.org',
+      '@type': 'Article',
+      headline: page.data.title,
+      description: page.data.description,
+      url,
+      inLanguage: lang.replace('_', '-'),
+      isPartOf: { '@type': 'WebSite', url: canonicalUrl(`/${section}`) },
+    },
+    {
+      '@context': 'https://schema.org',
+      '@type': 'BreadcrumbList',
+      itemListElement: items.map((crumb, index) => ({
+        '@type': 'ListItem',
+        position: index + 1,
+        name: crumb.name,
+        item: crumb.url
+          ? canonicalUrl(stripLangFromUrl(crumb.url, languages))
+          : url,
+      })),
+    },
+  ];
+}

package/src/lib/landing.ts

@@ -1,5 +1,9 @@
 import 'server-only';
+import type { Metadata } from 'next';
+import { notFound } from 'next/navigation';
 import { loadLocaleRegistry } from '@terrafirmagreg-team/translate/server';
+import { sectionUrl } from '@terrafirmagreg-team/sites/location';
+import { canonicalUrl, getDatasetImageUrl } from './urls';
 import { datasetSlugs, findDataset } from './datasets';
 import type {
   DatasetLanding,
@@ -30,6 +34,36 @@ export function getDatasetLanding(
   };
 }
 
+export function datasetLandingMetadata(
+  section: SectionKey,
+  slug: string[] | undefined,
+  datasets: readonly SectionDataset[],
+): Metadata {
+  const page = getDatasetLanding(section, slug, 'en_us', datasets);
+  if (!page) notFound();
+  const meta = findDataset(datasets, { id: slug?.[0] ?? '' });
+  const description = page.description ?? meta?.description;
+  const title = page.datasetTitle ?? page.title;
+  const url = canonicalUrl(`${sectionUrl(section)}/${(slug ?? []).join('/')}`);
+  return {
+    title,
+    description,
+    alternates: { canonical: url },
+    openGraph: {
+      type: 'website',
+      url,
+      title,
+      description,
+      images: getDatasetImageUrl(section, slug?.[0] ?? '').url,
+    },
+    twitter: {
+      card: 'summary_large_image',
+      title,
+      description,
+    },
+  };
+}
+
 export function resolveDatasetLanding(
   section: SectionKey,
   slug: string[] | undefined,

package/src/lib/page.ts

@@ -1,30 +1,16 @@
 import type { Metadata } from 'next';
 import { notFound } from 'next/navigation';
-import { createGetUrl } from 'fumadocs-core/source';
 import { firstLocalizedPage } from '@terrafirmagreg-team/translate/server';
 import { loadLocaleRegistry } from '@terrafirmagreg-team/translate/server';
 import { stripLangFromUrl, toInternalSlugs, toPublicSlug } from '@terrafirmagreg-team/translate/lib/slug';
 import { sectionConfig } from './config';
 import { sectionDatasets } from './datasets';
+import { canonicalUrl, getPageImageUrl } from './urls';
 import type { SectionKey, SectionPage, SectionSource } from '@terrafirmagreg-team/kit/types';
 import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
 
 export type { SectionSource } from '@terrafirmagreg-team/kit/types';
-
-const canonicalUrl = (pathname: string): string =>
-  new URL(
-    pathname.startsWith('/') ? pathname : `/${pathname}`,
-    sectionConfig().siteUrl,
-  ).toString();
-
-let imageUrl: ReturnType<typeof createGetUrl> | undefined;
-const getImageUrl = () =>
-  (imageUrl ??= createGetUrl(sectionConfig().previewRoute));
-
-function getDatasetImageUrl(section: string, dataset: string) {
-  const segments = [section, dataset, 'image.png'];
-  return { segments, url: getImageUrl()(segments) };
-}
+export { getDatasetImageUrl } from './urls';
 
 export function getPage<S extends SectionSource>(
   source: S,
@@ -97,7 +83,7 @@ export async function sectionMetadata(
       url,
       title: doc.data.title,
       description: doc.data.description,
-      images: getDatasetImageUrl(section, doc.slugs[0]).url,
+      images: getPageImageUrl(section, doc.slugs).url,
     },
     twitter: {
       card: 'summary_large_image',

package/src/lib/urls.ts

@@ -15,3 +15,21 @@ export function getDatasetImageUrl(section: string, dataset: string) {
   };
 }
 
+export function getPageImageUrl(section: string, slugs: string[]) {
+  const segments = [section, ...slugs, 'image.png'];
+
+  return {
+    segments,
+    url: createGetUrl(sectionConfig().previewRoute)(segments),
+  };
+}
+
+export function createGitFileUrl(git: {
+  user: string;
+  repo: string;
+  branch: string;
+}) {
+  return (filePath: string) =>
+    `https://github.com/${git.user}/${git.repo}/blob/${git.branch}/${filePath}`;
+}
+