starlight-seo 0.2.0

package/lib/text.js

@@ -0,0 +1,36 @@
+export const length = (value) => [...String(value ?? '')].length
+
+export const pick = (value, lang, locale) => {
+  if (value === undefined || value === null) return undefined
+  if (typeof value !== 'object' || Array.isArray(value)) return value
+  const short = String(lang ?? '').split('-')[0]
+  if (lang && lang in value) return value[lang]
+  if (short && short in value) return value[short]
+  if (locale && locale in value) return value[locale]
+  if ('root' in value) return value.root
+  return Object.values(value)[0]
+}
+
+export const fill = (template, values) =>
+  String(template).replace(/\{(\w+)\}/g, (whole, key) => (key in values ? String(values[key]) : whole))
+
+const ESCAPES = { '<': '\\u003c', '>': '\\u003e', '&': '\\u0026', '\u2028': '\\u2028', '\u2029': '\\u2029' }
+
+export const serialize = (value) => JSON.stringify(value).replace(/[<>&\u2028\u2029]/g, (char) => ESCAPES[char])
+
+const SPECIAL = /[.+^${}()|[\]\\]/g
+
+export const matcher = (pattern) => {
+  const source = String(pattern)
+    .replace(SPECIAL, '\\$&')
+    .replace(/\*\*/g, '\u0000')
+    .replace(/\*/g, '[^/]*')
+    .replace(/\u0000/g, '.*')
+    .replace(/\?/g, '[^/]')
+  const expression = new RegExp(`^${source}$`)
+  return (path) => expression.test(path)
+}
+
+export const firstMatch = (rules, path) => (rules ?? []).find((rule) => [].concat(rule.match).some((pattern) => matcher(pattern)(path)))
+
+export const anyMatch = (patterns, path) => (patterns ?? []).some((pattern) => matcher(pattern)(path))

package/lib/title.js

@@ -0,0 +1,14 @@
+import { fill, firstMatch, length, pick } from './text.js'
+
+export function resolveTitle({ label, seoTitle, path, lang, locale, siteName, options }) {
+  const rule = seoTitle ? undefined : firstMatch(options.templates, path)
+  const template = rule ? pick(rule.template, lang, locale) : undefined
+  const base = seoTitle ?? (template ? fill(template, { title: label, site: siteName }) : label)
+  const source = seoTitle ? 'frontmatter' : template ? 'template' : 'label'
+  const branded = `${base} ${options.delimiter} ${siteName}`
+  const mentionsSite = base.toLowerCase().includes(String(siteName).toLowerCase())
+  const withBrand =
+    options.brand === 'always' ||
+    (options.brand === 'auto' && !mentionsSite && length(branded) <= options.max)
+  return { base, full: withBrand ? branded : base, source, branded: withBrand }
+}

package/middleware.js

