@blaaiz/docs-core 0.5.0 → 0.7.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { A as AiConfig, T as ThemeConfig, D as DocsConfig, N as Navigation } from './navigation-CGqFIPlP.cjs';
-export { a as AI_PROVIDER_MODELS, b as AI_PROVIDER_NAMES, c as AiConfigError, d as AiProviderModels, e as AiProviderName, f as AuthConfig, g as DocPage, h as DocsConfigError, F as FeaturesConfig, G as GoogleProviderConfig, i as NavGroup, j as NavItem, k as NavMethod, l as NavPage, m as NavTab, O as OpenApiPage, P as ProxyConfig, R as ResolvedAiConfig, S as SecretProviderConfig, n as SeoConfig, o as ThemeLogo, p as ThemePalette, W as WorkspaceAuthConfig, q as WorkspaceProviders, r as defineDocsConfig, s as resolveAiConfig, v as validateDocsConfig } from './navigation-CGqFIPlP.cjs';
+import { A as AiConfig, T as ThemeConfig, D as DocsConfig, N as Navigation } from './navigation-DvgyWSZ4.cjs';
+export { a as AI_PROVIDER_MODELS, b as AI_PROVIDER_NAMES, c as AiConfigError, d as AiProviderModels, e as AiProviderName, f as AuthConfig, g as DocPage, h as DocsConfigError, F as FeaturesConfig, G as GoogleProviderConfig, i as NavGroup, j as NavItem, k as NavMethod, l as NavPage, m as NavTab, O as OpenApiPage, P as ProxyConfig, R as ResolvedAiConfig, S as SecretProviderConfig, n as SeoConfig, o as ThemeLogo, p as ThemePalette, W as WorkspaceAuthConfig, q as WorkspaceProviders, r as defineDocsConfig, s as resolveAiConfig, v as validateDocsConfig } from './navigation-DvgyWSZ4.cjs';
 import { b as OpenApiDocument, O as OpenApiInfo, a as OpenApiServer } from './openapi-types-CJ6p5Cux.cjs';
 export { c as OpenApiComponents, d as OpenApiOperation, e as OpenApiPathItem, f as OpenApiTag } from './openapi-types-CJ6p5Cux.cjs';
 
@@ -275,7 +275,9 @@ declare function searchIndex(index: SearchIndex, query: string, limit?: number):
  * - **Configuration is resolved eagerly.** {@link createAskAiRoute} validates
  *   the `ai` block when the route is built, so a typo in `docs.config.ts` fails
  *   the build. Deferring it to the first request would turn a site's typo into a
- *   reader's error message.
+ *   reader's error message. A site with no `ai` block at all is different from
+ *   a typo: the route mounts dormant and answers `404`, so a scaffold ships the
+ *   file and enabling Ask AI is a config change, not a code change.
  * - **The API key is read lazily, per request.** An edge runtime binds its
  *   environment per invocation, not at module load, so the key is looked up when
  *   it is needed. It is never logged; a missing key is reported by env var name.
