next-ai-discovery 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+
+The MIT License (MIT)
+
+Copyright (c) 2025 Nivalis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,267 @@
+# next-ai-discovery
+
+Next.js 16 (App Router) helpers to make your site AI-discoverable by serving Markdown variants and advertising them via standard `<link rel="alternate" type="text/markdown" ...>` tags.
+
+What this package provides:
+
+- A `proxy.ts` factory to rewrite Markdown requests to a single internal route handler
+- A route handler factory to serve per-page Markdown with correct headers (`Content-Type`, `Vary: Accept`)
+- Metadata helpers to advertise per-page Markdown alternates
+- A `llms.txt` route handler factory (and optional `llms-full.txt`)
+
+## Core behavior (explicit contract)
+
+- Only these requests are rewritten to the internal Markdown endpoint:
+  - URLs ending in `.md` (example: `/docs.md`)
+  - Requests whose `Accept` header contains `text/markdown` (example: `Accept: text/markdown, text/html;q=0.9`)
+- Other dot-paths are never rewritten (assets). Example: `/logo.png` is not rewritten.
+- Root mapping is intentional: `/` is normalized to `/index`, so the home page Markdown twin is `/index.md`.
+
+## Install
+
+```bash
+npm i next-ai-discovery
+# or
+pnpm add next-ai-discovery
+# or
+bun add next-ai-discovery
+```
+
+## Minimal setup (Next.js 16 App Router)
+
+### 1) Add `proxy.ts`
+
+Create `proxy.ts` at the project root:
+
+```ts
+import { createMarkdownProxy } from 'next-ai-discovery';
+
+export default createMarkdownProxy();
+
+export const config = {
+  // Recommended matcher:
+  // - runs on "normal" routes (no dot)
+  // - also runs on explicit `.md` routes
+  matcher: ['/((?!_next/|api/|.*\\..*).*)', '/(.*\\.md)'],
+};
+```
+
+Notes:
+
+- Your `matcher` controls where Next runs the proxy. The proxy itself still has its own rewrite rules.
+- Internal endpoint default is `DEFAULT_ENDPOINT_PATH = '/__aid/md'`.
+- The internal endpoint is automatically excluded to avoid rewrite loops.
+
+### 2) Add the internal Markdown endpoint
+
+Create `app/__aid/md/route.ts`:
+
+```ts
+import { createMarkdownRoute } from 'next-ai-discovery';
+import type { NextRequest } from 'next/server';
+
+const handler = createMarkdownRoute({
+  async getMarkdown(pathname, request: NextRequest) {
+    // IMPORTANT: `getMarkdown()` is your policy boundary.
+    // Enforce the same auth/policy as your HTML routes.
+
+    // Root is normalized to `/index`.
+    if (pathname === '/index') {
+      return {
+        frontmatter: {
+          title: 'home',
+          canonical: 'https://example.com/',
+        },
+        body: '# home\n\nhello.',
+      };
+    }
+
+    return null;
+  },
+});
+
+export const GET = handler;
+export const HEAD = handler;
+```
+
+Notes:
+
+- Responses include `Content-Type: text/markdown; charset=utf-8` and `Vary: Accept`.
+- `HEAD` is supported; the handler returns the same status/headers but no body.
+
+### 3) Add `llms.txt`
+
+`/llms.txt` is a proposed convention for publishing a short, curated Markdown index to help LLMs and agents understand your site.
+Reference: `https://llmstxt.org/`
+
+Create `app/llms.txt/route.ts`:
+
+```ts
+import { createLlmsTxtRoute } from 'next-ai-discovery';
+
+export const GET = createLlmsTxtRoute({
+  config: {
+    site: {
+      name: 'Example.com',
+      description: 'This site publishes articles about X.',
+      url: 'https://example.com',
+    },
+    sections: [{ title: 'Key sections', items: ['/blog', '/docs', '/about'] }],
+    markdown: {
+      appendDotMd: true,
+      acceptNegotiation: true,
+      fullIndexPath: '/llms-full.txt',
+    },
+  },
+});
+```
+
+Optional full variant:
+
+- Create `app/llms-full.txt/route.ts` with `variant: 'full'`.
+- “full” is not auto-generated by this package; it just selects a variant so you can return a larger inventory if you want.
+
+Advertising `llms.txt`:
+
+- This package does not auto-inject a global `<link ... href="/llms.txt">`.
+- If you want it, add it in your root `app/layout.tsx` metadata manually.
+
+## What crawlers will see (HTTP examples)
+
+```bash
+# content negotiation
+curl -i -H 'Accept: text/markdown' https://example.com/docs
+
+# explicit .md
+curl -i https://example.com/docs.md
+```
+
+Expected headers (both):
+
+- `Content-Type: text/markdown; charset=utf-8`
+- `Vary: Accept`
+
+## Per-page Markdown auto-discovery
+
+To advertise a Markdown twin from HTML using the Next.js Metadata API, use `withMarkdownAlternate()`.
+
+```ts
+import { withMarkdownAlternate } from 'next-ai-discovery';
+import type { Metadata } from 'next';
+
+export async function generateMetadata(): Promise<Metadata> {
+  return withMarkdownAlternate({ title: 'Docs' }, '/docs');
+}
+```
+
+This emits:
+
+```html
+<link rel="alternate" type="text/markdown" href="/docs.md" />
+```
+
+Home page note:
+
+- `pathnameToMd('/')` yields `/index.md` (because `/` is normalized to `/index`).
+
+## Configuration
+
+### `createMarkdownProxy(options)`
+
+- `endpointPath` (default: `/__aid/md`)
+- `enableDotMd` (default: `true`)
+- `enableAcceptNegotiation` (default: `true`)
+- `acceptHeader` (default: `text/markdown`)
+- `exclude(pathname): boolean` (optional)
+- `excludePrefixes` (default: `["/_next", "/api"]`)
+- `excludeExact` (default: `["/robots.txt", "/sitemap.xml"]`)
+- `onRewrite({ type: 'accept' | 'dotmd', pathname })` (optional)
+
+Precedence / terminology:
+
+- `config.matcher` decides which requests execute the proxy at all.
+- `exclude*` decides which requests the proxy will rewrite.
+
+Content negotiation semantics:
+
+- Any `Accept` header value that contains a comma-separated entry starting with `text/markdown` triggers Markdown (q-values are ignored).
+
+Dot-path behavior:
+
+- For `Accept` negotiation, the proxy will not rewrite “asset-like” URLs containing a dot after the last slash (example: `/logo.png`).
+- Explicit `.md` URLs are always eligible (example: `/docs.md`).
+
+### `createMarkdownRoute({ getMarkdown, includeFrontmatter, onServed })`
+
+- `getMarkdown(pathname, request)` returns `{ body, frontmatter? }` or `null`
+- `includeFrontmatter` (default: `true`)
+- `onServed({ pathname, status })` (optional)
+
+### Path normalization
+
+Internally, paths are normalized to make matching predictable:
+
+- `/` -> `/index`
+- Trailing slash is removed (`/docs/` -> `/docs`)
+- `.md` suffix is removed (`/docs.md` -> `/docs`)
+
+## Compatibility / runtime
+
+- Next.js: App Router only
+- Proxy (`proxy.ts`): Edge runtime (Next.js proxy)
+- Route handlers: can be Edge or Node depending on how you configure your Next route file; this library itself does not require Node-only APIs.
+
+## Why not HTML -> Markdown conversion?
+
+This package avoids HTML rewriting/conversion on purpose: it is hard to do reliably, and it risks leaking content. Instead, you provide an explicit Markdown representation via `getMarkdown()`.
+
+## Auth parity patterns
+
+This package intentionally makes `getMarkdown()` your policy boundary.
+
+### 1) Reuse an existing access check
+
+```ts
+import { createMarkdownRoute } from 'next-ai-discovery';
+import type { NextRequest } from 'next/server';
+
+async function canViewPath(request: NextRequest, pathname: string) {
+  // Example only. Wire this to your auth/session logic.
+  // Return false for protected routes.
+  return !pathname.startsWith('/admin');
+}
+
+const handler = createMarkdownRoute({
+  async getMarkdown(pathname, request) {
+    if (!(await canViewPath(request, pathname))) {
+      // Recommended default: return null (404) to avoid leaking existence.
+      return null;
+    }
+
+    return { body: `# ${pathname}\n` };
+  },
+});
+
+export const GET = handler;
+export const HEAD = handler;
+```
+
+### 2) 404 vs 401/403
+
+If your HTML route would redirect unauthenticated users, decide whether your Markdown variant should:
+
+- Return `404` (recommended for private areas)
+- Return `401/403`
+
+Because Next.js route handlers return `Response`, you can also wrap the handler and map outcomes.
+
+## Roadmap
+
+- frontmatter format options (yaml vs json vs none)
+- llms-full helpers (sitemap-driven inventory)
+- observability hooks (`onServed`, `onRewrite`) docs + examples
+- codemod/snippets for adding `withMarkdownAlternate()`
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_PROXY_EXCLUDE_PREFIXES = exports.DEFAULT_PROXY_EXCLUDE_EXACT = exports.DEFAULT_MARKDOWN_ACCEPT = exports.DEFAULT_ENDPOINT_PATH = exports.createMarkdownProxy = exports.pathnameToMd = exports.normalizePathname = exports.withMarkdownAlternate = exports.createMarkdownRoute = exports.createLlmsTxtRoute = exports.renderLlmsTxt = void 0;
+/* biome-ignore lint/performance/noBarrelFile: public entrypoint exports */
+var llms_js_1 = require("./llms.cjs");
+Object.defineProperty(exports, "renderLlmsTxt", { enumerable: true, get: function () { return llms_js_1.renderLlmsTxt; } });
+var llms_route_js_1 = require("./llms-route.cjs");
+Object.defineProperty(exports, "createLlmsTxtRoute", { enumerable: true, get: function () { return llms_route_js_1.createLlmsTxtRoute; } });
+var markdown_route_js_1 = require("./markdown-route.cjs");
+Object.defineProperty(exports, "createMarkdownRoute", { enumerable: true, get: function () { return markdown_route_js_1.createMarkdownRoute; } });
+var metadata_js_1 = require("./metadata.cjs");
+Object.defineProperty(exports, "withMarkdownAlternate", { enumerable: true, get: function () { return metadata_js_1.withMarkdownAlternate; } });
+var pathname_js_1 = require("./pathname.cjs");
+Object.defineProperty(exports, "normalizePathname", { enumerable: true, get: function () { return pathname_js_1.normalizePathname; } });
+Object.defineProperty(exports, "pathnameToMd", { enumerable: true, get: function () { return pathname_js_1.pathnameToMd; } });
+var proxy_js_1 = require("./proxy.cjs");
+Object.defineProperty(exports, "createMarkdownProxy", { enumerable: true, get: function () { return proxy_js_1.createMarkdownProxy; } });
+Object.defineProperty(exports, "DEFAULT_ENDPOINT_PATH", { enumerable: true, get: function () { return proxy_js_1.DEFAULT_ENDPOINT_PATH; } });
+Object.defineProperty(exports, "DEFAULT_MARKDOWN_ACCEPT", { enumerable: true, get: function () { return proxy_js_1.DEFAULT_MARKDOWN_ACCEPT; } });
+Object.defineProperty(exports, "DEFAULT_PROXY_EXCLUDE_EXACT", { enumerable: true, get: function () { return proxy_js_1.DEFAULT_PROXY_EXCLUDE_EXACT; } });
+Object.defineProperty(exports, "DEFAULT_PROXY_EXCLUDE_PREFIXES", { enumerable: true, get: function () { return proxy_js_1.DEFAULT_PROXY_EXCLUDE_PREFIXES; } });

package/dist/index.d.cts

@@ -0,0 +1,11 @@
+export { renderLlmsTxt } from "./llms.cjs";
+export { createLlmsTxtRoute } from "./llms-route.cjs";
+export { createMarkdownRoute } from "./markdown-route.cjs";
+export { withMarkdownAlternate } from "./metadata.cjs";
+export { normalizePathname, pathnameToMd } from "./pathname.cjs";
+export { createMarkdownProxy, DEFAULT_ENDPOINT_PATH, DEFAULT_MARKDOWN_ACCEPT, DEFAULT_PROXY_EXCLUDE_EXACT, DEFAULT_PROXY_EXCLUDE_PREFIXES, } from "./proxy.cjs";
+export type { LlmsTxtConfig, LlmsTxtProvider, LlmsTxtVariant, } from "./llms.cjs";
+export type { GetMarkdown, MarkdownContent, MarkdownRouteOptions, } from "./markdown-route.cjs";
+export type { MarkdownAlternateOptions } from "./metadata.cjs";
+export type { MarkdownProxyOptions, MarkdownRewriteType, } from "./proxy.cjs";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,mBAAkB;AAC1C,OAAO,EAAE,kBAAkB,EAAE,yBAAwB;AACrD,OAAO,EAAE,mBAAmB,EAAE,6BAA4B;AAC1D,OAAO,EAAE,qBAAqB,EAAE,uBAAsB;AACtD,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,uBAAsB;AAChE,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,uBAAuB,EACvB,2BAA2B,EAC3B,8BAA8B,GAC/B,oBAAmB;AACpB,YAAY,EACV,aAAa,EACb,eAAe,EACf,cAAc,GACf,mBAAkB;AACnB,YAAY,EACV,WAAW,EACX,eAAe,EACf,oBAAoB,GACrB,6BAA4B;AAC7B,YAAY,EAAE,wBAAwB,EAAE,uBAAsB;AAC9D,YAAY,EACV,oBAAoB,EACpB,mBAAmB,GACpB,oBAAmB"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { renderLlmsTxt } from "./llms.js";
+export { createLlmsTxtRoute } from "./llms-route.js";
+export { createMarkdownRoute } from "./markdown-route.js";
+export { withMarkdownAlternate } from "./metadata.js";
+export { normalizePathname, pathnameToMd } from "./pathname.js";
+export { createMarkdownProxy, DEFAULT_ENDPOINT_PATH, DEFAULT_MARKDOWN_ACCEPT, DEFAULT_PROXY_EXCLUDE_EXACT, DEFAULT_PROXY_EXCLUDE_PREFIXES, } from "./proxy.js";
+export type { LlmsTxtConfig, LlmsTxtProvider, LlmsTxtVariant, } from "./llms.js";
+export type { GetMarkdown, MarkdownContent, MarkdownRouteOptions, } from "./markdown-route.js";
+export type { MarkdownAlternateOptions } from "./metadata.js";
+export type { MarkdownProxyOptions, MarkdownRewriteType, } from "./proxy.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,kBAAkB;AAC1C,OAAO,EAAE,kBAAkB,EAAE,wBAAwB;AACrD,OAAO,EAAE,mBAAmB,EAAE,4BAA4B;AAC1D,OAAO,EAAE,qBAAqB,EAAE,sBAAsB;AACtD,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,sBAAsB;AAChE,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,uBAAuB,EACvB,2BAA2B,EAC3B,8BAA8B,GAC/B,mBAAmB;AACpB,YAAY,EACV,aAAa,EACb,eAAe,EACf,cAAc,GACf,kBAAkB;AACnB,YAAY,EACV,WAAW,EACX,eAAe,EACf,oBAAoB,GACrB,4BAA4B;AAC7B,YAAY,EAAE,wBAAwB,EAAE,sBAAsB;AAC9D,YAAY,EACV,oBAAoB,EACpB,mBAAmB,GACpB,mBAAmB"}

package/dist/index.js

@@ -0,0 +1,7 @@
+/* biome-ignore lint/performance/noBarrelFile: public entrypoint exports */
+export { renderLlmsTxt } from "./llms.js";
+export { createLlmsTxtRoute } from "./llms-route.js";
+export { createMarkdownRoute } from "./markdown-route.js";
+export { withMarkdownAlternate } from "./metadata.js";
+export { normalizePathname, pathnameToMd } from "./pathname.js";
+export { createMarkdownProxy, DEFAULT_ENDPOINT_PATH, DEFAULT_MARKDOWN_ACCEPT, DEFAULT_PROXY_EXCLUDE_EXACT, DEFAULT_PROXY_EXCLUDE_PREFIXES, } from "./proxy.js";

package/dist/llms-route.cjs

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLlmsTxtRoute = void 0;
+const llms_js_1 = require("./llms.cjs");
+const DEFAULT_HEADERS = {
+    'Content-Type': 'text/markdown; charset=utf-8',
+};
+const resolveConfig = (options, variant) => {
+    if ('config' in options && options.config) {
+        return options.config;
+    }
+    return options.getLlmsTxt(variant);
+};
+const handleError = (error) => {
+    console.error('[next-ai-discovery] llms.txt route error', error);
+    return new Response('Internal Server Error', {
+        status: 500,
+        headers: DEFAULT_HEADERS,
+    });
+};
+const createLlmsTxtRoute = (options) => {
+    const variant = options.variant ?? 'default';
+    return async (_request) => {
+        try {
+            const config = await resolveConfig(options, variant);
+            const body = (0, llms_js_1.renderLlmsTxt)(config, variant);
+            return new Response(body, {
+                status: 200,
+                headers: DEFAULT_HEADERS,
+            });
+        }
+        catch (error) {
+            return handleError(error);
+        }
+    };
+};
+exports.createLlmsTxtRoute = createLlmsTxtRoute;

package/dist/llms-route.d.cts

@@ -0,0 +1,13 @@
+import type { NextRequest } from 'next/server.js';
+import type { LlmsTxtConfig, LlmsTxtProvider, LlmsTxtVariant } from "./llms.cjs";
+export type LlmsTxtRouteOptions = {
+    config: LlmsTxtConfig;
+    getLlmsTxt?: never;
+    variant?: LlmsTxtVariant;
+} | {
+    config?: never;
+    getLlmsTxt: LlmsTxtProvider;
+    variant?: LlmsTxtVariant;
+};
+export declare const createLlmsTxtRoute: (options: LlmsTxtRouteOptions) => (_request: NextRequest) => Promise<Response>;
+//# sourceMappingURL=llms-route.d.ts.map

package/dist/llms-route.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llms-route.d.ts","sourceRoot":"","sources":["../src/llms-route.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,cAAc,EAAE,mBAAkB;AAEhF,MAAM,MAAM,mBAAmB,GAC3B;IACE,MAAM,EAAE,aAAa,CAAC;IACtB,UAAU,CAAC,EAAE,KAAK,CAAC;IACnB,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B,GACD;IACE,MAAM,CAAC,EAAE,KAAK,CAAC;IACf,UAAU,EAAE,eAAe,CAAC;IAC5B,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B,CAAC;AAyBN,eAAO,MAAM,kBAAkB,GAAI,SAAS,mBAAmB,MAG/C,UAAU,WAAW,sBAapC,CAAC"}

package/dist/llms-route.d.ts

@@ -0,0 +1,13 @@
+import type { NextRequest } from 'next/server.js';
+import type { LlmsTxtConfig, LlmsTxtProvider, LlmsTxtVariant } from "./llms.js";
+export type LlmsTxtRouteOptions = {
+    config: LlmsTxtConfig;
+    getLlmsTxt?: never;
+    variant?: LlmsTxtVariant;
+} | {
+    config?: never;
+    getLlmsTxt: LlmsTxtProvider;
+    variant?: LlmsTxtVariant;
+};
+export declare const createLlmsTxtRoute: (options: LlmsTxtRouteOptions) => (_request: NextRequest) => Promise<Response>;
+//# sourceMappingURL=llms-route.d.ts.map

package/dist/llms-route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llms-route.d.ts","sourceRoot":"","sources":["../src/llms-route.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,cAAc,EAAE,kBAAkB;AAEhF,MAAM,MAAM,mBAAmB,GAC3B;IACE,MAAM,EAAE,aAAa,CAAC;IACtB,UAAU,CAAC,EAAE,KAAK,CAAC;IACnB,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B,GACD;IACE,MAAM,CAAC,EAAE,KAAK,CAAC;IACf,UAAU,EAAE,eAAe,CAAC;IAC5B,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B,CAAC;AAyBN,eAAO,MAAM,kBAAkB,GAAI,SAAS,mBAAmB,MAG/C,UAAU,WAAW,sBAapC,CAAC"}

package/dist/llms-route.js

@@ -0,0 +1,33 @@
+import { renderLlmsTxt } from "./llms.js";
+const DEFAULT_HEADERS = {
+    'Content-Type': 'text/markdown; charset=utf-8',
+};
+const resolveConfig = (options, variant) => {
+    if ('config' in options && options.config) {
+        return options.config;
+    }
+    return options.getLlmsTxt(variant);
+};
+const handleError = (error) => {
+    console.error('[next-ai-discovery] llms.txt route error', error);
+    return new Response('Internal Server Error', {
+        status: 500,
+        headers: DEFAULT_HEADERS,
+    });
+};
+export const createLlmsTxtRoute = (options) => {
+    const variant = options.variant ?? 'default';
+    return async (_request) => {
+        try {
+            const config = await resolveConfig(options, variant);
+            const body = renderLlmsTxt(config, variant);
+            return new Response(body, {
+                status: 200,
+                headers: DEFAULT_HEADERS,
+            });
+        }
+        catch (error) {
+            return handleError(error);
+        }
+    };
+};

package/dist/llms.cjs

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderLlmsTxt = void 0;
+const formatSection = (section) => {
+    const lines = [`## ${section.title}`];
+    for (const item of section.items) {
+        lines.push(`- ${item}`);
+    }
+    return lines.join('\n');
+};
+const joinBlocks = (blocks) => blocks.filter(block => block.trim().length > 0).join('\n\n');
+const renderLlmsTxt = (config, variant) => {
+    const blocks = [`# ${config.site.name}`];
+    if (config.site.description) {
+        blocks.push(config.site.description);
+    }
+    if (config.sections && config.sections.length > 0) {
+        const rendered = config.sections.map(section => formatSection(section));
+        blocks.push(joinBlocks(rendered));
+    }
+    if (config.markdown) {
+        const markdownLines = ['## Machine-readable variants'];
+        if (config.markdown.appendDotMd ?? true) {
+            markdownLines.push('- Markdown pages: append `.md` to most URLs');
+        }
+        if (config.markdown.acceptNegotiation ?? true) {
+            markdownLines.push('- Negotiation: send `Accept: text/markdown`');
+        }
+        if (variant === 'default') {
+            const fullIndex = config.markdown.fullIndexPath ?? '/llms-full.txt';
+            markdownLines.push(`- Full index: ${fullIndex}`);
+        }
+        blocks.push(markdownLines.join('\n'));
+    }
+    if (config.site.url) {
+        blocks.push(`Site: ${config.site.url}`);
+    }
+    return joinBlocks(blocks);
+};
+exports.renderLlmsTxt = renderLlmsTxt;

