test(docs): add comprehensive tests and monitoring for llms.txt endpoints (#4676)

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: [email protected] <[email protected]>
Co-authored-by: Deep Singhvi <[email protected]>
Co-authored-by: vercel[bot] <35613825+vercel[bot]@users.noreply.github.com>
Co-authored-by: David Konigsberg <[email protected]>

Author: 5 people

.github/workflows/monitor-llms-md-endpoints.yml

@@ -0,0 +1,34 @@
+name: Monitor LLM-friendly Docs Endpoints
+
+on:
+  schedule:
+    # Run every 5 minutes
+    - cron: '*/5 * * * *'
+  workflow_dispatch: # Allow manual triggering
+
+jobs:
+  monitor:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: |
+          npm install -g tsx
+
+      - name: Run monitoring script
+        env:
+          SLACK_WEBHOOK_URL_DOCS_INCIDENTS: ${{ secrets.SLACK_WEBHOOK_URL_DOCS_INCIDENTS }}
+          INCIDENT_API_KEY: ${{ secrets.INCIDENT_API_KEY }}
+          DRY_RUN: ${{ github.event_name == 'push' && '1' || '0' }}
+        continue-on-error: ${{ github.event_name == 'push' }}
+        run: |
+          tsx scripts/monitor/check-llms-md-endpoints.ts

biome.json

@@ -381,7 +381,8 @@
         "packages/workers/proxy/src/websocket.ts",
         "packages/generator-cli/src/**/*.ts",
         "packages/commons/visual-editor-server/src/mongodb-client.ts",
-        "servers/fdr-lambda/src/index.ts"
+        "servers/fdr-lambda/src/index.ts",
+        "scripts/monitor/**/*.ts"
       ],
       "linter": {
         "rules": {

packages/fern-docs/bundle/src/app/[host]/[domain]/api/fern-docs/markdown/route.test.ts

@@ -0,0 +1,59 @@
+import { NextRequest } from "next/server";
+import { describe, expect, it, vi } from "vitest";
+
+describe("markdown route slug handling", () => {
+    const createMockRequest = (pathname: string, searchParams: Record<string, string> = {}) => {
+        const url = new URL(`https://example.com${pathname}`);
+        Object.entries(searchParams).forEach(([key, value]) => {
+            url.searchParams.set(key, value);
+        });
+        return new NextRequest(url);
+    };
+
+    it("should prefer slug from search params over pathname", () => {
+        const request = createMockRequest("/api/fern-docs/markdown", { slug: "docs/quickstart" });
+
+        const slugParam = request.nextUrl.searchParams.get("slug");
+        const slug = slugParam ?? request.nextUrl.pathname.replace(/\.(md|mdx)$/, "");
+
+        expect(slug).toBe("docs/quickstart");
+    });
+
+    it("should fallback to pathname parsing when slug param is not present", () => {
+        const request = createMockRequest("/docs/quickstart.md");
+
+        const slugParam = request.nextUrl.searchParams.get("slug");
+        const slug = slugParam ?? request.nextUrl.pathname.replace(/\.(md|mdx)$/, "");
+
+        expect(slug).toBe("/docs/quickstart");
+    });
+
+    it("should handle .mdx extension in pathname fallback", () => {
+        const request = createMockRequest("/docs/quickstart.mdx");
+
+        const slugParam = request.nextUrl.searchParams.get("slug");
+        const slug = slugParam ?? request.nextUrl.pathname.replace(/\.(md|mdx)$/, "");
+
+        expect(slug).toBe("/docs/quickstart");
+    });
+
+    it("should handle nested paths in slug param", () => {
+        const request = createMockRequest("/api/fern-docs/markdown", {
+            slug: "learn/sdks/overview/quickstart"
+        });
+
+        const slugParam = request.nextUrl.searchParams.get("slug");
+        const slug = slugParam ?? request.nextUrl.pathname.replace(/\.(md|mdx)$/, "");
+
+        expect(slug).toBe("learn/sdks/overview/quickstart");
+    });
+
+    it("should handle empty slug param", () => {
+        const request = createMockRequest("/api/fern-docs/markdown", { slug: "" });
+
+        const slugParam = request.nextUrl.searchParams.get("slug");
+        const slug = slugParam ?? request.nextUrl.pathname.replace(/\.(md|mdx)$/, "");
+
+        expect(slug).toBe("");
+    });
+});

packages/fern-docs/bundle/src/app/[host]/[domain]/api/fern-docs/markdown/route.ts

@@ -30,7 +30,8 @@ export async function GET(
     const fernToken = req.headers.get("FERN_TOKEN") ?? (await cookies()).get(COOKIE_FERN_TOKEN)?.value;
 
     const path = req.nextUrl.pathname;
-    const slug = path.replace(MARKDOWN_PATTERN, "");
+    const slugParam = req.nextUrl.searchParams.get("slug");
+    const slug = slugParam ?? path.replace(MARKDOWN_PATTERN, "");
     const cleanSlug = removeLeadingSlash(slug);
 
     const loader = await createCachedDocsLoader(host, domain, fernToken);