@@ -301,8 +303,12 @@ type AskAiDocumentsSource = readonly SearchDocument[] | (() => Promise<readonly
  * @public
  */
 interface AskAiRouteOptions {
-    /** The site's raw `ai` block. Validated when the route is built. */
-    readonly config: AiConfig;
+    /**
+     * The site's raw `ai` block. Validated when the route is built. `undefined`
+     * (the config declares no `ai` block) mounts the route dormant: every
+     * request answers `404`.
+     */
+    readonly config: AiConfig | undefined;
     /** Display name used in the system prompt, normally `theme.name`. */
     readonly siteName: string;
     /**
@@ -397,6 +403,152 @@ declare function createAskAiRoute(options: AskAiRouteOptions): AskAiRoute;
  */
 declare function buildThemeCss(theme: ThemeConfig): string;
 
+/**
+ * Permanent redirects for renamed pages. The generator writes
+ * `content/redirects.json` (old page URL to current) whenever an operation's
+ * URL changes; the site's middleware serves `308`s from it, so an edited
+ * summary is a rename with a forwarding address, never a dead link.
+ *
+ * @packageDocumentation
+ */
+/**
+ * The URL a renamed page's request should be redirected to, or `null` when
+ * the request matches no entry. The `.md` form of a renamed page redirects to
+ * the `.md` form of its new address.
+ *
+ * @example
+ * ```ts
+ * const redirected = redirectTarget(request.nextUrl, redirects);
+ * if (redirected) {
+ *   return NextResponse.redirect(redirected, 308);
+ * }
+ * ```
+ *
+ * @param url - the request URL
+ * @param redirects - the parsed `content/redirects.json`
+ * @returns the redirect target, or `null`
+ * @public
+ */
+declare function redirectTarget(url: URL, redirects: Readonly<Record<string, string>>): URL | null;
+
+/**
+ * The site's `/llms.txt`: a Markdown index of every page, the entry point
+ * agents fetch first. Each entry links the page's `.md` address.
+ *
+ * @packageDocumentation
+ */
+/**
+ * One page of the documentation index.
+ *
+ * @public
+ */
+interface LlmsTxtPage {
+    readonly title: string;
+    /** The page URL (e.g. `/docs/guides/webhooks`); `.md` is appended. */
+    readonly url: string;
+    readonly description?: string;
+}
+/**
+ * Options for {@link buildLlmsTxt}.
+ *
+ * @public
+ */
+interface BuildLlmsTxtOptions {
+    /** The site name, the index's `#` heading. */
+    readonly name: string;
+    /** One sentence on what the site documents. */
+    readonly description?: string;
+    /** Absolute origin to prefix every link with (e.g. `https://docs.example.com`). */
+    readonly origin?: string;
+}
+/**
+ * Build the `/llms.txt` document from the site's pages.
+ *
+ * @example
+ * ```ts
+ * // app/llms.txt/route.ts
+ * export function GET() {
+ *   const body = buildLlmsTxt(pages, { name: config.theme.name });
+ *   return new Response(body, { headers: { 'content-type': 'text/plain; charset=utf-8' } });
+ * }
+ * ```
+ *
+ * @param pages - the site's pages, in navigation order
+ * @param options - the site name, description, and link origin
+ * @returns the document text
+ * @public
+ */
+declare function buildLlmsTxt(pages: readonly LlmsTxtPage[], options: BuildLlmsTxtOptions): string;
+
+/**
+ * Code-sample generators for the API reference's usage panel.
+ *
+ * `fumadocs-openapi` renders one sample per registered generator; a site
+ * replaces a built-in one by adding a generator under the same id. The shapes
+ * here are structural, so this module needs no fumadocs types.
+ *
+ * @packageDocumentation
+ */
+/**
+ * One resolved request parameter, as the usage panel passes it.
+ *
+ * @public
+ */
+interface CodeUsageValue {
+    /** The parameter's example value. */
+    readonly value: string;
+}
+/**
+ * The resolved example request a code-sample generator receives.
+ *
+ * @public
+ */
+interface CodeUsageRequest {
+    /** The HTTP method. */
+    readonly method: string;
+    /** The full request URL, path and query resolved. */
+    readonly url: string;
+    /** Header name to example value. */
+    readonly header?: Readonly<Record<string, CodeUsageValue>>;
+    /** Cookie name to example value. */
+    readonly cookie?: Readonly<Record<string, CodeUsageValue>>;
+    /** The example request body, when the operation takes one. */
+    readonly body?: unknown;
+    /** The body's media type, when the operation takes a body. */
+    readonly bodyMediaType?: string;
+}
+/**
+ * A code-sample generator, shaped for fumadocs-openapi's code-usage registry.
+ *
+ * @public
+ */
+interface CodeUsageGenerator {
+    /** The tab label readers see. */
+    readonly label: string;
+    /** The sample's syntax-highlighting language. */
+    readonly lang: string;
+    /** Render the sample for one resolved example request. */
+    generate(data: CodeUsageRequest): string;
+}
+/**
+ * A cURL sample in long-form flags: `--request`, `--url`, `--header`,
+ * `--data`. Register it over the built-in `curl` entry:
+ *
+ * @example
+ * ```ts
+ * import { curlCodeUsage } from '@blaaiz/docs-core';
+ * import { createCodeUsageGeneratorRegistry } from 'fumadocs-openapi/requests/generators';
+ * import { registerDefault } from 'fumadocs-openapi/requests/generators/all';
+ *
+ * const codeUsages = registerDefault(createCodeUsageGeneratorRegistry());
+ * codeUsages.add('curl', curlCodeUsage);
+ * createOpenAPI({ input, codeUsages });
+ * ```
+ *
+ * @public
+ */
+declare const curlCodeUsage: CodeUsageGenerator;
+
 /**
  * SEO metadata, derived from {@link DocsConfig}.
  *
@@ -628,6 +780,8 @@ interface PlannedGroupChild {
     readonly order: number;
     /** The child folder's name within the group directory. */
     readonly folder: string;
+    /** The child group's title, for the heading the `headings` style renders. */
+    readonly title: string;
 }
 /**
  * A planned API group folder. The generator fills its page order once the
@@ -688,6 +842,17 @@ interface DocsTreePlan {
      */
     readonly apiDocLinks: readonly PlannedApiDocLink[];
 }
+/**
+ * How the sidebar presents a tab's top-level groups.
+ *
+ * - `collapsible`: every group is a collapsible folder (the fumadocs default).
+ * - `headings`: a top-level group is a flat, always-open section heading with
+ *   its pages listed beneath it; only nested groups collapse, and they start
+ *   closed. The Mintlify presentation.
+ *
+ * @public
+ */
+type SidebarStyle = 'collapsible' | 'headings';
 /**
  * Options for {@link planDocsTree}.
  *
@@ -696,6 +861,8 @@ interface DocsTreePlan {
 interface PlanDocsTreeOptions {
     /** Folder for generated API pages when one tab publishes them. Default `api`. */
     readonly apiDir?: string;