package/dist/llms.d.cts

@@ -0,0 +1,20 @@
+export type LlmsTxtVariant = 'default' | 'full';
+export type LlmsTxtConfig = {
+    site: {
+        name: string;
+        description?: string;
+        url?: string;
+    };
+    sections?: Array<{
+        title: string;
+        items: Array<string>;
+    }>;
+    markdown?: {
+        appendDotMd?: boolean;
+        acceptNegotiation?: boolean;
+        fullIndexPath?: string;
+    };
+};
+export type LlmsTxtProvider = (variant: LlmsTxtVariant) => Promise<LlmsTxtConfig> | LlmsTxtConfig;
+export declare const renderLlmsTxt: (config: LlmsTxtConfig, variant: LlmsTxtVariant) => string;
+//# sourceMappingURL=llms.d.ts.map

package/dist/llms.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llms.d.ts","sourceRoot":"","sources":["../src/llms.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,MAAM,CAAC;AAEhD,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE;QACJ,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,GAAG,CAAC,EAAE,MAAM,CAAC;KACd,CAAC;IACF,QAAQ,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;KAAE,CAAC,CAAC;IAC1D,QAAQ,CAAC,EAAE;QACT,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,iBAAiB,CAAC,EAAE,OAAO,CAAC;QAC5B,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,CAC5B,OAAO,EAAE,cAAc,KACpB,OAAO,CAAC,aAAa,CAAC,GAAG,aAAa,CAAC;AAa5C,eAAO,MAAM,aAAa,GACxB,QAAQ,aAAa,EACrB,SAAS,cAAc,WAkCxB,CAAC"}

