site: serve markdown when the client asks for it (#623)

* site: add prefersMarkdown Accept-header parser

* site: add Accept-header negotiation middleware

* site: expand llms.txt with downloads, version, and elevator pitch

Author: rgbkrk

app/llms.txt/route.ts

@@ -1,15 +1,42 @@
 import { getAllPosts } from "@/lib/blog";
 import { absoluteUrl, siteConfig } from "@/lib/site";
 
-export const dynamic = "force-static";
+export const revalidate = 300;
+
+async function getStableVersion(): Promise<string | null> {
+  try {
+    const res = await fetch(siteConfig.stableManifestUrl, {
+      next: { revalidate: 300 },
+    });
+    if (!res.ok) return null;
+    const manifest = await res.json();
+    return manifest.version ?? null;
+  } catch {
+    return null;
+  }
+}
 
 export async function GET() {
-  const posts = await getAllPosts();
+  const [posts, version] = await Promise.all([
+    getAllPosts(),
+    getStableVersion(),
+  ]);
+
+  const downloadsLine = version
+    ? `- [Latest releases](${siteConfig.links.releases}) for macOS, Windows, and Linux. Current stable: v${version}.`
+    : `- [Latest releases](${siteConfig.links.releases}) for macOS, Windows, and Linux.`;
 
   const lines = [
     `# ${siteConfig.name}`,
     "",
-    `> ${siteConfig.description}`,
+    "> Native interactive notebooks. Fast to launch, agent ready, humans welcome.",
+    "",
+    "nteract is a desktop notebook app for macOS, Windows, and Linux. Open a `.ipynb` file, a kernel starts, you're running code. No browser, no server to manage.",
+    "",
+    "## Downloads",
+    "",
+    downloadsLine,
+    `- [Source on GitHub](${siteConfig.links.github})`,
     "",
     "## Blog",
     "",

lib/accept.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+
+import { prefersMarkdown } from "@/lib/accept";
+
+describe("prefersMarkdown", () => {
+  it("returns true for the WebFetch Accept header", () => {
+    expect(prefersMarkdown("text/markdown, text/html, */*")).toBe(true);
+  });
+
+  it("returns false for a typical Chrome Accept header", () => {
+    expect(
+      prefersMarkdown(
+        "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8",
+      ),
+    ).toBe(false);
+  });
+
+  it("returns false for the curl default", () => {
+    expect(prefersMarkdown("*/*")).toBe(false);
+  });
+
+  it("respects q values when markdown q exceeds html q", () => {
+    expect(prefersMarkdown("text/html;q=0.5, text/markdown;q=0.9")).toBe(true);
+  });
+
+  it("breaks ties in favor of markdown when both are listed without q", () => {
+    expect(prefersMarkdown("text/html, text/markdown")).toBe(true);
+  });
+
+  it("returns false for null", () => {
+    expect(prefersMarkdown(null)).toBe(false);
+  });
+
+  it("returns false for an empty string", () => {
+    expect(prefersMarkdown("")).toBe(false);
+  });
+
+  it("returns false when only html is listed", () => {
+    expect(prefersMarkdown("text/html")).toBe(false);
+  });
+
+  it("ignores extra parameters and whitespace", () => {
+    expect(
+      prefersMarkdown("  text/markdown ;  q=0.95  , text/html ; q=0.5 "),
+    ).toBe(true);
+  });
+});

lib/accept.ts

@@ -0,0 +1,42 @@
+type AcceptEntry = {
+  type: string;
+  q: number;
+};
+
+function parseAcceptHeader(header: string): AcceptEntry[] {
+  return header
+    .split(",")
+    .map((raw) => raw.trim())
+    .filter(Boolean)
+    .map((raw) => {
+      const [typePart, ...params] = raw.split(";").map((part) => part.trim());
+      let q = 1;
+      for (const param of params) {
+        const [key, value] = param.split("=").map((part) => part.trim());
+        if (key === "q") {
+          const parsed = Number.parseFloat(value);
+          if (!Number.isNaN(parsed)) {
+            q = parsed;
+          }
+        }
+      }
+      return { type: typePart.toLowerCase(), q };
+    });
+}
+
+export function prefersMarkdown(
+  header: string | null | undefined,
+): boolean {
+  if (!header) return false;
+
+  const entries = parseAcceptHeader(header);
+  if (entries.length === 0) return false;
+
+  const markdown = entries.find((entry) => entry.type === "text/markdown");
+  if (!markdown) return false;
+
+  const html = entries.find((entry) => entry.type === "text/html");
+  if (!html) return true;
+
+  return markdown.q >= html.q;
+}

middleware.ts

@@ -0,0 +1,39 @@
+import { NextResponse, type NextRequest } from "next/server";
+
+import { prefersMarkdown } from "@/lib/accept";
+
+export const config = {
+  matcher: ["/", "/blog", "/blog/:slug"],
+};
+
+function rewriteTarget(pathname: string): string | null {
+  if (pathname === "/" || pathname === "/blog") {
+    return "/llms.txt";
+  }
+  if (pathname.startsWith("/blog/")) {
+    return `/blog/${pathname.slice("/blog/".length)}/raw.md`;
+  }
+  return null;
+}
+
+export function middleware(request: NextRequest) {
+  const wantsMarkdown =
+    request.method === "GET" &&
+    prefersMarkdown(request.headers.get("accept"));
+
+  const target = wantsMarkdown
+    ? rewriteTarget(request.nextUrl.pathname)
+    : null;
+
+  let response: NextResponse;
+  if (target) {
+    const url = request.nextUrl.clone();
+    url.pathname = target;
+    response = NextResponse.rewrite(url);
+  } else {
+    response = NextResponse.next();
+  }
+
+  response.headers.set("Vary", "Accept");
+  return response;
+}