+    /** The sidebar's group presentation. Default `collapsible`. */
+    readonly sidebar?: SidebarStyle;
 }
 /**
  * Plan the content tree for a navigation.
@@ -710,9 +877,11 @@ interface PlanDocsTreeOptions {
  * - Root-level doc pages (no `/` in the path) are listed in the root meta.
  * - Tab folders get `root: true`, so the sidebar scopes to the active tab.
  * - Sidebar order is declaration order, pages and groups interleaved.
+ * - With `sidebar: 'headings'`, a tab-level group renders as a flat heading
+ *   with its pages extracted beneath it, and nested groups start closed.
  *
  * @param navigation - the parsed navigation
- * @param options - the API folder name
+ * @param options - the API folder name and the sidebar style
  * @returns the plan the generator executes
  * @throws when two sibling groups slugify to the same folder
  * @public
@@ -799,6 +968,38 @@ interface CreateMarkdownRouteOptions {
      * when the document is expensive to build.
      */
     readonly loadOpenApiDocuments?: () => Readonly<Record<string, OpenApiDocument>> | Promise<Readonly<Record<string, OpenApiDocument>>>;
+    /**
+     * Loads a generated API page's original operation source: the spec file
+     * path, the method and route, and the file's raw contents. When it returns
+     * one, the page's Markdown is the operation spec in full under an
+     * `## OpenAPI` heading, the shape agents get from the major docs platforms;
+     * pages it returns `null` for fall through to the MDX conversion. Wire it
+     * from the generator's `api-sources.json`.
+     */
+    readonly loadOperationSource?: (slug: readonly string[] | undefined) => Promise<OperationSource | null>;
+    /**
+     * The site's documentation index path (`/llms.txt`). When set, every
+     * response opens with a blockquote pointing agents at it, on the origin the
+     * request came in on — correct on localhost, a preview deploy, and
+     * production alike.
+     */
+    readonly llmsTxtPath?: string;
+}
+/**
+ * A generated API page's original operation source, as
+ * {@link CreateMarkdownRouteOptions.loadOperationSource} returns it.
+ *
+ * @public
+ */
+interface OperationSource {
+    /** The spec file, relative to the content directory. */
+    readonly file: string;
+    /** The operation's HTTP method. */
+    readonly method: string;
+    /** The operation's API route. */
+    readonly route: string;
+    /** The spec file's raw contents. */
+    readonly source: string;
 }
 /**
  * Build a drop-in route that serves a page as plain Markdown. It reads the raw
@@ -816,6 +1017,56 @@ interface CreateMarkdownRouteOptions {
  * @public
  */
 declare function createMarkdownRoute(options: CreateMarkdownRouteOptions): MarkdownRoute;
+/**
+ * Options for {@link markdownRewriteTarget}.
+ *
+ * @public
+ */
+interface MarkdownRewriteOptions {
+    /** The docs base URL. Default `/docs`. */
+    readonly baseUrl?: string;
+    /** Where the Markdown route is mounted. Default `/md`. */
+    readonly markdownBase?: string;
+}
+/**
+ * The internal URL serving a docs page's Markdown, for a request whose path is
+ * the page URL plus `.md` — the convention agents and other tools expect
+ * (`/docs/guides/webhooks.md`). Returns `null` for every other request. A
+ * site's middleware rewrites to the returned URL:
+ *
+ * @example
+ * ```ts
+ * const markdown = markdownRewriteTarget(request.nextUrl);
+ * if (markdown) {
+ *   return NextResponse.rewrite(markdown);
+ * }
+ * ```
+ *
+ * @param url - the request URL
+ * @param options - the docs base and the Markdown route's mount point
+ * @returns the rewrite target, or `null` when the request is not a `.md` path
+ * @public
+ */
+declare function markdownRewriteTarget(url: URL, options?: MarkdownRewriteOptions): URL | null;
+/**
+ * Whether a request addresses the Markdown route's internal mount directly.
+ * The route exists as the rewrite target for the page-URL-plus-`.md`
+ * convention; a direct request to it gets `404` from the site's middleware,
+ * so every page's Markdown has one public address.
+ *
+ * @example
+ * ```ts
+ * if (isMarkdownRouteRequest(request.nextUrl)) {
+ *   return new NextResponse('Not found', { status: 404 });
+ * }
+ * ```
+ *
+ * @param url - the request URL
+ * @param options - the Markdown route's mount point
+ * @returns whether the request must be refused
+ * @public
+ */
+declare function isMarkdownRouteRequest(url: URL, options?: Pick<MarkdownRewriteOptions, 'markdownBase'>): boolean;
 
 /**
  * Allowed-domain checks.
@@ -1294,4 +1545,4 @@ declare class OpenApiMergeError extends Error {
  */
 declare function mergeOpenApiDocuments(inputs: readonly unknown[], options: MergeOpenApiOptions): OpenApiDocument;
 