@@ -0,0 +1,53 @@
+import { defineRouteMiddleware } from '@astrojs/starlight/route-data'
+import options from 'virtual:starlight-seo/options'
+import { graph as graphHook, page as pageHook } from 'virtual:starlight-seo/extend'
+import { applyHead, canonicalOf, graphOf, pushGraph, setCanonical } from './lib/head.js'
+import { resolvePage, retitle } from './lib/page.js'
+import { anyMatch } from './lib/text.js'
+
+export const onRequest = defineRouteMiddleware(async (context, next) => {
+  await next()
+
+  const route = context.locals.starlightRoute
+  const data = route?.entry?.data
+  if (!data) return
+
+  const pathname = context.url.pathname
+  const locale = route.locale
+  const prefix = locale ? `/${locale}` : ''
+  const path = prefix && pathname.startsWith(`${prefix}/`) ? pathname.slice(prefix.length) : pathname
+  if (anyMatch(options.exclude, path)) return
+
+  if (route.isFallback && options.fallback === 'canonical') {
+    setCanonical(route.head, new URL(`${options.defaultPrefix}${path}`, `${options.origin}/`).href)
+  }
+
+  const page = resolvePage(options, {
+    pathname,
+    path,
+    lang: route.lang,
+    locale,
+    homeHref: `${prefix}/`,
+    isHome: path === '/',
+    canonical: canonicalOf(route.head) ?? new URL(pathname, `${options.origin}/`).href,
+    label: data.title,
+    description: data.description,
+    template: data.template,
+    lastUpdated: route.lastUpdated,
+    siteTitle: route.siteTitle,
+    sidebar: route.sidebar,
+    seo: data.seo,
+  })
+
+  if (typeof pageHook === 'function') {
+    const patch = (await pageHook(page, context)) ?? {}
+    Object.assign(page, patch)
+    if (patch.title !== undefined && patch.headTitle === undefined) Object.assign(page, retitle(options, page, patch.title))
+  }
+
+  applyHead(route.head, page, options)
+
+  let nodes = graphOf(page, options)
+  if (typeof graphHook === 'function') nodes = (await graphHook(nodes, page, context)) ?? nodes
+  pushGraph(route.head, nodes)
+})

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "starlight-seo",
+  "version": "0.2.0",
+  "description": "Starlight plugin for search-ready titles, connected JSON-LD, complete Open Graph tags and a build-time SEO audit.",
+  "license": "MIT",
+  "author": "kaktak.net",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kaktaknet/starlight-seo.git"
+  },
+  "homepage": "https://github.com/kaktaknet/starlight-seo#readme",
+  "bugs": "https://github.com/kaktaknet/starlight-seo/issues",
+  "keywords": [
+    "starlight",
+    "starlight-plugin",
+    "astro",
+    "withastro",
+    "seo",
+    "json-ld",
+    "schema.org",
+    "open-graph",
+    "structured-data"
+  ],
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    },
+    "./schema": {
+      "types": "./schema.d.ts",
+      "import": "./schema.js"
+    },
+    "./middleware": "./middleware.js",
+    "./audit": {
+      "types": "./lib/audit.d.ts",
+      "import": "./lib/audit.js"
+    },
+    "./core": {
+      "types": "./core.d.ts",
+      "import": "./core.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "core.js",
+    "core.d.ts",
+    "schema.js",
+    "schema.d.ts",
+    "middleware.js",
+    "virtual.d.ts",
+    "lib",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "node --test tests/*.test.js",
+    "test:fixture": "node tests/fixture.mjs"
+  },
+  "peerDependencies": {
+    "@astrojs/starlight": ">=0.32.0",
+    "astro": ">=5.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@astrojs/starlight": "0.42.5",
+    "astro": "7.3.5",
+    "starlight-seo": "link:."
+  },
+  "packageManager": "pnpm@12.6.0",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/schema.d.ts

@@ -0,0 +1,4 @@
+import type { z } from 'astro/zod'
+
+export declare const seoFields: () => z.ZodObject<any>
+export declare const seoSchema: () => z.ZodObject<{ seo: z.ZodOptional<z.ZodObject<any>> }>

package/schema.js

@@ -0,0 +1,31 @@
+import { z } from 'astro/zod'
+
+const thing = z.union([
+  z.string(),
+  z.object({
+    type: z.string().optional(),
+    name: z.string(),
+    description: z.string().optional(),
+    url: z.string().optional(),
+    sameAs: z.union([z.string(), z.array(z.string())]).optional(),
+  }),
+])
+
+export const seoFields = () =>
+  z
+    .object({
+      title: z.string().min(1).optional(),
+      description: z.string().min(1).optional(),
+      type: z.string().optional(),
+      image: z.string().optional(),
+      imageAlt: z.string().optional(),
+      noindex: z.boolean().optional(),
+      published: z.coerce.date().optional(),
+      modified: z.coerce.date().optional(),
+      section: z.string().optional(),
+      keywords: z.array(z.string()).optional(),
+      about: z.union([thing, z.array(thing)]).optional(),
+    })
+    .strict()
+
+export const seoSchema = () => z.object({ seo: seoFields().optional() })

package/virtual.d.ts

@@ -0,0 +1,9 @@
+declare module 'virtual:starlight-seo/options' {
+  const options: Record<string, any>
+  export default options
+}
+
+declare module 'virtual:starlight-seo/extend' {
+  export const page: import('./index.js').SeoPageHook | undefined
+  export const graph: import('./index.js').SeoGraphHook | undefined
+}