Add API website metadata and branding

Author: SandroMaglione

api-reference-site.config.json

@@ -2,6 +2,12 @@
   "input": ".data/api-reference/v4",
   "output": ".data/api-reference-site/v4",
   "basePath": "/",
+  "origin": "https://effect-machine.typeonce.dev",
   "title": "Effect Machine",
-  "description": "API reference for Effect Machine"
+  "description": "Schema-first state machines and statecharts for Effect",
+  "themeColor": {
+    "light": "#fbfbfd",
+    "dark": "#111115"
+  },
+  "socialImage": "social-card.png"
 }

scripts/api-reference-site/api-reference-site.test.mjs

@@ -4,7 +4,13 @@ import {
   highlightCode,
   moduleRoute,
   normalizeBasePath,
+  normalizeOrigin,
+  renderIndexPage,
+  renderLayout,
   renderMarkdown,
+  renderRobots,
+  renderSitemap,
+  siteManifest,
   uniqueDeclarationIds
 } from "./generate.mjs"
 
@@ -55,3 +61,59 @@ test("normalizes root, project, and custom-domain base paths", () => {
   assert.throws(() => normalizeBasePath("effect-machine"), /start with a slash/)
   assert.throws(() => normalizeBasePath("/../effect-machine"), /Invalid/)
 })
+
+const site = {
+  basePath: "/docs/",
+  description: "Schema-first state machines",
+  modules: [{
+    api: { declarationCount: 12, description: "State machine APIs" },
+    export: "./Machine",
+    label: "Machine",
+    route: "Machine"
+  }],
+  navigation: [],
+  origin: "https://docs.example.com",
+  package: {
+    name: "@typeonce/effect-machine",
+    description: "Schema-first state machines",
+    sourceUrl: "https://github.com/typeonce-dev/effect-machine",
+    version: "0.4.0"
+  },
+  socialImage: "social-card.png",
+  themeColor: { light: "#fbfbfd", dark: "#111115" },
+  title: "Effect Machine"
+}
+
+test("renders canonical and social metadata without exposing the internal channel", () => {
+  const html = renderLayout(site, {
+    content: '<section class="reference-hero"><div class="eyebrow">API reference</div></section>',
+    currentRoute: "Machine",
+    pageKind: "module",
+    title: "Machine · Effect Machine"
+  })
+  assert.match(html, /rel="canonical" href="https:\/\/docs\.example\.com\/docs\/Machine\/"/)
+  assert.match(html, /property="og:image" content="https:\/\/docs\.example\.com\/docs\/social-card\.png"/)
+  assert.match(html, /name="twitter:card" content="summary_large_image"/)
+  assert.match(html, /rel="manifest" href="\/docs\/site\.webmanifest"/)
+  assert.doesNotMatch(html, /v4 API reference/)
+})
+
+test("keeps the internal Effect channel out of the homepage label", () => {
+  const html = renderIndexPage({ ...site, channel: "v4" })
+  assert.match(html, /<div class="eyebrow">API reference<\/div>/)
+  assert.doesNotMatch(html, /v4 API reference/)
+})
+
+test("generates manifest, robots, and sitemap URLs from the deployment base", () => {
+  const manifest = siteManifest(site)
+  assert.equal(manifest.start_url, "/docs/")
+  assert.equal(manifest.icons[2].purpose, "maskable")
+  assert.match(renderRobots(site), /Sitemap: https:\/\/docs\.example\.com\/docs\/sitemap\.xml/)
+  assert.match(renderSitemap(site), /<loc>https:\/\/docs\.example\.com\/docs\/Machine\/<\/loc>/)
+})
+
+test("accepts only pathless HTTPS production origins", () => {
+  assert.equal(normalizeOrigin("https://docs.example.com"), "https://docs.example.com")
+  assert.throws(() => normalizeOrigin("http://docs.example.com"), /HTTPS origin/)
+  assert.throws(() => normalizeOrigin("https://docs.example.com/api"), /without a path/)
+})

scripts/api-reference-site/artwork/app-icon.svg

@@ -151,6 +151,23 @@ button {
   gap: 0.65rem;
 }
 
