add structured data and fix up styles

Author: jsneedles

scripts/prepare-og.mjs

@@ -15,6 +15,8 @@ async function walk(dir) {
     const file = `${dir}/${entry.name}`;
     if (entry.isDirectory()) { await walk(file); continue; }
     if (!/\.mdx?$/.test(file)) continue;
+    // Starlight's error page is not an article or an OG/Markdown export.
+    if (file === 'src/content/docs/404.mdx') continue;
     const { data } = matter(await fs.readFile(file, 'utf8'));
     if (typeof data.slug !== 'string') throw new Error(`Explicit slug required: ${file}`);
     const route = data.slug ? `/${data.slug}/` : '/';

src/components/Breadcrumbs.astro

@@ -1,27 +1,8 @@
 ---
-import navigation from '../navigation.mjs';
+import { breadcrumbs } from '../lib/breadcrumbs.mjs';
 const { entry } = Astro.locals.starlightRoute;
 const route = Astro.url.pathname;
-type Crumb = { label: string; link: string };
-type NavItem = { label: string; link?: string; items?: NavItem[] };
-const candidates: Crumb[][] = [];
-function findPaths(items: NavItem[], parents: Crumb[] = []) {
-  for (const item of items) {
-    if (item.link === route) candidates.push(parents);
-    if (item.items) {
-      const overview = item.items.find(child => child.label === 'Overview' && child.link);
-      const ancestors = overview?.link ? [...parents, { label: item.label, link: overview.link }] : parents;
-      findPaths(item.items, ancestors);
-    }
-  }
-}
-findPaths(navigation);
-// A page can appear in more than one sidebar group. Prefer its URL hierarchy.
-const score = (path: Crumb[]) => path.filter(crumb => route.startsWith(crumb.link)).length;
-const parents = entry.data.changelog
-  ? [{ label: 'Changelog', link: '/changelog/' }]
-  : (candidates.sort((a, b) => score(b) - score(a))[0] || []);
-const crumbs = [{ label: 'Docs', link: '/' }, ...parents.filter(crumb => crumb.link !== route && crumb.link !== '/')];
+const crumbs = breadcrumbs(route, entry.data.page_title ?? entry.data.title, Boolean(entry.data.changelog)).slice(0, -1);
 ---
 {route !== '/' && <nav class="breadcrumbs" aria-label="Breadcrumb">
   <ol>

src/components/Head.astro

@@ -1,7 +1,17 @@
 ---
 import pages from '../generated/pages.json';
+import { structuredData, serializeStructuredData } from '../lib/structured-data.mjs';
 const page = pages.find(page => page.route === Astro.url.pathname);
 const { head, entry } = Astro.locals.starlightRoute;
+const jsonLd = page && structuredData({
+  origin: Astro.site?.href ?? Astro.url.origin,
+  route: page.route,
+  title: entry.data.page_title ?? entry.data.title,
+  description: entry.data.description,
+  image: page.og.image,
+  datePublished: entry.data.changelog?.date,
+  overview: page.route === '/' || page.route === '/changelog/' || /\/index\.mdx?$/.test(page.file),
+});
 const siteTitle = 'HTML/CSS to Image API Docs';
 const brandedTitle = (title: string) => title === siteTitle || title.endsWith(` | ${siteTitle}`)
   ? title : `${title} | ${siteTitle}`;
@@ -13,6 +23,8 @@ const tags = head.filter(tag => tag.tag !== 'title' &&
     : tag);
 ---
 <title>{brandedTitle(entry.data.title)}</title>
+{jsonLd && <script type="application/ld+json" set:html={serializeStructuredData(jsonLd)} />}
+{entry.data.changelog && <meta property="article:published_time" content={entry.data.changelog.date} />}
 <meta data-pagefind-filter="kind[content]" content={entry.data.changelog ? 'changelog' : 'docs'} />
 <link rel="preconnect" href="https://fonts.googleapis.com" />
 <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
@@ -24,6 +36,8 @@ const tags = head.filter(tag => tag.tag !== 'title' &&
 {page?.og.image && <>
   <meta property="og:image" content={page.og.image} />
   <meta name="twitter:image" content={page.og.image} />
+  <meta property="og:image:alt" content={page.og.title} />
+  <meta name="twitter:image:alt" content={page.og.title} />
   <meta property="og:image:width" content="1200" />
   <meta property="og:image:height" content="630" />
 </>}

src/components/PageTitle.astro

@@ -10,7 +10,7 @@ const markdownPath = route === '/' ? '/index.md' : `${route.replace(/\/$/, '')}.
 <Breadcrumbs />
 <div class="page-heading">
   {entry.data.page_title ? <h1 id="_top">{pageTitle}</h1> : <DefaultPageTitle />}
-  <PageActions markdownPath={markdownPath} title={pageTitle} />
+  {entry.id !== '404' && <PageActions markdownPath={markdownPath} title={pageTitle} />}
 </div>
 {entry.data.changelog && <p class="published"><time data-changelog-date datetime={entry.data.changelog.date}>{new Date(`${entry.data.changelog.date}T00:00:00Z`).toLocaleDateString('en-US', { month: 'long', day: 'numeric', year: 'numeric', timeZone: 'UTC' })}</time></p>}
 <style>

src/content.config.ts

@@ -1,6 +1,6 @@
 import { defineCollection, z } from 'astro:content';
-import { docsLoader } from '@astrojs/starlight/loaders';
-import { docsSchema } from '@astrojs/starlight/schema';
+import { docsLoader, i18nLoader } from '@astrojs/starlight/loaders';
+import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';
 
 // Native Markdown/MDX only. Jekyll sources are never loaded by Astro.
 export const collections = { docs: defineCollection({
@@ -16,4 +16,4 @@ export const collections = { docs: defineCollection({
       anchor: z.string().regex(/^[a-z0-9_-]+$/),
     }).optional(),
   }) }),
-}) };
+}), i18n: defineCollection({ loader: i18nLoader(), schema: i18nSchema() }) };

src/content/docs/404.mdx

@@ -0,0 +1,19 @@
+---
+title: Page not found
+description: Find your way back to the HTML/CSS to Image documentation.
+# Starlight reads this entry directly for /404.html; don't also publish /404/.
+draft: true
+editUrl: false
+tableOfContents: false
+sidebar:
+  hidden: true
+head:
+  - tag: meta
+    attrs:
+      name: robots
+      content: noindex, nofollow
+---
+
+We couldn't find that page. It may have moved, or the link may be incorrect.
+
+Try searching the docs, or head back to the [documentation homepage](/).

src/content/i18n/en.json

@@ -0,0 +1,3 @@
+{
+  "search.label": "Search docs"
+}

src/lib/breadcrumbs.mjs

@@ -0,0 +1,20 @@
+import navigation from '../navigation.mjs';
+
+export function breadcrumbs(route, title, isChangelog = false) {
+  if (route === '/') return [];
+  const candidates = [];
+  function findPaths(items, parents = []) {
+    for (const item of items) {
+      if (item.link === route) candidates.push(parents);
+      if (item.items) {
+        const overview = item.items.find(child => child.label === 'Overview' && child.link);
+        findPaths(item.items, overview?.link ? [...parents, { label: item.label, link: overview.link }] : parents);
+      }
+    }
+  }
+  findPaths(navigation);
+  const score = path => path.filter(crumb => route.startsWith(crumb.link)).length;
+  const parents = isChangelog ? [{ label: 'Changelog', link: '/changelog/' }]
+    : (candidates.sort((a, b) => score(b) - score(a))[0] || []);
+  return [{ label: 'Docs', link: '/' }, ...parents.filter(crumb => crumb.link !== route && crumb.link !== '/'), { label: title, link: route }];
+}

src/lib/structured-data.mjs

@@ -0,0 +1,41 @@
+import { breadcrumbs } from './breadcrumbs.mjs';
+
+export function structuredData({ origin, route, title, description, image, datePublished, overview = false }) {
+  const url = new URL(route, origin).href;
+  const home = new URL('/', origin).href;
+  const publisher = {
+    '@type': 'Organization', '@id': 'https://htmlcsstoimage.com/#organization',
+    name: 'HTML/CSS to Image API', alternateName: 'HCTI', url: 'https://htmlcsstoimage.com/',
+    description: 'Capture website screenshots, render HTML/CSS, or create templated graphics. Use MCP with AI, no-code automation, or the REST API. No browsers needed.',
+    logo: { '@type': 'ImageObject', url: 'https://htmlcsstoimage.com/images/logo_with_black_bg.png', width: 1024, height: 1024 },
+    sameAs: ['https://twitter.com/htmlcsstoimage', 'https://github.com/htmlcsstoimage', 'https://www.linkedin.com/company/html-css-to-image/'],
+    contactPoint: { '@type': 'ContactPoint', contactType: 'customer support', email: 'support@htmlcsstoimage.com' },
+  };
+  const website = {
+    '@type': 'WebSite', '@id': `${home}#website`, url: home,
+    name: 'HTML/CSS to Image API Docs', inLanguage: 'en', publisher: { '@id': publisher['@id'] },
+  };
+  const crumbs = breadcrumbs(route, title, Boolean(datePublished));
+  const breadcrumb = crumbs.length ? {
+    '@type': 'BreadcrumbList', '@id': `${url}#breadcrumbs`,
+    itemListElement: crumbs.map((crumb, index) => ({
+      '@type': 'ListItem', position: index + 1, name: crumb.label, item: new URL(crumb.link, origin).href,
+    })),
+  } : undefined;
+  const page = {
+    '@type': overview ? 'CollectionPage' : 'WebPage', '@id': `${url}#webpage`, url,
+    name: title, description, inLanguage: 'en', isPartOf: { '@id': website['@id'] },
+    ...(breadcrumb ? { breadcrumb: { '@id': breadcrumb['@id'] } } : {}),
+    ...(image ? { primaryImageOfPage: { '@type': 'ImageObject', url: image, width: 1200, height: 630 } } : {}),
+  };
+  const article = overview ? undefined : {
+    '@type': datePublished ? 'BlogPosting' : 'TechArticle', '@id': `${url}#article`, url,
+    headline: title, description, inLanguage: 'en', mainEntityOfPage: { '@id': page['@id'] },
+    publisher: { '@id': publisher['@id'] },
+    ...(image ? { image } : {}), ...(datePublished ? { datePublished } : {}),
+  };
+  return { '@context': 'https://schema.org', '@graph': [publisher, website, page, breadcrumb, article].filter(Boolean) };
+}
+
+// JSON-LD is embedded in a script element, so content must not close that element.
+export const serializeStructuredData = data => JSON.stringify(data).replace(/</g, '\\u003c');

src/styles/global.css

@@ -11,6 +11,7 @@
 :root[data-theme='light'] { --sl-color-accent-low:#e4f6eb; --sl-color-accent:#007a4e; --sl-color-accent-high:#075836; --sl-color-white:#171b22; --sl-color-gray-1:#28332d; --sl-color-gray-2:#435148; --sl-color-gray-3:#617067; --sl-color-gray-4:#87988d; --sl-color-gray-5:#dce5dd; --sl-color-gray-6:#f7f9f6; --sl-color-bg:#ffffff; --sl-color-bg-nav:#ffffff; --sl-color-bg-sidebar:#f7f9f6; --sl-color-hairline:#e3e9e3; }
 html { scroll-padding-top:6rem; }
 h1,h2,h3 { letter-spacing:-.025em; }
+strong, b { font-weight:600; }
 main > .content-panel { padding-block:1rem; }
 /* Image zoom inserts a hidden element before the article. */
 .sl-container > .sl-markdown-content { margin-top:0; }