-export { AiConfig, type AiMessage, type AskAiDocumentsSource, type AskAiRoute, type AskAiRouteOptions, type AskAiSource, type AuthGateOptions, type BuildSitemapOptions, type CreateMarkdownRouteOptions, type CreateTryItProxyOptions, DocsConfig, type DocsMetadata, type DocsRobots, type DocsSitemapEntry, type DocsTreePlan, type EmailSignInOptions, type FetchLike, type GoogleAuthHandlers, type GoogleAuthOptions, type IndexedDocument, InvalidNavigationError, type MarkdownRoute, type MdxReader, type MdxToMarkdownOptions, type MergeOpenApiOptions, Navigation, OpenApiDocument, OpenApiInfo, OpenApiMergeError, type OpenApiOperationRef, OpenApiServer, type PageSeo, type PlanDocsTreeOptions, type PlannedApiDocLink, type PlannedApiGroup, type PlannedApiPage, type PlannedGroupChild, type PlannedMeta, ProxyTargetError, SESSION_COOKIE, type SearchDocument, type SearchIndex, type SearchResult, type SecretSignInOptions, type SessionPayload, type SignOutOptions, type SiteAuth, type SiteAuthOptions, type SitemapChangeFrequency, type SitemapEntry, ThemeConfig, type TryItEnvelope, type TryItProxyRoute, assertAllowedTarget, buildMetadata, buildRobots, buildSearchIndex, buildSessionCookie, buildSitemap, buildThemeCss, clearSessionCookie, createAskAiRoute, createAuthGate, createEmailSignIn, createGoogleAuth, createMarkdownRoute, createSecretSignIn, createSignOut, createSiteAuth, createTryItProxy, createTryItProxyRoute, isAllowedEmail, mdxToMarkdown, mergeOpenApiDocuments, openApiOperationToMarkdown, parseNavigation, planDocsTree, readCookie, searchIndex, signSession, unwrapProxyTarget, verifySession };
+export { AiConfig, type AiMessage, type AskAiDocumentsSource, type AskAiRoute, type AskAiRouteOptions, type AskAiSource, type AuthGateOptions, type BuildLlmsTxtOptions, type BuildSitemapOptions, type CodeUsageGenerator, type CodeUsageRequest, type CodeUsageValue, type CreateMarkdownRouteOptions, type CreateTryItProxyOptions, DocsConfig, type DocsMetadata, type DocsRobots, type DocsSitemapEntry, type DocsTreePlan, type EmailSignInOptions, type FetchLike, type GoogleAuthHandlers, type GoogleAuthOptions, type IndexedDocument, InvalidNavigationError, type LlmsTxtPage, type MarkdownRewriteOptions, type MarkdownRoute, type MdxReader, type MdxToMarkdownOptions, type MergeOpenApiOptions, Navigation, OpenApiDocument, OpenApiInfo, OpenApiMergeError, type OpenApiOperationRef, OpenApiServer, type OperationSource, type PageSeo, type PlanDocsTreeOptions, type PlannedApiDocLink, type PlannedApiGroup, type PlannedApiPage, type PlannedGroupChild, type PlannedMeta, ProxyTargetError, SESSION_COOKIE, type SearchDocument, type SearchIndex, type SearchResult, type SecretSignInOptions, type SessionPayload, type SignOutOptions, type SiteAuth, type SiteAuthOptions, type SitemapChangeFrequency, type SitemapEntry, ThemeConfig, type TryItEnvelope, type TryItProxyRoute, assertAllowedTarget, buildLlmsTxt, buildMetadata, buildRobots, buildSearchIndex, buildSessionCookie, buildSitemap, buildThemeCss, clearSessionCookie, createAskAiRoute, createAuthGate, createEmailSignIn, createGoogleAuth, createMarkdownRoute, createSecretSignIn, createSignOut, createSiteAuth, createTryItProxy, createTryItProxyRoute, curlCodeUsage, isAllowedEmail, isMarkdownRouteRequest, markdownRewriteTarget, mdxToMarkdown, mergeOpenApiDocuments, openApiOperationToMarkdown, parseNavigation, planDocsTree, readCookie, redirectTarget, searchIndex, signSession, unwrapProxyTarget, verifySession };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { A as AiConfig, T as ThemeConfig, D as DocsConfig, N as Navigation } from './navigation-CGqFIPlP.js';
-export { a as AI_PROVIDER_MODELS, b as AI_PROVIDER_NAMES, c as AiConfigError, d as AiProviderModels, e as AiProviderName, f as AuthConfig, g as DocPage, h as DocsConfigError, F as FeaturesConfig, G as GoogleProviderConfig, i as NavGroup, j as NavItem, k as NavMethod, l as NavPage, m as NavTab, O as OpenApiPage, P as ProxyConfig, R as ResolvedAiConfig, S as SecretProviderConfig, n as SeoConfig, o as ThemeLogo, p as ThemePalette, W as WorkspaceAuthConfig, q as WorkspaceProviders, r as defineDocsConfig, s as resolveAiConfig, v as validateDocsConfig } from './navigation-CGqFIPlP.js';
+import { A as AiConfig, T as ThemeConfig, D as DocsConfig, N as Navigation } from './navigation-DvgyWSZ4.js';
+export { a as AI_PROVIDER_MODELS, b as AI_PROVIDER_NAMES, c as AiConfigError, d as AiProviderModels, e as AiProviderName, f as AuthConfig, g as DocPage, h as DocsConfigError, F as FeaturesConfig, G as GoogleProviderConfig, i as NavGroup, j as NavItem, k as NavMethod, l as NavPage, m as NavTab, O as OpenApiPage, P as ProxyConfig, R as ResolvedAiConfig, S as SecretProviderConfig, n as SeoConfig, o as ThemeLogo, p as ThemePalette, W as WorkspaceAuthConfig, q as WorkspaceProviders, r as defineDocsConfig, s as resolveAiConfig, v as validateDocsConfig } from './navigation-DvgyWSZ4.js';
 import { b as OpenApiDocument, O as OpenApiInfo, a as OpenApiServer } from './openapi-types-CJ6p5Cux.js';
 export { c as OpenApiComponents, d as OpenApiOperation, e as OpenApiPathItem, f as OpenApiTag } from './openapi-types-CJ6p5Cux.js';
 
