@takazudo/zudo-doc 0.1.0

package/dist/integrations/doc-history/index.js

@@ -0,0 +1,138 @@
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import { dirname, join, resolve as resolvePath } from "node:path";
+import {
+  runDocHistoryMetaStep
+} from "./pre-build.js";
+const DEFAULT_SERVER_PORT = 4322;
+const DEFAULT_MAX_ENTRIES = 50;
+const DOC_HISTORY_ROUTE_PREFIX = "/doc-history/";
+const DOC_HISTORY_OUTPUT_DIRNAME = "doc-history";
+const DOC_HISTORY_GENERATE_BIN = "doc-history-generate";
+function docHistoryPlugin(options) {
+  return { name: "doc-history", options };
+}
+function createDocHistoryDevMiddleware(options, logger) {
+  const port = options.serverPort ?? DEFAULT_SERVER_PORT;
+  return (req, res, next) => {
+    const url = req.url ?? "";
+    if (!url.includes(DOC_HISTORY_ROUTE_PREFIX)) {
+      next();
+      return;
+    }
+    const idx = url.indexOf(DOC_HISTORY_ROUTE_PREFIX);
+    const proxyPath = url.slice(idx);
+    const proxyUrl = `http://localhost:${port}${proxyPath}`;
+    fetch(proxyUrl).then(async (upstream) => {
+      res.statusCode = upstream.status;
+      res.setHeader(
+        "Content-Type",
+        upstream.headers.get("content-type") ?? "application/json"
+      );
+      const body = await upstream.text();
+      res.end(body);
+    }).catch((err) => {
+      const msg = err instanceof Error ? err.message : String(err);
+      logger?.warn(
+        `Doc history proxy failed: ${msg}. Is the doc-history server running on port ${port}?`
+      );
+      res.statusCode = 502;
+      res.setHeader("Content-Type", "application/json");
+      res.end(
+        JSON.stringify({
+          error: `Doc history server unavailable (port ${port})`
+        })
+      );
+    });
+  };
+}
+async function runDocHistoryPostBuild(options, ctx) {
+  if (process.env.SKIP_DOC_HISTORY === "1") {
+    ctx.logger?.info("Skipping doc history generation (SKIP_DOC_HISTORY=1)");
+    return;
+  }
+  const args = buildGenerateCliArgs(options, ctx.outDir);
+  await spawnDocHistoryGenerate(args, ctx.logger);
+}
+function buildGenerateCliArgs(options, outDir) {
+  const historyOut = join(outDir, DOC_HISTORY_OUTPUT_DIRNAME);
+  const args = [
+    "--content-dir",
+    options.docsDir,
+    "--out-dir",
+    historyOut
+  ];
+  if (options.locales) {
+    for (const [key, locale] of Object.entries(options.locales)) {
+      args.push("--locale", `${key}:${locale.dir}`);
+    }
+  }
+  if (options.maxEntries != null) {
+    args.push("--max-entries", String(options.maxEntries));
+  }
+  return args;
+}
+function resolveDocHistoryGenerateBin() {
+  const localRequire = createRequire(import.meta.url);
+  const pkgJsonPath = localRequire.resolve(
+    "@takazudo/zudo-doc-history-server/package.json"
+  );
+  const pkgJson = localRequire(
+    "@takazudo/zudo-doc-history-server/package.json"
+  );
+  const binEntry = typeof pkgJson.bin === "string" ? pkgJson.bin : pkgJson.bin?.[DOC_HISTORY_GENERATE_BIN];
+  if (!binEntry) {
+    throw new Error(
+      `@takazudo/zudo-doc-history-server does not declare a '${DOC_HISTORY_GENERATE_BIN}' bin entry`
+    );
+  }
+  return resolvePath(dirname(pkgJsonPath), binEntry);
+}
+function spawnDocHistoryGenerate(args, logger) {
+  return new Promise((resolveSpawn, reject) => {
+    let cliPath;
+    try {
+      cliPath = resolveDocHistoryGenerateBin();
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      logger?.warn(
+        `Failed to resolve ${DOC_HISTORY_GENERATE_BIN} from @takazudo/zudo-doc-history-server: ${msg}`
+      );
+      reject(err instanceof Error ? err : new Error(msg));
+      return;
+    }
+    const child = spawn(process.execPath, [cliPath, ...args], {
+      stdio: "inherit",
+      shell: false
+    });
+    child.on("error", (err) => {
+      logger?.warn(
+        `Failed to launch ${DOC_HISTORY_GENERATE_BIN}: ${err.message}`
+      );
+      reject(err);
+    });
+    child.on("exit", (code, signal) => {
+      if (code === 0) {
+        resolveSpawn();
+        return;
+      }
+      const reason = code != null ? `exit code ${code}` : `signal ${signal ?? "unknown"}`;
+      reject(
+        new Error(`${DOC_HISTORY_GENERATE_BIN} failed (${reason})`)
+      );
+    });
+  });
+}
+export {
+  DEFAULT_MAX_ENTRIES,
+  DEFAULT_SERVER_PORT,
+  DOC_HISTORY_GENERATE_BIN,
+  DOC_HISTORY_OUTPUT_DIRNAME,
+  DOC_HISTORY_ROUTE_PREFIX,
+  buildGenerateCliArgs,
+  createDocHistoryDevMiddleware,
+  docHistoryPlugin,
+  resolveDocHistoryGenerateBin,
+  runDocHistoryMetaStep,
+  runDocHistoryPostBuild
+};

