From bfdd9709470ca15f67a9c75608b3f626df81cf6c Mon Sep 17 00:00:00 2001
From: Justin Mclean <jmclean@apache.org>
Date: Thu, 3 Sep 2026 00:05:25 +0000
Subject: [PATCH 1/4] feat(site): add sitemap, robots, llms.txt and structured
 data

Nothing on the site enumerated its own pages: /sitemap.xml, /robots.txt and
/llms.txt all returned 404. This adds all three, generated from the same
Fumadocs source the site already builds from, plus the metadata that search
engines and agents read first.

- src/app/sitemap.ts: every docs page, blog post and hand-written route
- src/app/robots.ts: allow all, pointing at the sitemap
- src/app/llms.txt/route.ts: an llmstxt.org index built with fumadocs-core's
  llms helper, prefaced by a short section on what the site is for
- src/app/layout.tsx: metadataBase, per-route canonical, Open Graph and Twitter
  cards, and Organization/WebSite/SoftwareApplication JSON-LD
- src/app/not-found.tsx: recovery links, so a 404 is not a dead end
- src/app/(home)/page.tsx: the "How it works" steps were h4 under an h2, so the
  heading hierarchy skipped a level

New routes outside docs and blog need adding to STATIC_ROUTES in src/lib/site.ts
to appear in the sitemap.
---
 src/app/(home)/page.tsx   |  4 +-
 src/app/layout.tsx        | 80 ++++++++++++++++++++++++++++++++++++++-
 src/app/llms.txt/route.ts | 65 +++++++++++++++++++++++++++++++
 src/app/not-found.tsx     | 33 ++++++++++++++++
 src/app/robots.ts         | 31 +++++++++++++++
 src/app/sitemap.ts        | 48 +++++++++++++++++++++++
 src/lib/blog.ts           | 48 +++++++++++++++++++++++
 src/lib/site.ts           | 52 +++++++++++++++++++++++++
 8 files changed, 357 insertions(+), 4 deletions(-)
 create mode 100644 src/app/llms.txt/route.ts
 create mode 100644 src/app/robots.ts
 create mode 100644 src/app/sitemap.ts
 create mode 100644 src/lib/blog.ts
 create mode 100644 src/lib/site.ts