@@ -275,7 +275,9 @@ declare function searchIndex(index: SearchIndex, query: string, limit?: number):
  * - **Configuration is resolved eagerly.** {@link createAskAiRoute} validates
  *   the `ai` block when the route is built, so a typo in `docs.config.ts` fails
  *   the build. Deferring it to the first request would turn a site's typo into a
- *   reader's error message.
+ *   reader's error message. A site with no `ai` block at all is different from
+ *   a typo: the route mounts dormant and answers `404`, so a scaffold ships the
+ *   file and enabling Ask AI is a config change, not a code change.
  * - **The API key is read lazily, per request.** An edge runtime binds its
  *   environment per invocation, not at module load, so the key is looked up when
  *   it is needed. It is never logged; a missing key is reported by env var name.
@@ -301,8 +303,12 @@ type AskAiDocumentsSource = readonly SearchDocument[] | (() => Promise<readonly
  * @public
  */
 interface AskAiRouteOptions {
-    /** The site's raw `ai` block. Validated when the route is built. */
-    readonly config: AiConfig;
+    /**
+     * The site's raw `ai` block. Validated when the route is built. `undefined`
+     * (the config declares no `ai` block) mounts the route dormant: every
+     * request answers `404`.
+     */
+    readonly config: AiConfig | undefined;
     /** Display name used in the system prompt, normally `theme.name`. */
     readonly siteName: string;
     /**
@@ -397,6 +403,152 @@ declare function createAskAiRoute(options: AskAiRouteOptions): AskAiRoute;
  */
 declare function buildThemeCss(theme: ThemeConfig): string;
 
+/**
+ * Permanent redirects for renamed pages. The generator writes
+ * `content/redirects.json` (old page URL to current) whenever an operation's
+ * URL changes; the site's middleware serves `308`s from it, so an edited
+ * summary is a rename with a forwarding address, never a dead link.
+ *
+ * @packageDocumentation
+ */
+/**
+ * The URL a renamed page's request should be redirected to, or `null` when
+ * the request matches no entry. The `.md` form of a renamed page redirects to
+ * the `.md` form of its new address.
+ *
+ * @example
+ * ```ts
+ * const redirected = redirectTarget(request.nextUrl, redirects);
+ * if (redirected) {
+ *   return NextResponse.redirect(redirected, 308);
+ * }
+ * ```
+ *
+ * @param url - the request URL
+ * @param redirects - the parsed `content/redirects.json`
+ * @returns the redirect target, or `null`
+ * @public
+ */
+declare function redirectTarget(url: URL, redirects: Readonly<Record<string, string>>): URL | null;
+
+/**
+ * The site's `/llms.txt`: a Markdown index of every page, the entry point
+ * agents fetch first. Each entry links the page's `.md` address.
+ *
+ * @packageDocumentation
+ */
+/**
+ * One page of the documentation index.
+ *
+ * @public
+ */
+interface LlmsTxtPage {
+    readonly title: string;
+    /** The page URL (e.g. `/docs/guides/webhooks`); `.md` is appended. */
+    readonly url: string;
+    readonly description?: string;
+}
+/**
+ * Options for {@link buildLlmsTxt}.
+ *
+ * @public
+ */
+interface BuildLlmsTxtOptions {
+    /** The site name, the index's `#` heading. */
+    readonly name: string;
+    /** One sentence on what the site documents. */
+    readonly description?: string;
+    /** Absolute origin to prefix every link with (e.g. `https://docs.example.com`). */
+    readonly origin?: string;
+}
+/**
+ * Build the `/llms.txt` document from the site's pages.
+ *
+ * @example
+ * ```ts
+ * // app/llms.txt/route.ts
+ * export function GET() {
+ *   const body = buildLlmsTxt(pages, { name: config.theme.name });
+ *   return new Response(body, { headers: { 'content-type': 'text/plain; charset=utf-8' } });
+ * }
+ * ```
+ *
+ * @param pages - the site's pages, in navigation order
+ * @param options - the site name, description, and link origin
+ * @returns the document text
+ * @public
+ */
+declare function buildLlmsTxt(pages: readonly LlmsTxtPage[], options: BuildLlmsTxtOptions): string;
+
+/**
+ * Code-sample generators for the API reference's usage panel.
+ *
+ * `fumadocs-openapi` renders one sample per registered generator; a site
+ * replaces a built-in one by adding a generator under the same id. The shapes
+ * here are structural, so this module needs no fumadocs types.
+ *
+ * @packageDocumentation
+ */
+/**
+ * One resolved request parameter, as the usage panel passes it.
+ *
+ * @public
+ */
+interface CodeUsageValue {
+    /** The parameter's example value. */
+    readonly value: string;
+}
+/**
+ * The resolved example request a code-sample generator receives.
+ *
+ * @public
+ */
+interface CodeUsageRequest {
+    /** The HTTP method. */
+    readonly method: string;
+    /** The full request URL, path and query resolved. */
+    readonly url: string;
+    /** Header name to example value. */
+    readonly header?: Readonly<Record<string, CodeUsageValue>>;
+    /** Cookie name to example value. */
+    readonly cookie?: Readonly<Record<string, CodeUsageValue>>;
+    /** The example request body, when the operation takes one. */
+    readonly body?: unknown;
+    /** The body's media type, when the operation takes a body. */
+    readonly bodyMediaType?: string;
+}
+/**
+ * A code-sample generator, shaped for fumadocs-openapi's code-usage registry.
+ *
+ * @public
+ */
+interface CodeUsageGenerator {
+    /** The tab label readers see. */
+    readonly label: string;
+    /** The sample's syntax-highlighting language. */
+    readonly lang: string;
+    /** Render the sample for one resolved example request. */
+    generate(data: CodeUsageRequest): string;
+}
+/**
+ * A cURL sample in long-form flags: `--request`, `--url`, `--header`,
+ * `--data`. Register it over the built-in `curl` entry:
+ *
+ * @example
+ * ```ts
+ * import { curlCodeUsage } from '@blaaiz/docs-core';
+ * import { createCodeUsageGeneratorRegistry } from 'fumadocs-openapi/requests/generators';
+ * import { registerDefault } from 'fumadocs-openapi/requests/generators/all';
+ *
+ * const codeUsages = registerDefault(createCodeUsageGeneratorRegistry());
+ * codeUsages.add('curl', curlCodeUsage);
+ * createOpenAPI({ input, codeUsages });
+ * ```
+ *
+ * @public
+ */
+declare const curlCodeUsage: CodeUsageGenerator;
+
 /**
  * SEO metadata, derived from {@link DocsConfig}.
  *
@@ -628,6 +780,8 @@ interface PlannedGroupChild {
     readonly order: number;
     /** The child folder's name within the group directory. */
     readonly folder: string;
+    /** The child group's title, for the heading the `headings` style renders. */
+    readonly title: string;
 }
 /**
  * A planned API group folder. The generator fills its page order once the
@@ -688,6 +842,17 @@ interface DocsTreePlan {
      */
     readonly apiDocLinks: readonly PlannedApiDocLink[];
 }