package/dist/integrations/doc-history/pre-build.d.ts

@@ -0,0 +1,58 @@
+/** A single non-default locale entry; mirrors `settings.locales[*]`. */
+interface DocHistoryMetaLocaleConfig {
+    /** Absolute or project-relative directory holding this locale's MDX content. */
+    dir: string;
+}
+/** A versioned docs entry; mirrors `settings.versions[*]`. */
+interface DocHistoryMetaVersionConfig {
+    /** Slug used to namespace the version (e.g. `"1.0"`). */
+    slug: string;
+    /** Default-locale content directory for this version. */
+    docsDir: string;
+    /** Optional non-default locales, keyed by locale code. */
+    locales?: Record<string, DocHistoryMetaLocaleConfig>;
+}
+/** Options accepted by the preBuild runner. */
+interface RunDocHistoryMetaOptions {
+    /** Project root — directory containing `zfb.config.ts`. Resolves all relative paths. */
+    projectRoot: string;
+    /** Default-locale content directory (e.g. `"src/content/docs"`). */
+    docsDir: string;
+    /** Optional non-default locales, keyed by locale code. */
+    locales?: Record<string, DocHistoryMetaLocaleConfig>;
+    /**
+     * Optional versioned docs (e.g. legacy `1.0`). Each version produces
+     * its own default-locale collection plus per-locale variants.
+     * Currently unused by the host's emitted manifest (parity with
+     * `scripts/zfb-prebuild.mjs`) — accepted here so callers can pass
+     * versions through without ad-hoc filtering.
+     */
+    versions?: DocHistoryMetaVersionConfig[];
+    /** Optional logger. Falls back to `console`. */
+    logger?: {
+        info(msg: string): void;
+        warn?(msg: string): void;
+    };
+}
+/** A single manifest entry. */
+interface DocHistoryMetaEntry {
+    author: string;
+    createdDate: string;
+    updatedDate: string;
+}
+/** Manifest shape — keyed by composedSlug. */
+type DocHistoryMetaManifest = Record<string, DocHistoryMetaEntry>;
+/**
+ * Emit `<projectRoot>/.zfb/doc-history-meta.json` from git history.
+ *
+ * Honours the `SKIP_DOC_HISTORY=1` env-var short-circuit (see header
+ * comment for the CI contract). Writes a byte-identical empty manifest
+ * (`{}\n`) when set; writes a sorted-key JSON document otherwise.
+ *
+ * Skips files with no git history (untracked / not yet committed) by
+ * omitting them from the manifest — the page-side wrapper treats
+ * undefined entries as "no SSR data".
+ */
+declare function runDocHistoryMetaStep(options: RunDocHistoryMetaOptions): Promise<void>;
+
+export { type DocHistoryMetaEntry, type DocHistoryMetaLocaleConfig, type DocHistoryMetaManifest, type DocHistoryMetaVersionConfig, type RunDocHistoryMetaOptions, runDocHistoryMetaStep };

package/dist/integrations/doc-history/pre-build.js