package/dist/llms.d.ts

@@ -0,0 +1,20 @@
+export type LlmsTxtVariant = 'default' | 'full';
+export type LlmsTxtConfig = {
+    site: {
+        name: string;
+        description?: string;
+        url?: string;
+    };
+    sections?: Array<{
+        title: string;
+        items: Array<string>;
+    }>;
+    markdown?: {
+        appendDotMd?: boolean;
+        acceptNegotiation?: boolean;
+        fullIndexPath?: string;
+    };
+};
+export type LlmsTxtProvider = (variant: LlmsTxtVariant) => Promise<LlmsTxtConfig> | LlmsTxtConfig;
+export declare const renderLlmsTxt: (config: LlmsTxtConfig, variant: LlmsTxtVariant) => string;
+//# sourceMappingURL=llms.d.ts.map

package/dist/llms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llms.d.ts","sourceRoot":"","sources":["../src/llms.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,MAAM,CAAC;AAEhD,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE;QACJ,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,GAAG,CAAC,EAAE,MAAM,CAAC;KACd,CAAC;IACF,QAAQ,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;KAAE,CAAC,CAAC;IAC1D,QAAQ,CAAC,EAAE;QACT,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,iBAAiB,CAAC,EAAE,OAAO,CAAC;QAC5B,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,CAC5B,OAAO,EAAE,cAAc,KACpB,OAAO,CAAC,aAAa,CAAC,GAAG,aAAa,CAAC;AAa5C,eAAO,MAAM,aAAa,GACxB,QAAQ,aAAa,EACrB,SAAS,cAAc,WAkCxB,CAAC"}

