From ee0c0171a5e41ba6b0d7143b8e523edf622a922f Mon Sep 17 00:00:00 2001
From: Jim Myhrberg <contact@jimeh.me>
Date: Fri, 16 Jan 2026 18:04:56 +0000
Subject: [PATCH] feat: add llms.txt and rename raw spec URL to match filename

- Add /llms.txt endpoint following llmstxt.org specification format
- Change raw markdown URL from /spec/{version}/raw.md to
  /spec/git-common-flow-v{version}.md to match download filename
- Add <link rel="alternate"> for raw markdown in spec pages
- Add Raw button to markdown view page

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 src/layouts/BaseLayout.astro                  | 11 +++++--
 src/layouts/SpecLayout.astro                  | 21 +++++++++----
 src/pages/llms.txt.ts                         | 25 ++++++++++++++++
 src/pages/spec/[version]/md.astro             | 22 ++++++++++++++
 .../spec/git-common-flow-v[version].md.ts     | 30 +++++++++++++++++++
 5 files changed, 100 insertions(+), 9 deletions(-)
 create mode 100644 src/pages/llms.txt.ts
 create mode 100644 src/pages/spec/git-common-flow-v[version].md.ts

diff --git a/src/layouts/BaseLayout.astro b/src/layouts/BaseLayout.astro
index 5ec85ce..3996007 100644
--- a/src/layouts/BaseLayout.astro
+++ b/src/layouts/BaseLayout.astro
@@ -11,7 +11,9 @@ interface Props {
 }
 
 const { title, description = config.description } = Astro.props;
-const fullTitle = title.includes(config.title) ? title : `${title} | ${config.title}`;
+const fullTitle = title.includes(config.title)
+  ? title
+  : `${title} | ${config.title}`;
 const canonicalUrl = Astro.url.href;
 ---
 
@@ -42,12 +44,15 @@ const canonicalUrl = Astro.url.href;
     <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
     <link rel="apple-touch-icon" href="/apple-touch-icon.png" />
 
