fix(docs): separate SEO and display titles

Author: ObservedObserver

docs/app/docs/[[...slug]]/page.tsx

@@ -7,9 +7,11 @@ import {
 } from 'fumadocs-ui/page';
 import { notFound } from 'next/navigation';
 import { createRelativeLink } from 'fumadocs-ui/mdx';
+import defaultMdxComponents from 'fumadocs-ui/mdx';
 import { getMDXComponents } from '@/mdx-components';
 import type { Metadata } from 'next';
 import { buildSeoProfile } from '@/lib/seo';
+import { getDisplayTitle, getDisplayTitleNode } from '@/lib/title';
 
 const siteUrl = (process.env.NEXT_PUBLIC_SITE_URL ?? 'https://ml.kanaries.net').replace(/\/$/, '');
 
@@ -24,6 +26,17 @@ export default async function Page(props: {
   const slug = params.slug ?? [];
   const path = slug.length ? `/docs/${slug.join('/')}` : '/docs';
   const canonicalUrl = new URL(path, siteUrl).toString();
+  const displayTitle = getDisplayTitle(page.data.title);
+  const displayToc = page.data.toc
+    .map((item) => {
+      const title = getDisplayTitleNode(item.title);
+
+      return {
+        ...item,
+        title,
+      };
+    })
+    .filter((item) => item.title !== displayTitle);
   const seoProfile = buildSeoProfile({
     title: page.data.title,
     description: page.data.description,
@@ -66,14 +79,24 @@ export default async function Page(props: {
     <>
       <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(articleLd) }} />
       <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(faqLd) }} />
-      <DocsPage toc={page.data.toc} full={page.data.full}>
-        <DocsTitle>{page.data.title}</DocsTitle>
+      <DocsPage toc={displayToc} full={page.data.full}>
+        <DocsTitle>{displayTitle}</DocsTitle>
         <DocsDescription>{page.data.description}</DocsDescription>
         <DocsBody>
           <MDXContent
             components={getMDXComponents({
               // this allows you to link to other pages with relative file paths
               a: createRelativeLink(source, page),
+              h1: (props) => {
+                const children = getDisplayTitleNode(props.children);
+
+                if (children === displayTitle) return null;
+
+                return defaultMdxComponents.h1({
+                  ...props,
+                  children,
+                });
+              },
             })}
           />
           <section className="mt-12 rounded-lg border border-fd-border bg-fd-muted/40 p-6">

docs/lib/seo.ts

@@ -1,3 +1,5 @@
+import { getDisplayTitle } from '@/lib/title';
+
 type SeoInput = {
   title: string;
   description?: string;
@@ -60,7 +62,7 @@ function unique(values: string[]): string[] {
 }
 
 function titleToTopic(title: string): string {
-  return title.replace(/\s+[-–]\s+@kanaries\/ml.*$/i, '').replace(/\s{2,}/g, ' ').trim();
+  return getDisplayTitle(title.replace(/\s+[-–]\s+@kanaries\/ml.*$/i, '')).replace(/\s{2,}/g, ' ').trim();
 }
 
 function slugToWords(value: string): string {

docs/lib/source.ts

@@ -1,9 +1,20 @@
 import { docs } from '@/.source';
 import { loader } from 'fumadocs-core/source';
+import { getDisplayTitle } from '@/lib/title';
 
 // See https://fumadocs.vercel.app/docs/headless/source-api for more info
 export const source = loader({
   // it assigns a URL to your pages
   baseUrl: '/docs',
   source: docs.toFumadocsSource(),
+  pageTree: {
+    attachFile(node, file) {
+      if (!file) return node;
+
+      return {
+        ...node,
+        name: getDisplayTitle(file.data.data.title) || node.name,
+      };
+    },
+  },
 });

docs/lib/title.ts

@@ -0,0 +1,33 @@
+export function getDisplayTitle(title: string | undefined): string {
+  if (!title) return '';
+
+  return title
+    .replace(/\s+with\s+@kanaries\/ml\s*$/i, '')
+    .replace(/\s+in\s+(?:JavaScript|TypeScript)(?:\s+(?:and|or)\s+(?:JavaScript|TypeScript))*\s*$/i, '')
+    .replace(/\s+JavaScript\s+implementation\s*$/i, '')
+    .replace(/\s{2,}/g, ' ')
+    .trim();
+}
+
+export function getTextFromNode(value: unknown): string | undefined {
+  if (typeof value === 'string') return value;
+  if (typeof value === 'number') return String(value);
+
+  if (Array.isArray(value)) {
+    const text = value.map((item) => getTextFromNode(item)).filter(Boolean).join('');
+    return text || undefined;
+  }
+
+  if (value && typeof value === 'object' && 'props' in value) {
+    return getTextFromNode((value as { props?: { children?: unknown } }).props?.children);
+  }
+
+  return undefined;
+}
+
+export function getDisplayTitleNode<T>(value: T): T | string {
+  const text = getTextFromNode(value);
+  if (!text) return value;
+
+  return getDisplayTitle(text) || text;
+}