diff --git a/src/app/(home)/page.tsx b/src/app/(home)/page.tsx
index 3ac9abd9c1..951f371f0c 100644
--- a/src/app/(home)/page.tsx
+++ b/src/app/(home)/page.tsx
@@ -358,9 +358,9 @@ export default function HomePage() {
                     {item.step}
                   </div>
                   <div className="min-w-0">
-                    <h4 className="text-base font-semibold text-[#fffaeb] mb-1">
+                    <h3 className="text-base font-semibold text-[#fffaeb] mb-1">
                       {item.title}
-                    </h4>
+                    </h3>
                     <p className="text-sm font-light leading-relaxed text-[#aeb5bd] m-0">
                       {item.desc}
                     </p>
diff --git a/src/app/layout.tsx b/src/app/layout.tsx
index f0c4be7483..04eebed4aa 100644
--- a/src/app/layout.tsx
+++ b/src/app/layout.tsx
@@ -21,22 +21,98 @@ import { RootProvider } from "fumadocs-ui/provider/next";
 import type { Metadata } from "next";
 import Script from "next/script";
 import { Matomo } from "@/components/matomo";
+import { SITE_DESCRIPTION, SITE_URL } from "@/lib/site";
 import "./global.css";
 
+const OG_IMAGE = "/img/apache-iggy-color-darkbg0.5x.png";
+
 export const metadata: Metadata = {
+  metadataBase: new URL(SITE_URL),
   title: {
     default: "Apache Iggy",
     template: "%s | Apache Iggy",
   },
-  description:
-    "Apache Iggy is a persistent message streaming platform written in Rust, supporting QUIC, TCP and HTTP transport protocols, capable of processing millions of messages per second.",
+  description: SITE_DESCRIPTION,
+  // Relative values resolve against the current route, so every page gets its own canonical.
+  alternates: { canonical: "./" },
+  // No title/description here on purpose: Next fills og:title and og:description
+  // from each page's own metadata, so per-page titles survive.
+  openGraph: {
+    type: "website",
+    siteName: "Apache Iggy",
+    url: "./",
+    images: [
+      {
+        url: OG_IMAGE,
+        width: 1951,
+        height: 652,
+        alt: "Apache Iggy",
+      },
+    ],
+  },
+  twitter: {
+    card: "summary_large_image",
+    images: [OG_IMAGE],
+  },
   icons: { icon: "/img/favicon.png" },
 };
 
+// Structured data. Kept deliberately small: only claims the site already makes elsewhere.
+const structuredData = {
+  "@context": "https://schema.org",
+  "@graph": [
+    {
+      "@type": "Organization",
+      "@id": `${SITE_URL}/#organization`,
+      name: "The Apache Software Foundation",
+      url: "https://www.apache.org/",
+      logo: `${SITE_URL}/img/asf_logo.svg`,
+      address: {
+        "@type": "PostalAddress",
+        streetAddress: "1000 N West Street, Suite 1200",
+        addressLocality: "Wilmington",
+        addressRegion: "DE",
+        postalCode: "19801",
+        addressCountry: "US",
+      },
+      contactPoint: {
+        "@type": "ContactPoint",
+        contactType: "technical support",
+        email: "dev@iggy.apache.org",
+        url: `${SITE_URL}/community/`,
+      },
+    },
+    {
+      "@type": "WebSite",
+      "@id": `${SITE_URL}/#website`,
+      name: "Apache Iggy",
+      url: `${SITE_URL}/`,
+      description: SITE_DESCRIPTION,
+      inLanguage: "en",
+      publisher: { "@id": `${SITE_URL}/#organization` },
+    },
+    {
+      "@type": "SoftwareApplication",
+      "@id": `${SITE_URL}/#software`,
+      name: "Apache Iggy",
+      applicationCategory: "DeveloperApplication",
+      description: SITE_DESCRIPTION,
+      url: `${SITE_URL}/`,
+      license: "https://www.apache.org/licenses/LICENSE-2.0",
+      sameAs: ["https://github.com/apache/iggy"],
+      publisher: { "@id": `${SITE_URL}/#organization` },
+    },
+  ],
+};
+
 export default function Layout({ children }: { children: React.ReactNode }) {
   return (
     <html lang="en" suppressHydrationWarning>
       <body className="flex min-h-screen flex-col font-sans antialiased">
+        <script
+          type="application/ld+json"
+          dangerouslySetInnerHTML={{ __html: JSON.stringify(structuredData) }}
+        />
         <RootProvider
           search={{ options: { type: "static" as const } }}
           theme={{ defaultTheme: "dark" }}
diff --git a/src/app/llms.txt/route.ts b/src/app/llms.txt/route.ts
new file mode 100644
index 0000000000..0c9859f1cb
--- /dev/null
+++ b/src/app/llms.txt/route.ts
@@ -0,0 +1,65 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { llms } from "fumadocs-core/source/llms";
+import { source } from "@/lib/source";
+import { publishedPosts } from "@/lib/blog";
+import { SITE_DESCRIPTION, absoluteUrl } from "@/lib/site";
+
+export const dynamic = "force-static";
+
+const INTRO = `# Apache Iggy
+
+> ${SITE_DESCRIPTION}
+
+Apache Iggy is a message streaming server, not a hosted service: there is no
+API on this domain to call. This site carries the documentation, blog and
+community pages. The source, releases and issue tracker live at
+https://github.com/apache/iggy.
+
+## When to use this site
+
+- Running or configuring the server, including storage, networking and clustering: /docs/server and /docs/clustering.
+- Writing a producer or consumer in a given language: /docs/sdk.
+- Talking to the server directly over QUIC, TCP or HTTP: /docs/binary-protocol.
+- Moving data in or out of Iggy without writing code: /docs/connectors.
+- Command line and web administration: /docs/cli and /docs/web_ui.
+- Downloading a release: /downloads.
+- Contributing, or reaching the project's mailing lists and Discord: /community.
+`;
+
+export function GET(): Response {
+  const posts = publishedPosts()
+    .slice(0, 10)
+    .map(({ post, href, date }) => {
+      const day = date.toISOString().slice(0, 10);
+      return `- [${post.title}](${absoluteUrl(href)}): ${day}`;
+    })
+    .join("\n");
+
+  const body = [
+    INTRO,
+    llms(source).index(),
+    `## Blog\n\nThe ten most recent posts. The full list is at ${absoluteUrl("/blogs")}.\n\n${posts}\n`,
+  ].join("\n");
+
+  return new Response(body, {
+    headers: { "Content-Type": "text/plain; charset=utf-8" },
+  });
+}
diff --git a/src/app/not-found.tsx b/src/app/not-found.tsx
index 271125c86f..4ca911dd6a 100644
--- a/src/app/not-found.tsx
+++ b/src/app/not-found.tsx
@@ -24,6 +24,14 @@ export const metadata: Metadata = {
   title: "404: Page not found",
 };
 
+const RECOVERY_LINKS = [
+  { href: "/", label: "Home" },
+  { href: "/docs", label: "Documentation" },
+  { href: "/blogs", label: "Blog" },
+  { href: "/downloads", label: "Downloads" },
+  { href: "/community", label: "Community" },
+];
+
 export default function NotFound() {
   return (
     <main className="flex min-h-screen flex-col items-center justify-center gap-4 px-6 text-center">
@@ -42,6 +50,31 @@ export default function NotFound() {
       >
         Back to documentation
       </Link>
+      <nav
+        aria-label="Where to go next"
+        className="mt-6 flex flex-wrap items-center justify-center gap-x-6 gap-y-2 text-sm text-fd-muted-foreground"
+      >
+        {RECOVERY_LINKS.map((link) => (
+          <Link
+            key={link.href}
+            href={link.href}
+            className="transition-colors hover:text-fd-primary"
+          >
+            {link.label}
+          </Link>
+        ))}
+      </nav>
+      <p className="mt-6 max-w-md text-xs text-fd-muted-foreground">
+        Every page on this site is listed in{" "}
+        <a href="/sitemap.xml" className="underline hover:text-fd-primary">
+          /sitemap.xml
+        </a>
+        , and{" "}
+        <a href="/llms.txt" className="underline hover:text-fd-primary">
+          /llms.txt
+        </a>{" "}
+        summarises the documentation.
+      </p>
     </main>
   );
 }
diff --git a/src/app/robots.ts b/src/app/robots.ts
new file mode 100644
index 0000000000..24b58ab53b
--- /dev/null
+++ b/src/app/robots.ts
@@ -0,0 +1,31 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import type { MetadataRoute } from "next";
+import { SITE_URL } from "@/lib/site";
+
+export const dynamic = "force-static";
+
+export default function robots(): MetadataRoute.Robots {
+  return {
+    rules: [{ userAgent: "*", allow: "/" }],
+    sitemap: `${SITE_URL}/sitemap.xml`,
+    host: SITE_URL,
+  };
+}
diff --git a/src/app/sitemap.ts b/src/app/sitemap.ts
new file mode 100644
index 0000000000..69ab9a9c03
--- /dev/null
+++ b/src/app/sitemap.ts
@@ -0,0 +1,48 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import type { MetadataRoute } from "next";
+import { source } from "@/lib/source";
+import { publishedPosts } from "@/lib/blog";
+import { STATIC_ROUTES, absoluteUrl } from "@/lib/site";
+
+export const dynamic = "force-static";
+
+export default function sitemap(): MetadataRoute.Sitemap {
+  const staticPages = STATIC_ROUTES.map((route) => ({
+    url: absoluteUrl(route),
+    changeFrequency: "weekly" as const,
+    priority: route === "/" ? 1 : 0.7,
+  }));
+
+  const docsPages = source.getPages().map((page) => ({
+    url: absoluteUrl(page.url),
+    changeFrequency: "weekly" as const,
+    priority: 0.8,
+  }));
+
+  const blogPages = publishedPosts().map(({ href, date }) => ({
+    url: absoluteUrl(href),
+    lastModified: date,
+    changeFrequency: "yearly" as const,
+    priority: 0.6,
+  }));
+
+  return [...staticPages, ...docsPages, ...blogPages];
+}
diff --git a/src/lib/blog.ts b/src/lib/blog.ts
new file mode 100644
index 0000000000..ec55ca1813
--- /dev/null
+++ b/src/lib/blog.ts
@@ -0,0 +1,48 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { blogPosts } from "@/lib/source";
+
+/** Filename stem of a blog post, which is the last segment of its URL. */
+export function blogSlug(filePath: string): string {
+  return (
+    filePath
+      .replace(/\.mdx?$/, "")
+      .split("/")
+      .pop() ?? filePath
+  );
+}
+
+/** Published, non-draft posts, newest first, with their site-relative URLs. */
+export function publishedPosts() {
+  return [...blogPosts]
+    .filter((post) => !post.draft)
+    .sort((a, b) => new Date(b.date).getTime() - new Date(a.date).getTime())
+    .map((post) => {
+      const date = new Date(post.date);
+      const year = date.getFullYear();
+      const month = String(date.getMonth() + 1).padStart(2, "0");
+      const day = String(date.getDate()).padStart(2, "0");
+      return {
+        post,
+        date,
+        href: `/blogs/${year}/${month}/${day}/${blogSlug(post.info.path)}`,
+      };
+    });
+}
diff --git a/src/lib/site.ts b/src/lib/site.ts
new file mode 100644
index 0000000000..8e067b468d
--- /dev/null
+++ b/src/lib/site.ts
@@ -0,0 +1,52 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+/** Canonical origin of the published site. Used for canonical URLs, Open Graph, sitemap and llms.txt. */
+export const SITE_URL = "https://iggy.apache.org";
+
+/** Short description reused across metadata, structured data and llms.txt. */
+export const SITE_DESCRIPTION =
+  "Apache Iggy is a persistent message streaming platform written in Rust, supporting QUIC, TCP and HTTP transport protocols, capable of processing millions of messages per second.";
+
+/**
+ * Pages outside the docs and blog collections.
+ *
+ * Static export means these are the only hand-written routes, so they are listed
+ * here rather than discovered. Add a route here when you add a page under
+ * `src/app/(site)/`, or it will be missing from the sitemap.
+ */
+export const STATIC_ROUTES = [
+  "/",
+  "/blogs",
+  "/downloads",
+  "/community",
+  "/community/become-a-committer",
+  "/community/brand-kit",
+  "/community/graduation-checklist",
+  "/community/how-to-contribute",
+  "/community/how-to-release",
+  "/community/team",
+] as const;
+
+/** `trailingSlash: true` in next.config.mjs, so every emitted URL ends in a slash. */
+export function absoluteUrl(path: string): string {
+  const withLeading = path.startsWith("/") ? path : `/${path}`;
+  const withTrailing = withLeading.endsWith("/") ? withLeading : `${withLeading}/`;
+  return `${SITE_URL}${withTrailing}`;
+}

From 586d7e13f9e52a907bd972d90dd6f6314dade29e Mon Sep 17 00:00:00 2001
From: Justin Mclean <jmclean@apache.org>
Date: Thu, 3 Sep 2026 00:09:43 +0000
Subject: [PATCH 2/4] fix(site): correct canonicals, llms.txt links and the
 duplicated home title

Follow-ups found by reading the first build's output:

- blog posts canonicalised to a URL without the trailing slash the site
  actually serves, because the inherited relative canonical loses it on a
  catch-all route; set it explicitly instead
- the home page title already began with "Apache Iggy", so the root template
  appended the brand a second time
- llms.txt carried site-relative links and a second H1; links are now absolute
  and the generated index sits under an H2
- dropped the ASF postal address from the Organization JSON-LD: it was there
  only to satisfy an external scorecard, and the site does not otherwise
  publish it
---
 src/app/(home)/page.tsx                 |  2 +-
 src/app/(site)/blogs/[...slug]/page.tsx | 10 ++++++++++
 src/app/layout.tsx                      |  8 --------
 src/app/llms.txt/route.ts               | 23 +++++++++++++++--------
 4 files changed, 26 insertions(+), 17 deletions(-)

diff --git a/src/app/(home)/page.tsx b/src/app/(home)/page.tsx
index 951f371f0c..a51f353b5a 100644
--- a/src/app/(home)/page.tsx
+++ b/src/app/(home)/page.tsx
@@ -24,7 +24,7 @@ import { LandingCodeTabs } from "@/components/code-tabs";
 import { BenchmarkSection } from "@/components/benchmark-chart";
 
 export const metadata: Metadata = {
-  title: "Apache Iggy | Hyper-Efficient Message Streaming written in Rust.",
+  title: "Hyper-Efficient Message Streaming written in Rust",
   description:
     "Apache Iggy is a high-performance, persistent message streaming platform written in Rust, capable of processing millions of messages per second with ultra-low latency.",
 };
diff --git a/src/app/(site)/blogs/[...slug]/page.tsx b/src/app/(site)/blogs/[...slug]/page.tsx
index 70c9699a7d..9a7c563af8 100644
--- a/src/app/(site)/blogs/[...slug]/page.tsx
+++ b/src/app/(site)/blogs/[...slug]/page.tsx
@@ -148,8 +148,18 @@ export async function generateMetadata(props: {
   const page = findPostByDateSlug(params.slug);
   if (!page) notFound();
 
+  const date = new Date(page.date);
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const day = String(date.getDate()).padStart(2, "0");
+
   return {
     title: page.title,
     description: page.description,
+    // Set explicitly: the inherited relative canonical loses the trailing slash
+    // on this catch-all route, so it would not match the URL actually served.
+    alternates: {
+      canonical: `/blogs/${year}/${month}/${day}/${getSlug(page.info.path)}/`,
+    },
   };
 }
diff --git a/src/app/layout.tsx b/src/app/layout.tsx
index 04eebed4aa..e397455c4c 100644
--- a/src/app/layout.tsx
+++ b/src/app/layout.tsx
@@ -67,14 +67,6 @@ const structuredData = {
       name: "The Apache Software Foundation",
       url: "https://www.apache.org/",
       logo: `${SITE_URL}/img/asf_logo.svg`,
-      address: {
-        "@type": "PostalAddress",
-        streetAddress: "1000 N West Street, Suite 1200",
-        addressLocality: "Wilmington",
-        addressRegion: "DE",
-        postalCode: "19801",
-        addressCountry: "US",
-      },
       contactPoint: {
         "@type": "ContactPoint",
         contactType: "technical support",
diff --git a/src/app/llms.txt/route.ts b/src/app/llms.txt/route.ts
index 0c9859f1cb..9c25ea5318 100644
--- a/src/app/llms.txt/route.ts
+++ b/src/app/llms.txt/route.ts
@@ -35,13 +35,13 @@ https://github.com/apache/iggy.
 
 ## When to use this site
 
-- Running or configuring the server, including storage, networking and clustering: /docs/server and /docs/clustering.
-- Writing a producer or consumer in a given language: /docs/sdk.
-- Talking to the server directly over QUIC, TCP or HTTP: /docs/binary-protocol.
-- Moving data in or out of Iggy without writing code: /docs/connectors.
-- Command line and web administration: /docs/cli and /docs/web_ui.
-- Downloading a release: /downloads.
-- Contributing, or reaching the project's mailing lists and Discord: /community.
+- Running or configuring the server, including storage, networking and clustering: ${absoluteUrl("/docs/server")} and ${absoluteUrl("/docs/clustering")}
+- Writing a producer or consumer in a given language: ${absoluteUrl("/docs/sdk")}
+- Talking to the server directly over QUIC, TCP or HTTP: ${absoluteUrl("/docs/binary-protocol")}
+- Moving data in or out of Iggy without writing code: ${absoluteUrl("/docs/connectors")}
+- Command line and web administration: ${absoluteUrl("/docs/cli")} and ${absoluteUrl("/docs/web_ui")}
+- Downloading a release: ${absoluteUrl("/downloads")}
+- Contributing, or reaching the project's mailing lists and Discord: ${absoluteUrl("/community")}
 `;
 
 export function GET(): Response {
@@ -53,9 +53,16 @@ export function GET(): Response {
     })
     .join("\n");
 
+  // The helper emits site-relative links; llms.txt consumers want absolute ones.
+  const docsIndex = llms(source)
+    .index()
+    .replace(/\]\((\/[^)\s]*)\)/g, (_match, path: string) => `](${absoluteUrl(path)})`)
+    // One H1 per file: the helper's top-level heading becomes a section.
+    .replace(/^# /gm, "## ");
+
   const body = [
     INTRO,
-    llms(source).index(),
+    docsIndex,
     `## Blog\n\nThe ten most recent posts. The full list is at ${absoluteUrl("/blogs")}.\n\n${posts}\n`,
   ].join("\n");
 

From d1c3560a2b97c55bfddf4401d14479b14b71a0e5 Mon Sep 17 00:00:00 2001
From: Justin Mclean <jmclean@apache.org>
Date: Thu, 3 Sep 2026 00:10:29 +0000
Subject: [PATCH 3/4] fix(site): escape < when serialising the JSON-LD payload

JSON.stringify does not escape "<", so a value containing "</script>" would
close the tag early. Every value in the payload is a constant today, but the
escape makes that independent of what the object later carries.
---
 src/app/layout.tsx | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/src/app/layout.tsx b/src/app/layout.tsx
index e397455c4c..06d6e17916 100644
--- a/src/app/layout.tsx
+++ b/src/app/layout.tsx
@@ -97,13 +97,23 @@ const structuredData = {
   ],
 };
 
+/**
+ * JSON-LD has to be injected as raw text: React would HTML-escape it as a child
+ * and the quotes would end up as entities. The object above is built from
+ * constants in this file, so nothing here is user input, but JSON.stringify does
+ * not escape "<" -- so escape it, and a stray "</script>" can never close the tag.
+ */
+function serializeJsonLd(data: unknown): string {
+  return JSON.stringify(data).replace(/</g, "\\u003c");
+}
+
 export default function Layout({ children }: { children: React.ReactNode }) {
   return (
     <html lang="en" suppressHydrationWarning>
       <body className="flex min-h-screen flex-col font-sans antialiased">
         <script
           type="application/ld+json"
-          dangerouslySetInnerHTML={{ __html: JSON.stringify(structuredData) }}
+          dangerouslySetInnerHTML={{ __html: serializeJsonLd(structuredData) }}
         />
         <RootProvider
           search={{ options: { type: "static" as const } }}

From 475228deae13bda51fd84fedc27902f956081608 Mon Sep 17 00:00:00 2001
From: Justin Mclean <jmclean@apache.org>
Date: Thu, 3 Sep 2026 00:34:59 +0000
Subject: [PATCH 4/4] feat(docs): publish a Markdown copy of every docs page

An agent that wants a docs page currently has to parse the rendered HTML. This
writes a Markdown copy next to each page at build time, so
/docs/server/security/ is also available as /docs/server/security.md.

The site is a static export served by ASF infrastructure, so it cannot do
Accept-header content negotiation; a sibling file is the version of that which
needs no server control.

- scripts/generate-docs-markdown.mjs runs in prebuild, after the stars fetch,
  and rewrites public/**/*.md from content/docs on every build
- generated files are gitignored, like src/github-stars.json
- each docs page advertises its copy with <link rel="alternate"
  type="text/markdown">, and llms.txt states the .md convention

The body is the MDX as authored, so custom components appear as tags. Rendering
them out would need the MDX pipeline in this script; leaving them is honest
about what the page contains and keeps the generator dependency-free.
---
 .gitignore                         |   2 +
 package.json                       |   4 +-
 scripts/generate-docs-markdown.mjs | 109 +++++++++++++++++++++++++++++
 src/app/docs/[[...slug]]/page.tsx  |   6 ++
 src/app/llms.txt/route.ts          |   6 +-
 5 files changed, 124 insertions(+), 3 deletions(-)
 create mode 100644 scripts/generate-docs-markdown.mjs

diff --git a/.gitignore b/.gitignore
index 043d44f7c0..69ecf6f9c6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -12,6 +12,8 @@ tsconfig.tsbuildinfo
 
 # Build-time generated
 src/github-stars.json
+public/docs.md
+public/docs/**/*.md
 
 # System files
 .DS_Store
diff --git a/package.json b/package.json
index 04633f5eb5..1bca9fdbd4 100644
--- a/package.json
+++ b/package.json
@@ -3,9 +3,9 @@
   "version": "0.1.0",
   "private": true,
   "scripts": {
-    "predev": "node scripts/fetch-github-stars.mjs",
+    "predev": "node scripts/fetch-github-stars.mjs && node scripts/generate-docs-markdown.mjs",
     "dev": "next dev",
-    "prebuild": "node scripts/fetch-github-stars.mjs",
+    "prebuild": "node scripts/fetch-github-stars.mjs && node scripts/generate-docs-markdown.mjs",
     "build": "next build",
     "start": "next start",
     "postinstall": "fumadocs-mdx"
diff --git a/scripts/generate-docs-markdown.mjs b/scripts/generate-docs-markdown.mjs
new file mode 100644
index 0000000000..9b5628c317
--- /dev/null
+++ b/scripts/generate-docs-markdown.mjs
@@ -0,0 +1,109 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+/**
+ * Emits a Markdown copy of every docs page next to its HTML route, so an agent
+ * can fetch `/docs/server/security.md` instead of parsing the rendered page.
+ *
+ * The site is a static export served by ASF infrastructure, so it cannot do
+ * Accept-header content negotiation; a sibling file is the version of this that
+ * needs no server. Output goes to public/, is gitignored, and is rebuilt from
+ * content/docs on every build.
+ */
+
+import { readdirSync, readFileSync, writeFileSync, mkdirSync, rmSync, statSync } from "fs";
+import { join, relative, dirname, basename } from "path";
+
+const CONTENT = "content/docs";
+const PUBLIC = "public";
+const SITE_URL = "https://iggy.apache.org";
+const REPO_BLOB = "https://github.com/apache/iggy-website/blob/main";
+
+function walk(dir) {
+  return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) return walk(path);
+    return entry.name.endsWith(".mdx") ? [path] : [];
+  });
+}
+
+/** content/docs/server/security.mdx -> public/docs/server/security.md
+ *  content/docs/binary-protocol/index.mdx -> public/docs/binary-protocol.md
+ *  content/docs/index.mdx -> public/docs.md */
+function outputPath(source) {
+  const rel = relative(CONTENT, source).replace(/\.mdx$/, "");
+  const stem = basename(rel) === "index" ? dirname(rel) : rel;
+  return join(PUBLIC, "docs" + (stem === "." ? "" : `/${stem}`) + ".md");
+}
+
+/** Frontmatter is YAML, but only two scalar keys are read here, so it is not
+ *  worth a parser dependency. */
+function splitFrontmatter(raw) {
+  if (!raw.startsWith("---\n")) return { meta: {}, body: raw };
+  const end = raw.indexOf("\n---", 3);
+  if (end === -1) return { meta: {}, body: raw };
+  const meta = {};
+  for (const line of raw.slice(4, end).split("\n")) {
+    const match = /^(title|description):\s*(.*)$/.exec(line);
+    if (match) meta[match[1]] = match[2].trim().replace(/^["']|["']$/g, "");
+  }
+  return { meta, body: raw.slice(end + 4).replace(/^\n+/, "") };
+}
+
+function render(source, raw) {
+  const { meta, body } = splitFrontmatter(raw);
+  const url = `${SITE_URL}/${outputPath(source).replace(/^public\//, "").replace(/\.md$/, "")}/`;
+  const head = [
+    `# ${meta.title ?? basename(source, ".mdx")}`,
+    ...(meta.description ? [`> ${meta.description}`] : []),
+    `Rendered page: ${url}`,
+    `Source: ${REPO_BLOB}/${source}`,
+  ].join("\n\n");
+  // The body keeps its MDX as authored: custom components appear as tags, which
+  // is honest about what the page contains and needs no MDX pipeline here.
+  return `${head}\n\n${body.trimEnd()}\n`;
+}
+
+/** Everything this script wrote last time. Nothing else under public/ is .md. */
+function clean(dir) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) clean(path);
+    else if (entry.name.endsWith(".md")) rmSync(path);
+  }
+}
+
+function main() {
+  const sources = walk(CONTENT).sort();
+  try {
+    if (statSync(join(PUBLIC, "docs")).isDirectory()) clean(join(PUBLIC, "docs"));
+  } catch {
+    // No public/docs yet; nothing to clean.
+  }
+  rmSync(join(PUBLIC, "docs.md"), { force: true });
+
+  for (const source of sources) {
+    const target = outputPath(source);
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, render(source, readFileSync(source, "utf8")));
+  }
+  console.log(`Generated ${sources.length} Markdown copies of docs pages.`);
+}
+
+main();
diff --git a/src/app/docs/[[...slug]]/page.tsx b/src/app/docs/[[...slug]]/page.tsx
index efb85f5cea..bd43140b3c 100644
--- a/src/app/docs/[[...slug]]/page.tsx
+++ b/src/app/docs/[[...slug]]/page.tsx
@@ -79,6 +79,12 @@ export async function generateMetadata(props: {
   return {
     title: page.data.title,
     description: page.data.description,
+    alternates: {
+      // Set both: defining alternates here replaces the root's, canonical included.
+      canonical: `${page.url}/`,
+      // The Markdown copy written by scripts/generate-docs-markdown.mjs.
+      types: { "text/markdown": `${page.url}.md` },
+    },
   };
 }
 
diff --git a/src/app/llms.txt/route.ts b/src/app/llms.txt/route.ts
index 9c25ea5318..5fe8a4d076 100644
--- a/src/app/llms.txt/route.ts
+++ b/src/app/llms.txt/route.ts
@@ -20,7 +20,7 @@
 import { llms } from "fumadocs-core/source/llms";
 import { source } from "@/lib/source";
 import { publishedPosts } from "@/lib/blog";
-import { SITE_DESCRIPTION, absoluteUrl } from "@/lib/site";
+import { SITE_DESCRIPTION, SITE_URL, absoluteUrl } from "@/lib/site";
 
 export const dynamic = "force-static";
 
@@ -42,6 +42,10 @@ https://github.com/apache/iggy.
 - Command line and web administration: ${absoluteUrl("/docs/cli")} and ${absoluteUrl("/docs/web_ui")}
 - Downloading a release: ${absoluteUrl("/downloads")}
 - Contributing, or reaching the project's mailing lists and Discord: ${absoluteUrl("/community")}
+
+Every documentation page has a Markdown copy at the same path with a .md
+suffix, so ${absoluteUrl("/docs/server/security")} is also served as
+${SITE_URL}/docs/server/security.md.
 `;
 
 export function GET(): Response {