feat(website): /features index page + multilingual sitemap (hreflang + lastmod + sitemap-index + robots.txt) (#202)

SEO improvement so crawlers understand the site's information tree
(features / docs / blog) and how each section's content branches into
the three shipped locales (en / es / zh-CN).

Changes:

- **New /features index page** (website/src/pages/features/{index.tsx,
  index.module.css}). Renders FeatureGrid wrapped in a thin header
  (eyebrow + H1 + intro) so the nine /features/<slug> pages now have
  a parent aggregator, matching the pattern /blog and /docs already
  have. i18n-ready via translate() with localized OG metadata.
- **FeaturesLayout sidebar gains an "Overview" link** back to the new
  /features index, with active-state detection that doesn't false-match
  on /features/<slug> subpaths.
- **Sitemap plugin enriched** via createSitemapItems: every URL in each
  per-locale sitemap now carries `xhtml:link rel="alternate"
  hreflang="..."` entries for all three locales + an x-default — Google
  uses these to cluster the per-locale URLs as translations rather than
  duplicates. 80 URLs × 4 alternates × 3 sitemaps = 960 hreflang
  annotations emitted.
- **lastmod populated** for docs and blog posts via showLastUpdateTime
  on both content plugins + experimental_vcs: 'git-eager' on the
  future config so git history reads are eager-cached at build start.
  Aggregator pages (blog tag indexes, archive, author pages) correctly
  have no lastmod — they don't map to a single source file.
- **sitemap-index.xml** (static, website/static/) aggregates the three
  per-locale sitemaps so crawlers discover all locales from one entry
  point.
- **robots.txt** (static, website/static/) declares `Sitemap:` pointing
  at sitemap-index.xml. Without this, the multi-sitemap setup is not
  auto-discoverable.
- **i18n keys added** for the /features page (eyebrow, H1, intro, OG
  title, OG description, sidebar Overview label) in es + zh-CN code.json.

Build verified locally: 80 URLs × 3 locales, hreflang on every URL,
lastmod on 23 EN / 16 ES / 16 zh-CN URLs (all content; aggregators
correctly skipped).

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: montfort

website/docusaurus.config.ts

@@ -1,5 +1,5 @@
 import {themes as prismThemes} from 'prism-react-renderer';
-import type {Config} from '@docusaurus/types';
+import type {Config, I18n} from '@docusaurus/types';
 import type * as Preset from '@docusaurus/preset-classic';
 
 const GITHUB_REPO = 'https://github.com/StrangeDaysTech/straymark';
@@ -126,6 +126,12 @@ const config: Config = {
 
   future: {
     v4: true,
+    // Required for sitemap <lastmod> to be populated from git: the sitemap
+    // plugin reads each route's last update timestamp via this VCS layer.
+    // 'git-eager' pre-reads the whole repo once at build start, then answers
+    // per-file queries in memory — faster than 'git-ad-hoc' for a build that
+    // covers ~80 routes × 3 locales. See VcsPreset in @docusaurus/types.
+    experimental_vcs: 'git-eager',
   },
 
   url: 'https://straymark.dev',
@@ -169,6 +175,9 @@ const config: Config = {
           sidebarPath: './sidebars.ts',
           include: ['intro.md', 'adopters/**', 'contributors/**'],
           exclude: ['**/i18n/**', '**/proposals/**', '**/decisions/**'],
+          // Populates each route's metadata.lastUpdatedAt from git so the
+          // sitemap plugin can emit <lastmod> per doc URL.
+          showLastUpdateTime: true,
         },
         blog: {
           path: 'blog',
@@ -178,6 +187,10 @@ const config: Config = {
           blogSidebarCount: 'ALL',
           blogSidebarTitle: 'All posts',
           showReadingTime: true,
+          // Populates metadata.lastUpdatedAt from git for every post so the
+          // sitemap plugin can emit <lastmod> per post URL. Same lever the
+          // docs plugin uses above.
+          showLastUpdateTime: true,
           feedOptions: {
             type: ['rss', 'atom'],
             title: 'StrayMark Blog',
@@ -194,6 +207,79 @@ const config: Config = {
         theme: {
           customCss: './src/css/custom.css',
         },
+        // Sitemap config. The classic preset bundles @docusaurus/plugin-sitemap;
+        // by default it emits one sitemap.xml per locale build (en at root,
+        // /es/sitemap.xml, /zh-CN/sitemap.xml) with no lastmod and no
+        // hreflang alternates — meaning search engines treat each locale's
+        // copy of the same content as unrelated documents.
+        //
+        // We enrich the default emitter via createSitemapItems:
+        //   - `lastmod: 'date'` makes the plugin attach <lastmod> per URL,
+        //     pulled from git for files with a known sourceFilePath.
+        //   - createSitemapItems wraps defaultCreateSitemapItems and adds an
+        //     `xhtml:link rel="alternate" hreflang="..."` entry per item for
+        //     every locale we ship, plus an x-default pointing at the EN
+        //     canonical. Google uses this to cluster the per-locale URLs as
+        //     translations of the same page rather than as duplicates.
+        //
+        // The static counterparts (/sitemap-index.xml that aggregates the
+        // three per-locale sitemaps, and /robots.txt that points crawlers at
+        // the index) live under website/static/ — Docusaurus copies them
+        // verbatim to the build root.
+        sitemap: {
+          lastmod: 'date',
+          createSitemapItems: async (params) => {
+            const {defaultCreateSitemapItems, ...rest} = params;
+            const items = await defaultCreateSitemapItems(rest);
+            const {siteConfig} = params;
+            const siteUrl = siteConfig.url;
+            // Docusaurus types `siteConfig.i18n` as I18nConfig (the input
+            // shape), but at build time the loader hydrates it into the full
+            // I18n shape, which carries `currentLocale`. Cast accordingly.
+            const i18n = siteConfig.i18n as unknown as I18n;
+            const {defaultLocale, locales, currentLocale} = i18n;
+
+            // URL prefix for the current build. Default locale has no prefix
+            // (URLs live at root); other locales are namespaced as
+            // /<locale>/... — matches Docusaurus's i18n routing.
+            const prefixFor = (locale: string): string =>
+              locale === defaultLocale ? '' : `/${locale}`;
+            const currentPrefix = prefixFor(currentLocale);
+
+            // Strip the current-locale prefix from a path to recover the
+            // locale-agnostic canonical path. Used to build the per-locale
+            // alternate URLs below.
+            const stripCurrentPrefix = (path: string): string => {
+              if (!currentPrefix) return path;
+              if (path === currentPrefix) return '/';
+              if (path.startsWith(`${currentPrefix}/`)) {
+                return path.slice(currentPrefix.length);
+              }
+              return path;
+            };
+
+            return items.map((item) => {
+              const path = item.url.replace(siteUrl, '');
+              const canonicalPath = stripCurrentPrefix(path) || '/';
+
+              // One hreflang entry per shipped locale + x-default. The lib
+              // (sitemap@7.x) emits each as
+              //   <xhtml:link rel="alternate" hreflang="<lang>" href="<url>" />
+              const links = [
+                ...locales.map((locale) => ({
+                  lang: locale,
+                  url: `${siteUrl}${prefixFor(locale)}${canonicalPath}`,
+                })),
+                {
+                  lang: 'x-default',
+                  url: `${siteUrl}${canonicalPath}`,
+                },
+              ];
+
+              return {...item, links};
+            });
+          },
+        },
         // Note: we do NOT use the preset's `gtag` option. The plugin injects
         // gtag.js + `gtag('config', ...)` BEFORE user-config headTags render,
         // which means `gtag('consent', 'default', 'denied')` arrives after

website/i18n/es/code.json

@@ -83,6 +83,30 @@
     "message": "Qué trae StrayMark",
     "description": "Title for the left sidebar shared across feature pages"
   },
+  "features.sidebar.overview": {
+    "message": "Resumen",
+    "description": "Sidebar link back to the /features index page from any feature subpage"
+  },
+  "features.index.eyebrow": {
+    "message": "Características",
+    "description": "Small eyebrow label above the /features H1"
+  },
+  "features.index.title": {
+    "message": "Qué trae StrayMark",
+    "description": "H1 of the /features index page"
+  },
+  "features.index.intro": {
+    "message": "Nueve capacidades que componen StrayMark — desde la disciplina cognitiva y la gobernanza repo-native hasta la auditoría multi-modelo y la observación emergente. Elegí la que mapea al problema que estás resolviendo; cada una enlaza a una página dedicada.",
+    "description": "Intro paragraph above the FeatureGrid on the /features index page"
+  },
+  "meta.features.title": {
+    "message": "Qué trae StrayMark — todas las características",
+    "description": "OG/Twitter title and browser tab for the /features index (the \" | StrayMark\" suffix is appended by Docusaurus automatically)"
+  },
+  "meta.features.description": {
+    "message": "Todas las capacidades de StrayMark en una página: charters, gobernanza, auditoría multi-modelo, detección de drift TDE, el CLI, skills para agentes y observación emergente.",
+    "description": "OG/Twitter description and meta description for the /features index"
+  },
   "features.discipline.title": {
     "message": "Disciplina cognitiva estructurada",
     "description": "Feature: structured cognitive discipline (title)"

website/i18n/zh-CN/code.json

@@ -11,6 +11,30 @@
     "message": "StrayMark 提供什么",
     "description": "Title for the left sidebar shared across feature pages"
   },
+  "features.sidebar.overview": {
+    "message": "概览",
+    "description": "Sidebar link back to the /features index page from any feature subpage"
+  },
+  "features.index.eyebrow": {
+    "message": "功能",
+    "description": "Small eyebrow label above the /features H1"
+  },
+  "features.index.title": {
+    "message": "StrayMark 提供什么",
+    "description": "H1 of the /features index page"
+  },
+  "features.index.intro": {
+    "message": "构成 StrayMark 的九项能力 —— 从认知纪律与原生于仓库的治理，到多模型审计与涌现观察。选择映射到你正在解决的问题的那一项；每一项都链接到一个专门的页面。",
+    "description": "Intro paragraph above the FeatureGrid on the /features index page"
+  },
+  "meta.features.title": {
+    "message": "StrayMark 提供什么 —— 全部功能一览",
+    "description": "OG/Twitter title and browser tab for the /features index (the \" | StrayMark\" suffix is appended by Docusaurus automatically)"
+  },
+  "meta.features.description": {
+    "message": "StrayMark 的所有能力汇集在一页：charters、治理、多模型审计、TDE 漂移检测、CLI、智能体 skills 与涌现观察。",
+    "description": "OG/Twitter description and meta description for the /features index"
+  },
   "features.discipline.title": {
     "message": "结构化的认知纪律",
     "description": "Feature: structured cognitive discipline (title)"

website/src/components/FeaturesLayout/index.tsx

@@ -63,19 +63,39 @@ function isActive(pathname: string, slug: string): boolean {
   );
 }
 
+function isOverviewActive(pathname: string): boolean {
+  // True only on the /features index — must NOT match /features/<slug>.
+  return /\/features\/?$/.test(pathname);
+}
+
 export default function FeaturesLayout({children}: Props): ReactNode {
   const {pathname} = useLocation();
   const sidebarTitle = translate({
     id: 'features.sidebar.title',
     message: "What's in the box",
     description: 'Title for the left sidebar shared across feature pages',
   });
+  const overviewLabel = translate({
+    id: 'features.sidebar.overview',
+    message: 'Overview',
+    description: 'Sidebar link back to the /features index page from any feature subpage',
+  });
+  const overviewActive = isOverviewActive(pathname);
 
   return (
     <div className={styles.container}>
       <aside className={styles.sidebar} aria-label={sidebarTitle}>
         <h3 className={styles.sidebarTitle}>{sidebarTitle}</h3>
         <ul className={styles.sidebarList}>
+          <li>
+            <Link
+              to="/features"
+              className={`${styles.sidebarLink} ${overviewActive ? styles.sidebarLinkActive : ''}`}
+              aria-current={overviewActive ? 'page' : undefined}
+            >
+              {overviewLabel}
+            </Link>
+          </li>
           {FEATURES.map((f) => {
             const active = isActive(pathname, f.slug);
             return (

website/src/pages/features/index.module.css

@@ -0,0 +1,33 @@
+.header {
+  padding: 4rem 0 2rem;
+  border-bottom: 1px solid var(--ifm-color-emphasis-200);
+}
+
+.headerInner {
+  max-width: 880px;
+  margin: 0 auto;
+  padding: 0 1.5rem;
+}
+
+.eyebrow {
+  margin: 0 0 0.5rem;
+  font-size: 0.875rem;
+  font-weight: 600;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--ifm-color-primary);
+}
+
+.title {
+  margin: 0 0 1rem;
+  font-size: clamp(2rem, 4vw + 1rem, 3rem);
+  font-weight: 700;
+  line-height: 1.15;
+}
+
+.intro {
+  margin: 0;
+  font-size: 1.125rem;
+  line-height: 1.6;
+  color: var(--ifm-color-emphasis-700);
+}

website/src/pages/features/index.tsx

@@ -0,0 +1,59 @@
+import type {ReactNode} from 'react';
+import Layout from '@theme/Layout';
+import Translate, {translate} from '@docusaurus/Translate';
+import FeatureGrid from '@site/src/components/FeatureGrid';
+import styles from './index.module.css';
+
+export default function FeaturesIndex(): ReactNode {
+  const metaTitle = translate({
+    id: 'meta.features.title',
+    message: "What's in the box — all StrayMark features",
+    description:
+      'OG/Twitter title and browser tab for the /features index (the " | StrayMark" suffix is appended by Docusaurus automatically)',
+  });
+  const metaDescription = translate({
+    id: 'meta.features.description',
+    message:
+      'Every StrayMark capability on one page: charters, governance, multi-model audit, TDE drift detection, the CLI, agent skills, and emergent observation.',
+    description: 'OG/Twitter description and meta description for the /features index',
+  });
+
+  return (
+    <Layout title={metaTitle} description={metaDescription}>
+      <main>
+        <header className={styles.header}>
+          <div className={styles.headerInner}>
+            <p className={styles.eyebrow}>
+              <Translate
+                id="features.index.eyebrow"
+                description="Small eyebrow label above the /features H1"
+              >
+                Features
+              </Translate>
+            </p>
+            <h1 className={styles.title}>
+              <Translate
+                id="features.index.title"
+                description="H1 of the /features index page"
+              >
+                What's in the box
+              </Translate>
+            </h1>
+            <p className={styles.intro}>
+              <Translate
+                id="features.index.intro"
+                description="Intro paragraph above the FeatureGrid on the /features index page"
+              >
+                Nine capabilities that compose StrayMark — from cognitive
+                discipline and repo-native governance to multi-model audit
+                and emergent observation. Pick the one that maps to the
+                problem you're solving; each links to a focused page.
+              </Translate>
+            </p>
+          </div>
+        </header>
+        <FeatureGrid />
+      </main>
+    </Layout>
+  );
+}

website/static/robots.txt

@@ -0,0 +1,9 @@
+# StrayMark robots.txt
+# Crawl policy: open. The site is public marketing + docs + blog.
+# Sitemap directive points crawlers at the locale-aware index, which
+# in turn references the three per-locale sitemaps (en, es, zh-CN).
+
+User-agent: *
+Allow: /
+
+Sitemap: https://straymark.dev/sitemap-index.xml

website/static/sitemap-index.xml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+  <sitemap>
+    <loc>https://straymark.dev/sitemap.xml</loc>
+  </sitemap>
+  <sitemap>
+    <loc>https://straymark.dev/es/sitemap.xml</loc>
+  </sitemap>
+  <sitemap>
+    <loc>https://straymark.dev/zh-CN/sitemap.xml</loc>
+  </sitemap>
+</sitemapindex>