@@ -0,0 +1,67 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  collectContentFiles,
+  getFileCommits,
+  getFirstCommit,
+  getCommitInfo
+} from "@takazudo/zudo-doc-history-server/git-history";
+const META_OUT_RELATIVE_DIR = ".zfb";
+const META_OUT_FILENAME = "doc-history-meta.json";
+async function runDocHistoryMetaStep(options) {
+  const projectRoot = path.resolve(options.projectRoot);
+  const zfbDir = path.join(projectRoot, META_OUT_RELATIVE_DIR);
+  const outPath = path.join(zfbDir, META_OUT_FILENAME);
+  const logger = options.logger ?? defaultLogger;
+  if (process.env.SKIP_DOC_HISTORY === "1") {
+    logger.info(
+      "[doc-history-meta] SKIP_DOC_HISTORY=1 \u2014 emitting empty doc-history-meta.json"
+    );
+    fs.mkdirSync(zfbDir, { recursive: true });
+    fs.writeFileSync(outPath, "{}\n", "utf-8");
+    return;
+  }
+  const dirEntries = [
+    [null, path.resolve(projectRoot, options.docsDir)]
+  ];
+  if (options.locales) {
+    for (const [code, locale] of Object.entries(options.locales)) {
+      dirEntries.push([code, path.resolve(projectRoot, locale.dir)]);
+    }
+  }
+  const meta = {};
+  for (const [localeKey, contentDir] of dirEntries) {
+    const files = collectContentFiles(contentDir);
+    for (const { filePath, slug } of files) {
+      const commits = getFileCommits(filePath, 1);
+      if (commits.length === 0) continue;
+      const newestInfo = getCommitInfo(commits[0], filePath);
+      const firstHash = getFirstCommit(filePath);
+      const oldestInfo = firstHash && firstHash !== commits[0] ? getCommitInfo(firstHash, filePath) : newestInfo;
+      const composedSlug = localeKey ? `${localeKey}/${slug}` : slug;
+      meta[composedSlug] = {
+        // Author comes from the FIRST (oldest) commit.
+        author: oldestInfo.author,
+        // createdDate = oldest commit; updatedDate = newest commit.
+        createdDate: oldestInfo.date,
+        updatedDate: newestInfo.date
+      };
+    }
+  }
+  fs.mkdirSync(zfbDir, { recursive: true });
+  fs.writeFileSync(outPath, JSON.stringify(meta, null, 2) + "\n", "utf-8");
+  logger.info(
+    `[doc-history-meta] wrote ${Object.keys(meta).length} entries \u2192 .zfb/doc-history-meta.json`
+  );
+}
+const defaultLogger = {
+  info(msg) {
+    console.log(msg);
+  },
+  warn(msg) {
+    console.warn(msg);
+  }
+};
+export {
+  runDocHistoryMetaStep
+};

package/dist/integrations/llms-txt/dev-middleware.d.ts

@@ -0,0 +1,40 @@
+import { IncomingMessage, ServerResponse } from 'node:http';
+import { LlmsTxtSiteMeta, LlmsTxtLocaleConfig } from './types.js';
+
+/** Connect-style middleware signature — works as a Vite plugin middleware. */
+type LlmsTxtNextFn = (err?: unknown) => void;
+type LlmsTxtMiddleware = (req: IncomingMessage, res: ServerResponse, next: LlmsTxtNextFn) => void;
+/** Minimal logger surface used by the middleware on generation failure. */
+interface LlmsTxtMiddlewareLogger {
+    warn(msg: string): void;
+}
+/**
+ * Build-time + dev-time options. Mirrors {@link LlmsTxtEmitOptions}
+ * minus the `outDir` field (the dev middleware never writes to disk)
+ * so callers can hand a single options object to both `emitLlmsTxt`
+ * (build) and `createLlmsTxtDevMiddleware` (dev).
+ */
+interface LlmsTxtDevMiddlewareOptions extends LlmsTxtSiteMeta {
+    /** URL base used when materialising per-page links. */
+    base: string;
+    /** Optional absolute site URL; see `LlmsTxtLoadOptions.siteUrl`. */
+    siteUrl?: string;
+    /** Default-locale content directory. */
+    defaultLocaleDir: string;
+    /** Additional locales (e.g. `[{ code: "ja", dir: "src/content/docs-ja" }]`). */
+    locales?: LlmsTxtLocaleConfig[];
+}
+/**
+ * Build a dev-server middleware that responds to GET requests for
+ * `/llms.txt`, `/llms-full.txt`, `/<code>/llms.txt`, and
+ * `/<code>/llms-full.txt`. Unknown locale prefixes fall through (the
+ * chain returns 404), avoiding collisions with future routes that
+ * might share the `/<thing>/llms.txt` shape.
+ *
+ * Every request rebuilds the entries from disk — the same pattern the
+ * sibling `searchIndex` middleware uses — so authoring loops surface
+ * content edits without a dev-server restart.
+ */
+declare function createLlmsTxtDevMiddleware(options: LlmsTxtDevMiddlewareOptions, logger?: LlmsTxtMiddlewareLogger): LlmsTxtMiddleware;
+
+export { type LlmsTxtDevMiddlewareOptions, type LlmsTxtMiddleware, type LlmsTxtMiddlewareLogger, type LlmsTxtNextFn, createLlmsTxtDevMiddleware };

