feat: add SEO support with metadata, sitemap, and JSON-LD

examples/basic/chronicle.yaml

@@ -1,5 +1,6 @@
 title: My Documentation
 description: Documentation powered by Chronicle
+url: https://docs.example.com
 contentDir: .
 theme:
   name: default
@@ -23,6 +24,10 @@ api:
     server:
       url: https://frontier.raystack.org
       description: Frontier Server
+analytics:
+  enabled: false
+  googleAnalytics:
+    measurementId: G-XXXXXXXXXX
 footer:
   copyright: "© 2024 Chronicle. All rights reserved."
   links:

packages/chronicle/source.config.ts

@@ -11,6 +11,7 @@ export const docs = defineDocs({
   docs: {
     schema: frontmatterSchema.extend({
       order: z.number().optional(),
+      lastModified: z.string().optional(),
     }),
     postprocess: {
       includeProcessedMarkdown: true,

packages/chronicle/src/app/[[...slug]]/page.tsx

@@ -1,3 +1,4 @@
+import type { Metadata, ResolvingMetadata } from 'next'
 import { notFound } from 'next/navigation'
 import type { MDXContent } from 'mdx/types'
 import { loadConfig } from '@/lib/config'
@@ -16,6 +17,41 @@ interface PageData {
   toc: { title: string; url: string; depth: number }[]
 }
 
+export async function generateMetadata(
+  { params }: PageProps,
+  parent: ResolvingMetadata,
+): Promise<Metadata> {
+  const { slug } = await params
+  const page = source.getPage(slug)
+  if (!page) return {}
+  const config = loadConfig()
+  const data = page.data as PageData
+  const parentMetadata = await parent
+
+  const metadata: Metadata = {
+    title: data.title,
+    description: data.description,
+  }
+
+  if (config.url) {
+    const ogParams = new URLSearchParams({ title: data.title })
+    if (data.description) ogParams.set('description', data.description)
+    metadata.openGraph = {
+      ...parentMetadata.openGraph,
+      title: data.title,
+      description: data.description,
+      images: [{ url: `/og?${ogParams.toString()}`, width: 1200, height: 630 }],
+    }
+    metadata.twitter = {
+      ...parentMetadata.twitter,
+      title: data.title,
+      description: data.description,
+    }
+  }
+
+  return metadata
+}
+
 export default async function DocsPage({ params }: PageProps) {
   const { slug } = await params
   const config = loadConfig()
@@ -33,20 +69,33 @@ export default async function DocsPage({ params }: PageProps) {
 
   const tree = buildPageTree()
 
+  const pageUrl = config.url ? `${config.url}/${(slug ?? []).join('/')}` : undefined
+
   return (
-    <Page
-      page={{
-        slug: slug ?? [],
-        frontmatter: {
-          title: data.title,
+    <>
+      <script type="application/ld+json">
+        {JSON.stringify({
+          '@context': 'https://schema.org',
+          '@type': 'Article',
+          headline: data.title,
           description: data.description,
-        },
-        content: <MDXBody components={mdxComponents} />,
-        toc: data.toc ?? [],
-      }}
-      config={config}
-      tree={tree}
-    />
+          ...(pageUrl && { url: pageUrl }),
+        }, null, 2)}
+      </script>
+      <Page
+        page={{
+          slug: slug ?? [],
+          frontmatter: {
+            title: data.title,
+            description: data.description,
+          },
+          content: <MDXBody components={mdxComponents} />,
+          toc: data.toc ?? [],
+        }}
+        config={config}
+        tree={tree}
+      />
+    </>
   )
 }
 

packages/chronicle/src/app/apis/[[...slug]]/page.tsx

@@ -1,3 +1,4 @@
+import type { Metadata, ResolvingMetadata } from 'next'
 import { notFound } from 'next/navigation'
 import type { OpenAPIV3 } from 'openapi-types'
 import { Flex, Headline, Text } from '@raystack/apsara'
@@ -10,6 +11,65 @@ interface PageProps {
   params: Promise<{ slug?: string[] }>
 }
 
+export async function generateMetadata(
+  { params }: PageProps,
+  parent: ResolvingMetadata,
+): Promise<Metadata> {
+  const { slug } = await params
+  const config = loadConfig()
+  const specs = loadApiSpecs(config.api ?? [])
+  const parentMetadata = await parent
+
+  if (!slug || slug.length === 0) {
+    const apiDescription = `API documentation for ${config.title}`
+    const metadata: Metadata = {
+      title: 'API Reference',
+      description: apiDescription,
+    }
+    if (config.url) {
+      metadata.openGraph = {
+        ...parentMetadata.openGraph,
+        title: 'API Reference',
+        description: apiDescription,
+        images: [{ url: `/og?title=${encodeURIComponent('API Reference')}&description=${encodeURIComponent(apiDescription)}`, width: 1200, height: 630 }],
+      }
+      metadata.twitter = {
+        ...parentMetadata.twitter,
+        title: 'API Reference',
+        description: apiDescription,
+      }
+    }
+    return metadata
+  }
+
+  const match = findApiOperation(specs, slug)
+  if (!match) return {}
+
+  const operation = match.operation as OpenAPIV3.OperationObject
+  const title = operation.summary ?? `${match.method.toUpperCase()} ${match.path}`
+  const description = operation.description
+
+  const metadata: Metadata = { title, description }
+
+  if (config.url) {
+    const ogParams = new URLSearchParams({ title })
+    if (description) ogParams.set('description', description)
+    metadata.openGraph = {
+      ...parentMetadata.openGraph,
+      title,
+      description,
+      images: [{ url: `/og?${ogParams.toString()}`, width: 1200, height: 630 }],
+    }
+    metadata.twitter = {
+      ...parentMetadata.twitter,
+      title,
+      description,
+    }
+  }
+
+  return metadata
+}
+
 export default async function ApiPage({ params }: PageProps) {
   const { slug } = await params
   const config = loadConfig()

packages/chronicle/src/app/layout.tsx

@@ -7,8 +7,28 @@ import { Providers } from './providers'
 const config = loadConfig()
 
 export const metadata: Metadata = {
-  title: config.title,
+  title: {
+    default: config.title,
+    template: `%s | ${config.title}`,
+  },
   description: config.description,
+  ...(config.url && {
+    metadataBase: new URL(config.url),
+    openGraph: {
+      title: config.title,
+      description: config.description,
+      url: config.url,
+      siteName: config.title,
+      type: 'website',
+      images: [{ url: '/og?title=' + encodeURIComponent(config.title), width: 1200, height: 630 }],
+    },
+    twitter: {
+      card: 'summary_large_image',
+      title: config.title,
+      description: config.description,
+      images: ['/og?title=' + encodeURIComponent(config.title)],
+    },
+  }),
 }
 
 export default function RootLayout({
@@ -19,6 +39,17 @@ export default function RootLayout({
   return (
     <html lang="en" suppressHydrationWarning>
       <body suppressHydrationWarning>
+        {config.url && (
+          <script type="application/ld+json">
+            {JSON.stringify({
+              '@context': 'https://schema.org',
+              '@type': 'WebSite',
+              name: config.title,
+              description: config.description,
+              url: config.url,
+            }, null, 2)}
+          </script>
+        )}
         <Providers>{children}</Providers>
       </body>
     </html>

packages/chronicle/src/app/og/route.tsx

@@ -0,0 +1,62 @@
+import { ImageResponse } from 'next/og'
+import type { NextRequest } from 'next/server'
+import { loadConfig } from '@/lib/config'
+
+export async function GET(request: NextRequest) {
+  const { searchParams } = request.nextUrl
+  const title = searchParams.get('title') ?? loadConfig().title
+  const description = searchParams.get('description') ?? ''
+  const siteName = loadConfig().title
+
+  return new ImageResponse(
+    (
+      <div
+        style={{
+          height: '100%',
+          width: '100%',
+          display: 'flex',
+          flexDirection: 'column',
+          justifyContent: 'center',
+          padding: '60px 80px',
+          backgroundColor: '#0a0a0a',
+          color: '#fafafa',
+        }}
+      >
+        <div
+          style={{
+            fontSize: 24,
+            color: '#888',
+            marginBottom: 16,
+          }}
+        >
+          {siteName}
+        </div>
+        <div
+          style={{
+            fontSize: 56,
+            fontWeight: 700,
+            lineHeight: 1.2,
+            marginBottom: 24,
+          }}
+        >
+          {title}
+        </div>
+        {description && (
+          <div
+            style={{
+              fontSize: 24,
+              color: '#999',
+              lineHeight: 1.4,
+            }}
+          >
+            {description}
+          </div>
+        )}
+      </div>
+    ),
+    {
+      width: 1200,
+      height: 630,
+    }
+  )
+}

packages/chronicle/src/app/robots.ts

@@ -0,0 +1,10 @@
+import type { MetadataRoute } from 'next'
+import { loadConfig } from '@/lib/config'
+
+export default function robots(): MetadataRoute.Robots {
+  const config = loadConfig()
+  return {
+    rules: { userAgent: '*', allow: '/' },
+    ...(config.url && { sitemap: `${config.url}/sitemap.xml` }),
+  }
+}

packages/chronicle/src/app/sitemap.ts

@@ -0,0 +1,29 @@
+import type { MetadataRoute } from 'next'
+import { loadConfig } from '@/lib/config'
+import { source } from '@/lib/source'
+import { loadApiSpecs } from '@/lib/openapi'
+import { buildApiRoutes } from '@/lib/api-routes'
+
+export default function sitemap(): MetadataRoute.Sitemap {
+  const config = loadConfig()
+  if (!config.url) return []
+
+  const baseUrl = config.url.replace(/\/$/, '')
+
+  const docPages = source.getPages().map((page) => ({
+    url: `${baseUrl}/${page.slugs.join('/')}`,
+    ...(page.data.lastModified && { lastModified: new Date(page.data.lastModified) }),
+  }))
+
+  const apiPages = config.api?.length
+    ? buildApiRoutes(loadApiSpecs(config.api)).map((route) => ({
+        url: `${baseUrl}/apis/${route.slug.join('/')}`,
+      }))
+    : []
+
+  return [
+    { url: baseUrl },
+    ...docPages,
+    ...apiPages,
+  ]
+}

packages/chronicle/src/lib/config.ts

@@ -51,5 +51,6 @@ export function loadConfig(): ChronicleConfig {
     footer: userConfig.footer,
     api: userConfig.api,
     llms: { enabled: false, ...userConfig.llms },
+    analytics: { enabled: false, ...userConfig.analytics },
   }
 }

packages/chronicle/src/types/config.ts

@@ -1,19 +1,30 @@
 export interface ChronicleConfig {
   title: string
   description?: string
+  url?: string
   logo?: LogoConfig
   theme?: ThemeConfig
   navigation?: NavigationConfig
   search?: SearchConfig
   footer?: FooterConfig
   api?: ApiConfig[]
   llms?: LlmsConfig
+  analytics?: AnalyticsConfig
 }
 
 export interface LlmsConfig {
   enabled?: boolean
 }
 
+export interface AnalyticsConfig {
+  enabled?: boolean
+  googleAnalytics?: GoogleAnalyticsConfig
+}
+
+export interface GoogleAnalyticsConfig {
+  measurementId: string
+}
+
 export interface ApiConfig {
   name: string
   spec: string

packages/chronicle/src/types/content.ts

@@ -5,6 +5,7 @@ export interface Frontmatter {
   description?: string
   order?: number
   icon?: string
+  lastModified?: string
 }
 
 export interface Page {