+    <!-- Slot for page-specific head content -->
+    <slot name="head" />
+
     <!-- Prevent flash of wrong theme -->
     <script is:inline>
       (function () {
         const mode = localStorage.getItem("theme");
         const prefersDark = window.matchMedia(
-          "(prefers-color-scheme: dark)",
+          "(prefers-color-scheme: dark)"
         ).matches;
         if (mode === "dark" || (mode !== "light" && prefersDark)) {
           document.documentElement.classList.add("dark");
@@ -63,7 +68,7 @@ const canonicalUrl = Astro.url.href;
       document.addEventListener("astro:after-swap", () => {
         const mode = localStorage.getItem("theme");
         const prefersDark = window.matchMedia(
-          "(prefers-color-scheme: dark)",
+          "(prefers-color-scheme: dark)"
         ).matches;
         if (mode === "dark" || (mode !== "light" && prefersDark)) {
           document.documentElement.classList.add("dark");
diff --git a/src/layouts/SpecLayout.astro b/src/layouts/SpecLayout.astro
index 9304dd6..bbc45d8 100644
--- a/src/layouts/SpecLayout.astro
+++ b/src/layouts/SpecLayout.astro
@@ -31,7 +31,11 @@ const markdown = content.replace(/^---[\s\S]*?---\n/, "");
 const parsed = await parseSpecContent(markdown);
 
 // Read SVG content for inline embedding
-const svgFilePath = path.join(process.cwd(), "src/content/spec", `${version}.svg`);
+const svgFilePath = path.join(
+  process.cwd(),
+  "src/content/spec",
+  `${version}.svg`
+);
 let svgContent: string | null = null;
 if (fs.existsSync(svgFilePath)) {
   svgContent = fs.readFileSync(svgFilePath, "utf-8");
@@ -39,14 +43,19 @@ if (fs.existsSync(svgFilePath)) {
 ---
 
 <BaseLayout title={spec.data.title}>
+  <Fragment slot="head">
+    <link
+      rel="alternate"
+      type="text/markdown"
+      href={`/spec/git-common-flow-v${version}.md`}
+      title="Raw Markdown"
+    />
+  </Fragment>
+
   <Header version={version} versions={versions} />
 
   <main>
-    <Hero
-      version={version}
-      versions={versions}
-      svgContent={svgContent}
-    />
+    <Hero version={version} versions={versions} svgContent={svgContent} />
 
     <AboutSection
       introduction={parsed.introduction}
diff --git a/src/pages/llms.txt.ts b/src/pages/llms.txt.ts
new file mode 100644
index 0000000..afbc049
--- /dev/null
+++ b/src/pages/llms.txt.ts
@@ -0,0 +1,25 @@
+import type { APIRoute } from "astro";
+import { getVersionInfo } from "../utils/versions";
+
+export const GET: APIRoute = async () => {
+  const { currentVersion } = await getVersionInfo();
+
+  const content = `# Common-Flow
+
+> A Git workflow specification combining GitHub Flow with versioned releases.
+
+Common-Flow is a sensible git workflow based on GitHub Flow, with the addition
+of versioned releases, optional release branches, and without the requirement
+to deploy to production all the time.
+
+## Docs
+
+- [Git Common-Flow Specification](/spec/git-common-flow-v${currentVersion}.md): The complete Git Common-Flow v${currentVersion} specification in Markdown format
+`;
+
+  return new Response(content, {
+    headers: {
+      "Content-Type": "text/plain; charset=utf-8",
+    },
+  });
+};
diff --git a/src/pages/spec/[version]/md.astro b/src/pages/spec/[version]/md.astro
index a777d6a..e87e7fd 100644
--- a/src/pages/spec/[version]/md.astro
+++ b/src/pages/spec/[version]/md.astro
@@ -116,6 +116,15 @@ const previewHtml = await unified()
 ---
 
 <BaseLayout title={`${spec.data.title} - Markdown`}>
+  <Fragment slot="head">
+    <link
+      rel="alternate"
+      type="text/markdown"
+      href={`/spec/git-common-flow-v${version}.md`}
+      title="Raw Markdown"
+    />
+  </Fragment>
+
   <!-- Header -->
   <header
     class="sticky top-0 z-50 border-b
@@ -227,6 +236,19 @@ const previewHtml = await unified()
               </div>
             </div>
 
+            <!-- Raw button -->
+            <a
+              href={`/spec/git-common-flow-v${version}.md`}
+              class="inline-flex items-center gap-1.5 px-3 py-1.5 text-sm
+                     font-medium rounded-lg transition-colors
+                     text-gray-600 dark:text-neutral-400
+                     hover:bg-gray-100 hover:text-gray-950
+                     dark:hover:bg-neutral-800 dark:hover:text-neutral-50"
+            >
+              <Icon name="heroicons:document-text" class="w-4 h-4" />
+              <span>Raw</span>
+            </a>
+
             <!-- Download button -->
             <button
               id="download-btn"
diff --git a/src/pages/spec/git-common-flow-v[version].md.ts b/src/pages/spec/git-common-flow-v[version].md.ts
new file mode 100644
index 0000000..03047ea
--- /dev/null
+++ b/src/pages/spec/git-common-flow-v[version].md.ts
@@ -0,0 +1,30 @@
+import type { APIRoute, GetStaticPaths } from "astro";
+import { getCollection } from "astro:content";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export const getStaticPaths: GetStaticPaths = async () => {
+  const specs = await getCollection("spec");
+  return specs.map((spec) => ({
+    params: { version: spec.data.version },
+  }));
+};
+
+export const GET: APIRoute = ({ params }) => {
+  const version = params.version;
+  const filePath = path.join(
+    process.cwd(),
+    "src/content/spec",
+    `${version}.md`
+  );
+  const content = fs.readFileSync(filePath, "utf-8");
+  const markdown = content.replace(/^---[\s\S]*?---\n/, "");
+  const filename = `git-common-flow-v${version}.md`;
+
+  return new Response(markdown, {
+    headers: {
+      "Content-Type": "text/markdown; charset=utf-8",
+      "Content-Disposition": `inline; filename="${filename}"`,
+    },
+  });
+};