package/dist/integrations/llms-txt/dev-middleware.js

@@ -0,0 +1,76 @@
+import { generateLlmsFullTxt, generateLlmsTxt } from "./generate.js";
+import { loadDocEntries } from "./load.js";
+const LLMS_KIND_PATTERN = /^(?:\/(.+?))?\/(llms|llms-full)\.txt$/;
+function createLlmsTxtDevMiddleware(options, logger) {
+  const meta = {
+    siteName: options.siteName,
+    siteDescription: options.siteDescription
+  };
+  const localeCodes = new Set((options.locales ?? []).map((l) => l.code));
+  const localeDirByCode = new Map(
+    (options.locales ?? []).map((l) => [l.code, l.dir])
+  );
+  const base = options.base ?? "";
+  const siteUrl = options.siteUrl || void 0;
+  return (req, res, next) => {
+    const url = req.url ?? "";
+    const match = matchLlmsRoute(stripBase(url, base), localeCodes);
+    if (!match) {
+      next();
+      return;
+    }
+    if (req.method && req.method !== "GET" && req.method !== "HEAD") {
+      res.statusCode = 405;
+      res.setHeader("Content-Type", "text/plain; charset=utf-8");
+      res.end("Method Not Allowed");
+      return;
+    }
+    try {
+      const contentDir = match.locale === null ? options.defaultLocaleDir : localeDirByCode.get(match.locale);
+      if (contentDir === void 0) {
+        res.statusCode = 404;
+        res.setHeader("Content-Type", "text/plain; charset=utf-8");
+        res.end("Not Found");
+        return;
+      }
+      const entries = loadDocEntries({
+        contentDir,
+        locale: match.locale,
+        base,
+        siteUrl
+      });
+      const body = match.kind === "llms" ? generateLlmsTxt(entries, meta) : generateLlmsFullTxt(entries, meta);
+      res.statusCode = 200;
+      res.setHeader("Content-Type", "text/plain; charset=utf-8");
+      res.end(body);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      logger?.warn(`llms-txt generation failed: ${msg}`);
+      res.statusCode = 500;
+      res.setHeader("Content-Type", "text/plain; charset=utf-8");
+      res.end("Internal Server Error");
+    }
+  };
+}
+function matchLlmsRoute(url, localeCodes) {
+  const pathname = url.split("?")[0];
+  const m = pathname.match(LLMS_KIND_PATTERN);
+  if (!m) return null;
+  const prefix = m[1];
+  const kind = m[2];
+  if (prefix === void 0) return { kind, locale: null };
+  if (localeCodes.has(prefix)) return { kind, locale: prefix };
+  return null;
+}
+function stripBase(url, base) {
+  if (!base || base === "/") return url;
+  const normalised = base.endsWith("/") ? base.slice(0, -1) : base;
+  if (url.startsWith(normalised + "/")) {
+    return url.slice(normalised.length);
+  }
+  if (url === normalised) return "/";
+  return url;
+}
+export {
+  createLlmsTxtDevMiddleware
+};

package/dist/integrations/llms-txt/emit.d.ts

@@ -0,0 +1,22 @@
+import { LlmsTxtEmitOptions, LlmsTxtEmitResult } from './types.js';
+
+/**
+ * Build-time emitter that writes `llms.txt` and `llms-full.txt` for the
+ * default locale plus every additional locale.
+ *
+ * Designed as a zfb-shaped build hook: the function takes a single
+ * options object, performs synchronous fs writes, and returns the list
+ * of files it produced. Adapters wrap it for their build system —
+ * Astro's `astro:build:done`, a future zfb plugin's `onBuildDone`,
+ * a Node CLI in CI, etc.
+ */
+
+/**
+ * Walk every configured content root, generate the two files per
+ * locale, and write them to `outDir` (default locale) and
+ * `outDir/<code>/` (additional locales). The output directory is
+ * created if needed; existing files are overwritten.
+ */
+declare function emitLlmsTxt(options: LlmsTxtEmitOptions): LlmsTxtEmitResult;
+
+export { emitLlmsTxt };