package/dist/llms.js

@@ -0,0 +1,36 @@
+const formatSection = (section) => {
+    const lines = [`## ${section.title}`];
+    for (const item of section.items) {
+        lines.push(`- ${item}`);
+    }
+    return lines.join('\n');
+};
+const joinBlocks = (blocks) => blocks.filter(block => block.trim().length > 0).join('\n\n');
+export const renderLlmsTxt = (config, variant) => {
+    const blocks = [`# ${config.site.name}`];
+    if (config.site.description) {
+        blocks.push(config.site.description);
+    }
+    if (config.sections && config.sections.length > 0) {
+        const rendered = config.sections.map(section => formatSection(section));
+        blocks.push(joinBlocks(rendered));
+    }
+    if (config.markdown) {
+        const markdownLines = ['## Machine-readable variants'];
+        if (config.markdown.appendDotMd ?? true) {
+            markdownLines.push('- Markdown pages: append `.md` to most URLs');
+        }
+        if (config.markdown.acceptNegotiation ?? true) {
+            markdownLines.push('- Negotiation: send `Accept: text/markdown`');
+        }
+        if (variant === 'default') {
+            const fullIndex = config.markdown.fullIndexPath ?? '/llms-full.txt';
+            markdownLines.push(`- Full index: ${fullIndex}`);
+        }
+        blocks.push(markdownLines.join('\n'));
+    }
+    if (config.site.url) {
+        blocks.push(`Site: ${config.site.url}`);
+    }
+    return joinBlocks(blocks);
+};