+/**
+ * How the sidebar presents a tab's top-level groups.
+ *
+ * - `collapsible`: every group is a collapsible folder (the fumadocs default).
+ * - `headings`: a top-level group is a flat, always-open section heading with
+ *   its pages listed beneath it; only nested groups collapse, and they start
+ *   closed. The Mintlify presentation.
+ *
+ * @public
+ */
+type SidebarStyle = 'collapsible' | 'headings';
 /**
  * Options for {@link planDocsTree}.
  *
@@ -696,6 +861,8 @@ interface DocsTreePlan {
 interface PlanDocsTreeOptions {
     /** Folder for generated API pages when one tab publishes them. Default `api`. */
     readonly apiDir?: string;
+    /** The sidebar's group presentation. Default `collapsible`. */
+    readonly sidebar?: SidebarStyle;
 }
 /**
  * Plan the content tree for a navigation.
@@ -710,9 +877,11 @@ interface PlanDocsTreeOptions {
  * - Root-level doc pages (no `/` in the path) are listed in the root meta.
  * - Tab folders get `root: true`, so the sidebar scopes to the active tab.
  * - Sidebar order is declaration order, pages and groups interleaved.
+ * - With `sidebar: 'headings'`, a tab-level group renders as a flat heading
+ *   with its pages extracted beneath it, and nested groups start closed.
  *
  * @param navigation - the parsed navigation
- * @param options - the API folder name
+ * @param options - the API folder name and the sidebar style
  * @returns the plan the generator executes
  * @throws when two sibling groups slugify to the same folder
  * @public
@@ -799,6 +968,38 @@ interface CreateMarkdownRouteOptions {
      * when the document is expensive to build.
      */
     readonly loadOpenApiDocuments?: () => Readonly<Record<string, OpenApiDocument>> | Promise<Readonly<Record<string, OpenApiDocument>>>;