package/dist/integrations/llms-txt/emit.js

@@ -0,0 +1,55 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { generateLlmsFullTxt, generateLlmsTxt } from "./generate.js";
+import { loadDocEntries } from "./load.js";
+function emitLlmsTxt(options) {
+  const {
+    outDir,
+    base,
+    siteUrl,
+    siteName,
+    siteDescription,
+    defaultLocaleDir,
+    locales = [],
+    logger
+  } = options;
+  const meta = { siteName, siteDescription };
+  const written = [];
+  const defaultEntries = loadDocEntries({
+    contentDir: defaultLocaleDir,
+    locale: null,
+    base,
+    siteUrl
+  });
+  mkdirSync(outDir, { recursive: true });
+  const defaultIndexPath = join(outDir, "llms.txt");
+  const defaultFullPath = join(outDir, "llms-full.txt");
+  writeFileSync(defaultIndexPath, generateLlmsTxt(defaultEntries, meta));
+  writeFileSync(defaultFullPath, generateLlmsFullTxt(defaultEntries, meta));
+  written.push(defaultIndexPath, defaultFullPath);
+  logger?.info(
+    `Generated llms.txt and llms-full.txt (${defaultEntries.length} pages)`
+  );
+  for (const { code, dir } of locales) {
+    const localeEntries = loadDocEntries({
+      contentDir: dir,
+      locale: code,
+      base,
+      siteUrl
+    });
+    const localeDir = join(outDir, code);
+    mkdirSync(localeDir, { recursive: true });
+    const indexPath = join(localeDir, "llms.txt");
+    const fullPath = join(localeDir, "llms-full.txt");
+    writeFileSync(indexPath, generateLlmsTxt(localeEntries, meta));
+    writeFileSync(fullPath, generateLlmsFullTxt(localeEntries, meta));
+    written.push(indexPath, fullPath);
+    logger?.info(
+      `Generated ${code}/llms.txt and ${code}/llms-full.txt (${localeEntries.length} pages)`
+    );
+  }
+  return { written };
+}
+export {
+  emitLlmsTxt
+};

package/dist/integrations/llms-txt/generate.d.ts

@@ -0,0 +1,26 @@
+import { LlmsDocEntry, LlmsTxtSiteMeta } from './types.js';
+
+/**
+ * Pure string generators for `llms.txt` and `llms-full.txt`.
+ *
+ * Both functions are intentionally pure (no fs, no logger, no globals)
+ * so they can be unit-tested with fixture entries and so a future zfb
+ * non-HTML page (`pages/llms.txt.tsx`) can call them straight from a
+ * default export without a build-time hook.
+ *
+ * Output format must remain byte-identical to the legacy Astro emitter
+ * — the file shape is part of the project's public surface.
+ */
+
+/**
+ * Slim index — site header followed by a markdown bullet per page with
+ * `[title](url): description`.
+ */
+declare function generateLlmsTxt(entries: readonly LlmsDocEntry[], meta: LlmsTxtSiteMeta): string;
+/**
+ * Full content concatenation — site header followed by every page's
+ * stripped body separated by `---` rules.
+ */
+declare function generateLlmsFullTxt(entries: readonly LlmsDocEntry[], meta: LlmsTxtSiteMeta): string;
+
+export { generateLlmsFullTxt, generateLlmsTxt };

package/dist/integrations/llms-txt/generate.js