package/dist/markdown-route.cjs

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMarkdownRoute = void 0;
+const pathname_js_1 = require("./pathname.cjs");
+const DEFAULT_HEADERS = {
+    'Content-Type': 'text/markdown; charset=utf-8',
+    Vary: 'Accept',
+};
+const toFrontmatter = (frontmatter) => {
+    const lines = ['---'];
+    for (const [key, value] of Object.entries(frontmatter)) {
+        lines.push(`${key}: ${JSON.stringify(value)}`);
+    }
+    lines.push('---');
+    return lines.join('\n');
+};
+const buildBody = (content, includeFrontmatter) => {
+    if (!(includeFrontmatter && content.frontmatter)) {
+        return content.body;
+    }
+    return `${toFrontmatter(content.frontmatter)}\n\n${content.body}`;
+};
+const handleError = (error) => {
+    console.error('[next-ai-discovery] markdown route error', error);
+    return new Response('Internal Server Error', {
+        status: 500,
+        headers: DEFAULT_HEADERS,
+    });
+};
+const createMarkdownRoute = (options) => {
+    const includeFrontmatter = options.includeFrontmatter ?? true;
+    return async (request) => {
+        const url = new URL(request.url);
+        const rawPath = url.searchParams.get('path') ?? '/';
+        const pathname = (0, pathname_js_1.normalizePathname)(rawPath);
+        try {
+            const content = await options.getMarkdown(pathname, request);
+            const isHead = request.method === 'HEAD';
+            if (!content) {
+                options.onServed?.({ pathname, status: 404 });
+                return new Response(isHead ? null : 'Not Found', {
+                    status: 404,
+                    headers: DEFAULT_HEADERS,
+                });
+            }
+            const body = buildBody(content, includeFrontmatter);
+            options.onServed?.({ pathname, status: 200 });
+            return new Response(isHead ? null : body, {
+                status: 200,
+                headers: DEFAULT_HEADERS,
+            });
+        }
+        catch (error) {
+            options.onServed?.({ pathname, status: 500 });
+            return handleError(error);
+        }
+    };
+};
+exports.createMarkdownRoute = createMarkdownRoute;

package/dist/markdown-route.d.cts

@@ -0,0 +1,16 @@
+import type { NextRequest } from 'next/server.js';
+export type MarkdownContent = {
+    body: string;
+    frontmatter?: Record<string, unknown>;
+};
+export type GetMarkdown = (pathname: string, request: NextRequest) => Promise<MarkdownContent | null> | MarkdownContent | null;
+export type MarkdownRouteOptions = {
+    getMarkdown: GetMarkdown;
+    includeFrontmatter?: boolean;
+    onServed?: (event: {
+        pathname: string;
+        status: number;
+    }) => void;
+};
+export declare const createMarkdownRoute: (options: MarkdownRouteOptions) => (request: NextRequest) => Promise<Response>;
+//# sourceMappingURL=markdown-route.d.ts.map