+    /**
+     * Loads a generated API page's original operation source: the spec file
+     * path, the method and route, and the file's raw contents. When it returns
+     * one, the page's Markdown is the operation spec in full under an
+     * `## OpenAPI` heading, the shape agents get from the major docs platforms;
+     * pages it returns `null` for fall through to the MDX conversion. Wire it
+     * from the generator's `api-sources.json`.
+     */
+    readonly loadOperationSource?: (slug: readonly string[] | undefined) => Promise<OperationSource | null>;
+    /**
+     * The site's documentation index path (`/llms.txt`). When set, every
+     * response opens with a blockquote pointing agents at it, on the origin the
+     * request came in on — correct on localhost, a preview deploy, and
+     * production alike.
+     */
+    readonly llmsTxtPath?: string;
+}
+/**
+ * A generated API page's original operation source, as
+ * {@link CreateMarkdownRouteOptions.loadOperationSource} returns it.
+ *
+ * @public
+ */
+interface OperationSource {
+    /** The spec file, relative to the content directory. */
+    readonly file: string;
+    /** The operation's HTTP method. */
+    readonly method: string;
+    /** The operation's API route. */
+    readonly route: string;
+    /** The spec file's raw contents. */
+    readonly source: string;
 }
 /**
  * Build a drop-in route that serves a page as plain Markdown. It reads the raw
@@ -816,6 +1017,56 @@ interface CreateMarkdownRouteOptions {
  * @public
  */
 declare function createMarkdownRoute(options: CreateMarkdownRouteOptions): MarkdownRoute;
+/**
+ * Options for {@link markdownRewriteTarget}.
+ *
+ * @public
+ */
+interface MarkdownRewriteOptions {
+    /** The docs base URL. Default `/docs`. */
+    readonly baseUrl?: string;
+    /** Where the Markdown route is mounted. Default `/md`. */
+    readonly markdownBase?: string;
+}
+/**
+ * The internal URL serving a docs page's Markdown, for a request whose path is
+ * the page URL plus `.md` — the convention agents and other tools expect
+ * (`/docs/guides/webhooks.md`). Returns `null` for every other request. A
+ * site's middleware rewrites to the returned URL:
+ *
+ * @example
+ * ```ts
+ * const markdown = markdownRewriteTarget(request.nextUrl);
+ * if (markdown) {
+ *   return NextResponse.rewrite(markdown);
+ * }
+ * ```
+ *
+ * @param url - the request URL
+ * @param options - the docs base and the Markdown route's mount point
+ * @returns the rewrite target, or `null` when the request is not a `.md` path
+ * @public
+ */
+declare function markdownRewriteTarget(url: URL, options?: MarkdownRewriteOptions): URL | null;
+/**
+ * Whether a request addresses the Markdown route's internal mount directly.
+ * The route exists as the rewrite target for the page-URL-plus-`.md`
+ * convention; a direct request to it gets `404` from the site's middleware,
+ * so every page's Markdown has one public address.
+ *
+ * @example
+ * ```ts
+ * if (isMarkdownRouteRequest(request.nextUrl)) {
+ *   return new NextResponse('Not found', { status: 404 });
+ * }
+ * ```
+ *
+ * @param url - the request URL
+ * @param options - the Markdown route's mount point
+ * @returns whether the request must be refused
+ * @public
+ */
+declare function isMarkdownRouteRequest(url: URL, options?: Pick<MarkdownRewriteOptions, 'markdownBase'>): boolean;
 
 /**
  * Allowed-domain checks.
@@ -1294,4 +1545,4 @@ declare class OpenApiMergeError extends Error {
  */
 declare function mergeOpenApiDocuments(inputs: readonly unknown[], options: MergeOpenApiOptions): OpenApiDocument;
 