+.brand-mark {
+  display: block;
+  filter: invert(1);
+  height: 1.55rem;
+  width: 1.55rem;
+}
+
+:root[data-theme="dark"] .brand-mark {
+  filter: none;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root[data-theme="auto"] .brand-mark {
+    filter: none;
+  }
+}
+
 .brand-name {
   font-size: 0.95rem;
   font-weight: 700;

scripts/api-reference-site/artwork/social-card.svg

@@ -1,4 +1,5 @@
 import {
+  cpSync,
   copyFileSync,
   mkdirSync,
   mkdtempSync,
@@ -101,9 +102,15 @@ const writeSite = (outputDirectory, site) => {
   for (const asset of ["styles.css", "client.js"]) {
     copyFileSync(join(scriptDirectory, "assets", asset), join(assetDirectory, asset))
   }
+  for (const entry of readdirSync(join(scriptDirectory, "public"))) {
+    cpSync(join(scriptDirectory, "public", entry), join(outputDirectory, entry), { recursive: true })
+  }
+  writeJson(join(outputDirectory, "site.webmanifest"), siteManifest(site))
+  writeFileSync(join(outputDirectory, "robots.txt"), renderRobots(site))
+  writeFileSync(join(outputDirectory, "sitemap.xml"), renderSitemap(site))
 }
 
-const renderIndexPage = (site) => {
+export const renderIndexPage = (site) => {
   const moduleCards = site.modules.map((module) => `
     <a class="module-card" href="${siteUrl(site, module.route)}">
       <span class="module-card__path">${escapeHtml(displayExport(module.export))}</span>
@@ -113,7 +120,7 @@ const renderIndexPage = (site) => {
     </a>`).join("")
   const content = `
     <section class="reference-hero" data-pagefind-meta="type:overview">
-      <div class="eyebrow">${escapeHtml(site.channel)} API reference</div>
+      <div class="eyebrow">API reference</div>
       <h1>${escapeHtml(site.package.name)}</h1>
       <p>${escapeHtml(site.package.description)}</p>
       <div class="hero-meta">
@@ -233,15 +240,39 @@ const renderDeclaration = (declaration, id) => {
     </article>`
 }
 
-const renderLayout = (site, { content, currentRoute, description, pageKind, title, toc = "" }) => `<!doctype html>
+export const renderLayout = (site, { content, currentRoute, description, pageKind, title, toc = "" }) => {
+  const pageDescription = description ?? site.description
+  const canonical = canonicalUrl(site, currentRoute)
+  const socialImage = absoluteSiteUrl(site, site.socialImage)
+  return `<!doctype html>
 <html lang="en">
   <head>
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1">
-    <meta name="description" content="${escapeAttribute(description ?? site.description)}">
+    <meta name="description" content="${escapeAttribute(pageDescription)}">
+    <meta name="theme-color" media="(prefers-color-scheme: light)" content="${escapeAttribute(site.themeColor.light)}">
+    <meta name="theme-color" media="(prefers-color-scheme: dark)" content="${escapeAttribute(site.themeColor.dark)}">
     <meta name="api-reference-base" content="${escapeAttribute(site.basePath)}">
     <meta name="generator" content="effect-machine-api-reference-site">
+    <meta property="og:type" content="website">
+    <meta property="og:site_name" content="${escapeAttribute(site.title)}">
+    <meta property="og:title" content="${escapeAttribute(title)}">
+    <meta property="og:description" content="${escapeAttribute(pageDescription)}">
+    <meta property="og:url" content="${escapeAttribute(canonical)}">
+    <meta property="og:image" content="${escapeAttribute(socialImage)}">
+    <meta property="og:image:width" content="1200">
+    <meta property="og:image:height" content="630">
+    <meta property="og:image:alt" content="${escapeAttribute(`${site.package.name} API reference`)}">
+    <meta name="twitter:card" content="summary_large_image">
+    <meta name="twitter:title" content="${escapeAttribute(title)}">
+    <meta name="twitter:description" content="${escapeAttribute(pageDescription)}">
+    <meta name="twitter:image" content="${escapeAttribute(socialImage)}">
     <title>${escapeHtml(title)}</title>
+    <link rel="canonical" href="${escapeAttribute(canonical)}">
+    <link rel="icon" href="${siteUrl(site, "favicon.svg")}" type="image/svg+xml">
+    <link rel="icon" href="${siteUrl(site, "favicon.ico")}" sizes="any">
+    <link rel="apple-touch-icon" href="${siteUrl(site, "apple-touch-icon.png")}">
+    <link rel="manifest" href="${siteUrl(site, "site.webmanifest")}">
     <script>document.documentElement.dataset.theme=localStorage.getItem("api-theme")||"auto"</script>
     <link rel="stylesheet" href="${siteUrl(site, "assets/styles.css")}">
     <script type="module" src="${siteUrl(site, "assets/client.js")}"></script>
@@ -261,13 +292,15 @@ const renderLayout = (site, { content, currentRoute, description, pageKind, titl
   </body>
 </html>
 `
+}
 
 const renderHeader = (site) => `
   <a class="skip-link" href="#main-content">Skip to content</a>
   <header class="site-header" data-pagefind-ignore>
     <div class="site-header__brand">
       <button class="icon-button mobile-navigation-button" type="button" aria-label="Open navigation" aria-controls="module-navigation" aria-expanded="false">Menu</button>
       <a href="${siteUrl(site, "")}" aria-label="${escapeAttribute(site.package.name)} API reference home">
+        <img class="brand-mark" src="${siteUrl(site, "logo.svg")}" alt="" width="28" height="28">
         <span class="brand-name">${escapeHtml(site.package.name)}</span>
       </a>
       <span class="version">v${escapeHtml(site.package.version.replace(/^v/, ""))}</span>
@@ -433,6 +466,39 @@ export const uniqueDeclarationIds = (groups) => {
 }
 
 const siteUrl = (site, path) => `${site.basePath}${path}`.replace(/\/{2,}/g, "/")
+const absoluteSiteUrl = (site, path) => new URL(siteUrl(site, path), `${site.origin}/`).href
+const canonicalUrl = (site, route) => absoluteSiteUrl(site, route === "" ? "" : `${route}/`)
+
+export const siteManifest = (site) => ({
+  name: `${site.package.name} API reference`,
+  short_name: "effect-machine",
+  description: site.description,
+  id: site.basePath,
+  start_url: site.basePath,
+  scope: site.basePath,
+  display: "standalone",
+  background_color: site.themeColor.light,
+  theme_color: site.themeColor.light,
+  icons: [
+    { src: siteUrl(site, "icon-192.png"), sizes: "192x192", type: "image/png" },
+    { src: siteUrl(site, "icon-512.png"), sizes: "512x512", type: "image/png" },
+    { src: siteUrl(site, "icon-maskable-512.png"), sizes: "512x512", type: "image/png", purpose: "maskable" }
+  ]
+})
+
+export const renderRobots = (site) => `User-agent: *
+Allow: ${site.basePath}
+
+Sitemap: ${absoluteSiteUrl(site, "sitemap.xml")}
+`
+
+export const renderSitemap = (site) => `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${["", ...site.modules.map((module) => `${module.route}/`)]
+    .map((route) => `  <url><loc>${escapeXml(absoluteSiteUrl(site, route))}</loc></url>`)
+    .join("\n")}
+</urlset>
+`
 const displayExport = (value) => value === "." ? "root" : value.replace(/^\.\//, "")
 const titleCase = (value) => value.replace(/(^|\s)(\p{L})/gu, (_, space, letter) => `${space}${letter.toUpperCase()}`)
 const slugify = (value) => value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "api"
@@ -447,12 +513,41 @@ const readConfig = (path) => {
   if (typeof config.title !== "string" || typeof config.description !== "string") {
     throw new Error("API reference site title and description must be configured")
   }
+  if (
+    typeof config.origin !== "string" ||
+    typeof config.socialImage !== "string" ||
+    typeof config.themeColor?.light !== "string" ||
+    typeof config.themeColor?.dark !== "string"
+  ) {
+    throw new Error("API reference site origin, social image, and theme colors must be configured")
+  }
   return {
     ...config,
+    origin: normalizeOrigin(config.origin),
     basePath: normalizeBasePath(process.env.API_REFERENCE_BASE_PATH ?? config.basePath)
   }
 }
 
+export const normalizeOrigin = (value) => {
+  let url
+  try {
+    url = new URL(value)
+  } catch {
+    throw new Error("API reference site origin must be an absolute URL")
+  }
+  if (
+    url.protocol !== "https:" ||
+    url.username !== "" ||
+    url.password !== "" ||
+    url.pathname !== "/" ||
+    url.search !== "" ||
+    url.hash !== ""
+  ) {
+    throw new Error("API reference site origin must be an HTTPS origin without a path")
+  }
+  return url.origin
+}
+
 export const normalizeBasePath = (value) => {
   if (typeof value !== "string" || (value.length > 0 && !value.startsWith("/"))) {
     throw new Error("API reference site basePath must be empty or start with a slash")
@@ -489,6 +584,17 @@ const validateSite = (outputDirectory, site) => {
     "index.html",
     "assets/styles.css",
     "assets/client.js",
+    "apple-touch-icon.png",
+    "favicon.ico",
+    "favicon.svg",
+    "icon-192.png",
+    "icon-512.png",
+    "icon-maskable-512.png",
+    "logo.svg",
+    "robots.txt",
+    "site.webmanifest",
+    "sitemap.xml",
+    site.socialImage,
     ...site.modules.map((module) => join(module.route, "index.html"))
   ]) {
     if (!isFile(safeResolve(outputDirectory, path))) throw new Error(`Missing generated site file: ${path}`)
@@ -510,6 +616,7 @@ const writePage = (path, html) => {
   writeFileSync(path, html)
 }
 const readJson = (path) => JSON.parse(readFileSync(path, "utf8"))
+const writeJson = (path, value) => writeFileSync(path, `${JSON.stringify(value, undefined, 2)}\n`)
 const isFile = (path) => statSync(path, { throwIfNoEntry: false })?.isFile() === true
 const escapeHtml = (value) => String(value)
   .replaceAll("&", "&amp;")
@@ -518,6 +625,7 @@ const escapeHtml = (value) => String(value)
   .replaceAll('"', "&quot;")
   .replaceAll("'", "&#39;")
 const escapeAttribute = escapeHtml
+const escapeXml = escapeHtml
 
 const isMain = process.argv[1] !== undefined && resolve(process.argv[1]) === fileURLToPath(import.meta.url)
 if (isMain) {