@open-agent-toolkit/docs-config 0.3.26 → 0.3.27

package/README.md

@@ -51,10 +51,19 @@ export default defineConfig({
 
 The `docs` and `meta` options apply shared `documentation.nonReaderPaths` only when the explicit repo config's documentation root matches this app. Patterns follow OAT's bounded content-root-relative grammar: `*` within a segment, whole-segment `**` across directories, trailing `/` for directories, all other characters literal. Excluded directories omit descendants and metadata. `documentation.excludes` remains manifest-only. No ancestor config search occurs; scaffolded apps receive their resolved relative config path.
 
+Link rewriting uses the explicit app root's `docs` directory (or `./docs` from the working directory when omitted) and discovers readers with the same collection patterns and tinyglobby engine. Both source and target index collisions follow filtered reader membership, including `.mdx` readers. The inventory refreshes lazily for each transformed document, so adding or removing a reader does not require rebuilding the source configuration. OAT adds no error fallback; traversal follows the emitter's tinyglobby semantics, including skipped unreadable directories.
+
 The metadata schema preserves Fumadocs fields and accepts boolean roots and nonempty trimmed string inputs. String inputs normalize to `true` for the pinned generated collection types; authored metadata files remain unchanged. Booleans, including `false`, retain their values. Use both source options so collection validation and rendering agree with navigation. The scaffold pins MkDocs 1.4.2 separately; that version has no configurable rendering exclusion, so its non-readers leave nav/manifest but still render as routes.
 
+## Agent Markdown endpoints
+
+Import `createLlmsRoutes` from `@open-agent-toolkit/docs-config/llms` in runtime route/source files; this narrow entry avoids bundling Next/MDX build configuration. `createLlmsRoutes(source, { basePath })` accepts the real Fumadocs loader with MDX `getText('raw')` methods. Keep the loader's `baseUrl: '/'` and pass the same optional basePath as Next. It exposes `index()`, `full()`, `page(slug)` and `generateStaticParams()` for the scaffold's static route handlers: `/llms.txt`, `/llms-full.txt`, and `/llms/[...slug]` with the terminal `content.md` segment. The root page is `/llms/content.md`; a nested guide is `/llms/guide/content.md`. No rewrites or server are needed.
+
+All endpoints enumerate the same loaded `.md` pages, including readers omitted from a hand-authored sidebar; collection-level `nonReaderPaths` filtering still applies. MDX stays outside these endpoints and the OAT manifest. Bodies retain authored frontmatter and Markdown; relative links describe source paths rather than the endpoint directory. The agent header and each entry identify the source, canonical rendered URL (with trailing slash) and Markdown URL. Base paths are added once. Missing pages return 404 in the handler and have no exported file. The helper uses pinned core 16.10.2 loader and MDX 14.3.2 raw-source APIs; newer upstream `page`/`full` llms helpers are not assumed.
+
 ## Exports
 
+- `createLlmsRoutes`
 - `createDocsConfig`
 - `createSearchConfig`
 - `createSourceConfig`

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export { createLlmsRoutes, type LlmsOptions } from './llms.js';
 export { createDocsConfig } from './next-config.js';
 export { createSearchConfig } from './search-config.js';
 export { createSourceConfig } from './source-config.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -1,3 +1,4 @@
+export { createLlmsRoutes } from './llms.js';
 export { createDocsConfig } from './next-config.js';
 export { createSearchConfig } from './search-config.js';
 export { createSourceConfig } from './source-config.js';

package/dist/llms.d.ts

@@ -0,0 +1,29 @@
+/** The subset of pinned Fumadocs loader/MDX page data needed for raw Markdown. */
+interface MarkdownPage {
+    path: string;
+    url: string;
+    slugs: string[];
+    data: {
+        title?: string;
+        description?: string;
+        getText: (type: 'raw') => Promise<string>;
+    };
+}
+export interface LlmsOptions {
+    /** Same basePath passed to createDocsConfig; source.baseUrl stays '/'. */
+    basePath?: string;
+}
+interface LlmsRoutes {
+    index: () => Response;
+    full: () => Promise<Response>;
+    page: (slug: string[]) => Promise<Response>;
+    generateStaticParams: () => {
+        slug: string[];
+    }[];
+}
+/** Static-export handlers over one loaded reader-page set, independent of sidebar. */
+export declare function createLlmsRoutes(source: {
+    getPages: () => MarkdownPage[];
+}, options?: LlmsOptions): LlmsRoutes;
+export {};
+//# 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,kFAAkF;AAClF,UAAU,YAAY;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,IAAI,EAAE;QACJ,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,OAAO,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;KAC3C,CAAC;CACH;AAED,MAAM,WAAW,WAAW;IAC1B,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,UAAU;IAClB,KAAK,EAAE,MAAM,QAAQ,CAAC;IACtB,IAAI,EAAE,MAAM,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC9B,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC5C,oBAAoB,EAAE,MAAM;QAAE,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAC;CAClD;AAED,sFAAsF;AACtF,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,YAAY,EAAE,CAAA;CAAE,EAC1C,OAAO,GAAE,WAAgB,GACxB,UAAU,CA+DZ"}

package/dist/llms.js

@@ -0,0 +1,50 @@
+/** Static-export handlers over one loaded reader-page set, independent of sidebar. */
+export function createLlmsRoutes(source, options = {}) {
+    const base = (options.basePath ?? '').replace(/\/$/, '');
+    const pages = source.getPages().filter((page) => page.path.endsWith('.md'));
+    const withBase = (path) => (base ? `${base}${path}` : path);
+    const renderedUrl = (page) => withBase(`${page.url.replace(/\/$/, '')}/`);
+    const markdownUrl = (page) => withBase(`/llms/${[...page.slugs, 'content.md'].join('/')}`);
+    const header = [
+        '# Documentation for agents',
+        '',
+        'Use canonical pages for the documented behavior and follow each local Contents map.',
+        'Check repository AGENTS.md and contributing guidance for authority, deprecated paths and approval-required actions. Documentation does not grant permission to act.',
+        'Markdown below is authored source. Resolve relative links against its Source path, not the /llms/ URL; use the rendered URL for browser navigation.',
+        'These endpoints include loaded reader .md pages, including pages outside the sidebar. MDX and configured non-reader pages are excluded.',
+    ].join('\n');
+    const entry = (page) => [
+        `## ${page.data.title ?? page.path}`,
+        ...(page.data.description ? ['', page.data.description] : []),
+        '',
+        `Rendered: ${renderedUrl(page)}`,
+        `Markdown: ${markdownUrl(page)}`,
+        `Source: ${page.path}`,
+    ].join('\n');
+    const text = (body, markdown = false, status = 200) => new Response(body, {
+        status,
+        headers: {
+            'Content-Type': `${markdown ? 'text/markdown' : 'text/plain'}; charset=utf-8`,
+        },
+    });
+    return {
+        index: () => text(`${header}\n\n${pages.map(entry).join('\n\n')}\n`),
+        full: async () => text(`${header}\n\n${(await Promise.all(pages.map(async (page) => `${entry(page)}\n\n${await page.data.getText('raw')}`))).join('\n\n')}\n`, true),
+        page: async (slug) => {
+            if (slug.at(-1) !== 'content.md')
+                return text('Not found\n', false, 404);
+            const slugs = slug.slice(0, -1);
+            const page = pages.find((candidate) => candidate.slugs.length === slugs.length &&
+                candidate.slugs.every((value, index) => decodeURI(value) === slugs[index]));
+            if (!page)
+                return text('Not found\n', false, 404);
+            return text(`${header}\n\n${entry(page)}\n\n${await page.data.getText('raw')}`, true);
+        },
+        generateStaticParams: () => 
+        // The pinned loader encodes slugs; Next encodes static params and
+        // supplies decoded route params, so cross that boundary exactly once.
+        pages.map((page) => ({
+            slug: [...page.slugs.map(decodeURI), 'content.md'],
+        })),
+    };
+}

package/dist/source-config.d.ts

@@ -1,7 +1,5 @@
-import type { Root } from 'mdast';
-import type { Plugin } from 'unified';
+import type { PluggableList } from 'unified';
 import { type SearchConfig } from './search-config.js';
-type RemarkPlugin = Plugin<any[], Root>;
 declare const docsMetaSchema: import("zod").ZodObject<{
     title: import("zod").ZodOptional<import("zod").ZodString>;
     pages: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
@@ -19,7 +17,7 @@ export interface SourceConfigOptions {
     appRoot?: string | URL;
 }
 export interface SourceConfigResult {
-    remarkPlugins: RemarkPlugin[];
+    remarkPlugins: PluggableList;
     contentDir: string;
     search: SearchConfig;
     docs: {

package/dist/source-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"source-config.d.ts","sourceRoot":"","sources":["../src/source-config.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC;AAElC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAGtC,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAG3E,KAAK,YAAY,GAAG,MAAM,CAAC,GAAG,EAAE,EAAE,IAAI,CAAC,CAAC;AAIxC,QAAA,MAAM,cAAc;;;;;;;;;gCAWlB,CAAC;AAEH,MAAM,WAAW,mBAAmB;IAClC,yEAAyE;IACzE,aAAa,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC;IAC7B,mFAAmF;IACnF,OAAO,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,aAAa,EAAE,YAAY,EAAE,CAAC;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,YAAY,CAAC;IACrB,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAC1B,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,MAAM,EAAE,OAAO,cAAc,CAAA;KAAE,CAAC;CAC1D;AAuCD,wBAAgB,kBAAkB,CAChC,OAAO,GAAE,mBAAwB,GAChC,kBAAkB,CAYpB"}
+{"version":3,"file":"source-config.d.ts","sourceRoot":"","sources":["../src/source-config.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAG7C,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAI3E,QAAA,MAAM,cAAc;;;;;;;;;gCAWlB,CAAC;AAEH,MAAM,WAAW,mBAAmB;IAClC,yEAAyE;IACzE,aAAa,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC;IAC7B,mFAAmF;IACnF,OAAO,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,aAAa,EAAE,aAAa,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,YAAY,CAAC;IACrB,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAC1B,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,MAAM,EAAE,OAAO,cAAc,CAAA;KAAE,CAAC;CAC1D;AAuCD,wBAAgB,kBAAkB,CAChC,OAAO,GAAE,mBAAwB,GAChC,kBAAkB,CA6BpB"}

package/dist/source-config.js

@@ -4,6 +4,7 @@ import { fileURLToPath } from 'node:url';
 import { remarkLinks, remarkMermaid, remarkTabs, } from '@open-agent-toolkit/docs-transforms';
 import { metaSchema } from 'fumadocs-core/source/schema';
 import { remarkAlert } from 'remark-github-blockquote-alert';
+import { globSync } from 'tinyglobby';
 import { collectionFiles } from './reader-paths.js';
 import { createSearchConfig } from './search-config.js';
 // Accept named-root inputs while keeping output compatible with fumadocs-mdx
@@ -50,11 +51,27 @@ function nonReaderPaths(options) {
 }
 export function createSourceConfig(options = {}) {
     const patterns = nonReaderPaths(options);
+    const files = collectionFiles(patterns, ['md', 'mdx']);
+    const appRoot = options.appRoot instanceof URL
+        ? fileURLToPath(options.appRoot)
+        : (options.appRoot ?? '.');
+    const contentRoot = resolve(appRoot, 'docs');
     return {
-        remarkPlugins: [remarkLinks, remarkTabs, remarkAlert, remarkMermaid],
+        remarkPlugins: [
+            remarkTabs,
+            [
+                remarkLinks,
+                {
+                    contentRoot,
+                    getReaderFiles: () => globSync(files, { cwd: contentRoot }),
+                },
+            ],
+            remarkAlert,
+            remarkMermaid,
+        ],
         contentDir: './docs',
         search: createSearchConfig(),
-        docs: { files: collectionFiles(patterns, ['md', 'mdx']) },
+        docs: { files },
         meta: {
             files: collectionFiles(patterns, ['json', 'yaml']),
             schema: docsMetaSchema,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/docs-config",
-  "version": "0.3.26",
+  "version": "0.3.27",
   "private": false,
   "description": "Configuration factories for OAT documentation sites",
   "homepage": "https://github.com/voxmedia/open-agent-toolkit/tree/main/packages/docs-config",
@@ -24,6 +24,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./llms": {
+      "types": "./dist/llms.d.ts",
+      "import": "./dist/llms.js"
     }
   },
   "publishConfig": {
@@ -32,9 +36,10 @@
   "dependencies": {
     "flexsearch": "^0.8.212",
     "remark-github-blockquote-alert": "^2.0.1",
+    "tinyglobby": "^0.2.17",
     "unified": "^11.0.5",
     "zod": "^4.3.6",
-    "@open-agent-toolkit/docs-transforms": "0.3.26"
+    "@open-agent-toolkit/docs-transforms": "0.3.27"
   },
   "devDependencies": {
     "@types/mdast": "^4.0.4",
@@ -44,6 +49,7 @@
     "next": "^16.1.6",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
+    "remark-parse": "^11.0.0",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
     "typescript-7": "npm:typescript@^7.0.2",
     "vitest": "^4.0.18"