-export { AiConfig, type AiMessage, type AskAiDocumentsSource, type AskAiRoute, type AskAiRouteOptions, type AskAiSource, type AuthGateOptions, type BuildSitemapOptions, type CreateMarkdownRouteOptions, type CreateTryItProxyOptions, DocsConfig, type DocsMetadata, type DocsRobots, type DocsSitemapEntry, type DocsTreePlan, type EmailSignInOptions, type FetchLike, type GoogleAuthHandlers, type GoogleAuthOptions, type IndexedDocument, InvalidNavigationError, type MarkdownRoute, type MdxReader, type MdxToMarkdownOptions, type MergeOpenApiOptions, Navigation, OpenApiDocument, OpenApiInfo, OpenApiMergeError, type OpenApiOperationRef, OpenApiServer, type PageSeo, type PlanDocsTreeOptions, type PlannedApiDocLink, type PlannedApiGroup, type PlannedApiPage, type PlannedGroupChild, type PlannedMeta, ProxyTargetError, SESSION_COOKIE, type SearchDocument, type SearchIndex, type SearchResult, type SecretSignInOptions, type SessionPayload, type SignOutOptions, type SiteAuth, type SiteAuthOptions, type SitemapChangeFrequency, type SitemapEntry, ThemeConfig, type TryItEnvelope, type TryItProxyRoute, assertAllowedTarget, buildMetadata, buildRobots, buildSearchIndex, buildSessionCookie, buildSitemap, buildThemeCss, clearSessionCookie, createAskAiRoute, createAuthGate, createEmailSignIn, createGoogleAuth, createMarkdownRoute, createSecretSignIn, createSignOut, createSiteAuth, createTryItProxy, createTryItProxyRoute, isAllowedEmail, mdxToMarkdown, mergeOpenApiDocuments, openApiOperationToMarkdown, parseNavigation, planDocsTree, readCookie, searchIndex, signSession, unwrapProxyTarget, verifySession };
+export { AiConfig, type AiMessage, type AskAiDocumentsSource, type AskAiRoute, type AskAiRouteOptions, type AskAiSource, type AuthGateOptions, type BuildLlmsTxtOptions, type BuildSitemapOptions, type CodeUsageGenerator, type CodeUsageRequest, type CodeUsageValue, type CreateMarkdownRouteOptions, type CreateTryItProxyOptions, DocsConfig, type DocsMetadata, type DocsRobots, type DocsSitemapEntry, type DocsTreePlan, type EmailSignInOptions, type FetchLike, type GoogleAuthHandlers, type GoogleAuthOptions, type IndexedDocument, InvalidNavigationError, type LlmsTxtPage, type MarkdownRewriteOptions, type MarkdownRoute, type MdxReader, type MdxToMarkdownOptions, type MergeOpenApiOptions, Navigation, OpenApiDocument, OpenApiInfo, OpenApiMergeError, type OpenApiOperationRef, OpenApiServer, type OperationSource, type PageSeo, type PlanDocsTreeOptions, type PlannedApiDocLink, type PlannedApiGroup, type PlannedApiPage, type PlannedGroupChild, type PlannedMeta, ProxyTargetError, SESSION_COOKIE, type SearchDocument, type SearchIndex, type SearchResult, type SecretSignInOptions, type SessionPayload, type SignOutOptions, type SiteAuth, type SiteAuthOptions, type SitemapChangeFrequency, type SitemapEntry, ThemeConfig, type TryItEnvelope, type TryItProxyRoute, assertAllowedTarget, buildLlmsTxt, buildMetadata, buildRobots, buildSearchIndex, buildSessionCookie, buildSitemap, buildThemeCss, clearSessionCookie, createAskAiRoute, createAuthGate, createEmailSignIn, createGoogleAuth, createMarkdownRoute, createSecretSignIn, createSignOut, createSiteAuth, createTryItProxy, createTryItProxyRoute, curlCodeUsage, isAllowedEmail, isMarkdownRouteRequest, markdownRewriteTarget, mdxToMarkdown, mergeOpenApiDocuments, openApiOperationToMarkdown, parseNavigation, planDocsTree, readCookie, redirectTarget, searchIndex, signSession, unwrapProxyTarget, verifySession };

package/dist/index.js

@@ -1,3 +1,3 @@
-export { AI_PROVIDER_MODELS, AI_PROVIDER_NAMES, AiConfigError, DocsConfigError, InvalidNavigationError, OpenApiMergeError, ProxyTargetError, SESSION_COOKIE, assertAllowedTarget, buildMetadata, buildRobots, buildSearchIndex, buildSessionCookie, buildSitemap, buildThemeCss, clearSessionCookie, createAskAiRoute, createAuthGate, createEmailSignIn, createGoogleAuth, createMarkdownRoute, createSecretSignIn, createSignOut, createSiteAuth, createTryItProxy, createTryItProxyRoute, defineDocsConfig, isAllowedEmail, mdxToMarkdown, mergeOpenApiDocuments, openApiOperationToMarkdown, parseNavigation, planDocsTree, readCookie, resolveAiConfig, searchIndex, signSession, unwrapProxyTarget, validateDocsConfig, verifySession } from './chunk-ZWDLAW5M.js';
+export { AI_PROVIDER_MODELS, AI_PROVIDER_NAMES, AiConfigError, DocsConfigError, InvalidNavigationError, OpenApiMergeError, ProxyTargetError, SESSION_COOKIE, assertAllowedTarget, buildLlmsTxt, buildMetadata, buildRobots, buildSearchIndex, buildSessionCookie, buildSitemap, buildThemeCss, clearSessionCookie, createAskAiRoute, createAuthGate, createEmailSignIn, createGoogleAuth, createMarkdownRoute, createSecretSignIn, createSignOut, createSiteAuth, createTryItProxy, createTryItProxyRoute, curlCodeUsage, defineDocsConfig, isAllowedEmail, isMarkdownRouteRequest, markdownRewriteTarget, mdxToMarkdown, mergeOpenApiDocuments, openApiOperationToMarkdown, parseNavigation, planDocsTree, readCookie, redirectTarget, resolveAiConfig, searchIndex, signSession, unwrapProxyTarget, validateDocsConfig, verifySession } from './chunk-L4PFRXIK.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map