@@ -0,0 +1,36 @@
+function generateLlmsTxt(entries, meta) {
+  const lines = [];
+  lines.push(`# ${meta.siteName}`);
+  lines.push("");
+  lines.push(`> ${meta.siteDescription}`);
+  lines.push("");
+  lines.push("## Docs");
+  lines.push("");
+  for (const entry of entries) {
+    lines.push(`- [${entry.title}](${entry.url}): ${entry.description}`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+function generateLlmsFullTxt(entries, meta) {
+  const lines = [];
+  lines.push(`# ${meta.siteName}`);
+  lines.push("");
+  lines.push(`> ${meta.siteDescription}`);
+  for (const entry of entries) {
+    lines.push("");
+    lines.push("---");
+    lines.push("");
+    lines.push(`# ${entry.title}`);
+    lines.push("");
+    lines.push(`> Source: ${entry.url}`);
+    lines.push("");
+    lines.push(entry.content);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+export {
+  generateLlmsFullTxt,
+  generateLlmsTxt
+};

package/dist/integrations/llms-txt/index.d.ts

@@ -0,0 +1,7 @@
+export { LlmsTxtDevMiddlewareOptions, LlmsTxtMiddleware, LlmsTxtMiddlewareLogger, LlmsTxtNextFn, createLlmsTxtDevMiddleware } from './dev-middleware.js';
+export { emitLlmsTxt } from './emit.js';
+export { generateLlmsFullTxt, generateLlmsTxt } from './generate.js';
+export { collectMdFiles, isExcluded, loadDocEntries, parseMarkdownFile, slugToUrl } from './load.js';
+export { stripImportsAndJsx, stripMarkdown } from './strip.js';
+export { LlmsDocEntry, LlmsTxtEmitOptions, LlmsTxtEmitResult, LlmsTxtFrontmatter, LlmsTxtLoadOptions, LlmsTxtLocaleConfig, LlmsTxtLogger, LlmsTxtSiteMeta } from './types.js';
+import 'node:http';

package/dist/integrations/llms-txt/index.js

@@ -0,0 +1,27 @@
+import { createLlmsTxtDevMiddleware } from "./dev-middleware.js";
+import { emitLlmsTxt } from "./emit.js";
+import {
+  generateLlmsFullTxt,
+  generateLlmsTxt
+} from "./generate.js";
+import {
+  collectMdFiles,
+  isExcluded,
+  loadDocEntries,
+  parseMarkdownFile,
+  slugToUrl
+} from "./load.js";
+import { stripImportsAndJsx, stripMarkdown } from "./strip.js";
+export {
+  collectMdFiles,
+  createLlmsTxtDevMiddleware,
+  emitLlmsTxt,
+  generateLlmsFullTxt,
+  generateLlmsTxt,
+  isExcluded,
+  loadDocEntries,
+  parseMarkdownFile,
+  slugToUrl,
+  stripImportsAndJsx,
+  stripMarkdown
+};

package/dist/integrations/llms-txt/load.d.ts

@@ -0,0 +1,51 @@
+import { LlmsTxtFrontmatter, LlmsTxtLoadOptions, LlmsDocEntry } from './types.js';
+
+/**
+ * Filesystem loader for llms-txt content. Walks a markdown content root,
+ * parses frontmatter via `gray-matter`, and emits sorted
+ * {@link LlmsDocEntry} records ready for the generator stage.
+ *
+ * Lives in the framework layer (no `@/...` imports) so any consumer
+ * project — Astro today, zfb tomorrow, fixture-driven unit tests in
+ * between — can drive the emitter without dragging in the legacy
+ * `src/utils/content-files.ts` module.
+ */
+
+/**
+ * Walk `dir` recursively and return every `*.md` / `*.mdx` file's
+ * absolute path together with its docs-relative slug. Files (or whole
+ * directories) whose name starts with `_` are skipped, matching the
+ * Content Collections convention.
+ */
+declare function collectMdFiles(dir: string): Array<{
+    filePath: string;
+    slug: string;
+}>;
+/**
+ * Compute a docs URL for a given slug + locale. Mirrors the legacy
+ * `slugToUrl(slug, locale, true)` call site exactly: when `siteUrl` is
+ * empty, the URL is path-only; when `siteUrl` is set, a fully qualified
+ * URL is produced.
+ */
+declare function slugToUrl(slug: string, locale: string | null, base: string, siteUrl?: string): string;
+/** Whether a given doc should be excluded from the llms.txt index. */
+declare function isExcluded(data: LlmsTxtFrontmatter): boolean;
+/**
+ * Parse a markdown file into frontmatter + body. Returns `null` when
+ * the file is unreadable so callers can simply skip it.
+ */
+declare function parseMarkdownFile(filePath: string): {
+    data: LlmsTxtFrontmatter;
+    content: string;
+} | null;
+/**
+ * Build the sorted {@link LlmsDocEntry} list for a single content root.
+ * Excluded pages (draft / unlisted / search_exclude) are dropped.
+ * Entries are sorted ascending by `sidebar_position`; entries without a
+ * position go last (they share `Number.MAX_SAFE_INTEGER`, and
+ * `Array.prototype.sort` is stable in V8 so ties keep filesystem
+ * traversal order — same as the legacy emitter).
+ */
+declare function loadDocEntries(options: LlmsTxtLoadOptions): LlmsDocEntry[];
+
+export { collectMdFiles, isExcluded, loadDocEntries, parseMarkdownFile, slugToUrl };