Configure docs sources

Leadtype can read from one local docs folder, multiple local folders, or remote git repositories. For a small single-repo project, start with one local folder. For hosted product docs where the docs UI is separate from the package/source repo, start with a pinned remote collection and inherit the source repo's source-owned docs config.

Pick the right source shape

Use one docs folder when ownership is simple. Use pinned remote collections when the docs site is a hub for content owned by another repo, package, framework, or release stream. Use mounts when the source is still one docs tree and only the public URL differs.

One local docs folder

Put MDX under docs/ and product/nav metadata in docs/docs.config.ts:

import { defineDocsConfig } from "leadtype";

export default defineDocsConfig({
  product: {
    name: "My product",
    tagline: "Developer tools for modern apps.",
  },
  llms: {
    sections: [
      {
        type: "links",
        heading: "Best Starting Points",
        links: [
          {
            urlPath: "/docs",
            title: "Overview",
            description: "Start page for the docs site.",
          },
          {
            urlPath: "/docs/quickstart",
            title: "Quickstart",
            description: "First steps for setting up My product.",
          },
        ],
      },
    ],
  },
  navigation: [
    "index",
    "quickstart",
    { title: "Guides", pages: [{ include: "guides/*" }] },
    { title: "Reference", pages: [{ include: "reference/*" }] },
  ],
});

Then generate:

npx leadtype generate --src . --out public --base-url https://example.com

This reads ./docs, writes website artifacts to public, and exposes pages under /docs. Top-level string entries become root pages instead of groups. Use index for docs/index.mdx; Leadtype strips index from generated URLs so that page still resolves to /docs.

Mount a subtree at a top-level URL

Use mounts when a subtree is part of the same docs source but should not live under /docs publicly. A common example is a changelog kept at docs/changelog/*.mdx by the same repo and config as the rest of the docs:

import { defineDocsConfig } from "leadtype";

export default defineDocsConfig({
  product: {
    name: "My product",
    tagline: "Developer tools for modern apps.",
  },
  navigation: [
    "index",
    "quickstart",
    {
      title: "Changelog",
      base: "changelog",
      optional: true,
      pages: ["v1"],
    },
  ],
  mounts: [{ pathPrefix: "changelog", urlPrefix: "/changelog" }],
});

With that mount, docs/changelog/v1.mdx still generates an internal copy at public/docs/changelog/v1.md for search and runtime helpers, but canonical URLs become /changelog/v1 and /changelog/v1.md in llms.txt, sitemap data, search metadata, and agent-readability.json.

Prefer this over a second collection when the changelog shares the same source repo, frontmatter schema, navigation ownership, and release process as the docs. Use a collection only when the changelog is a separate source or needs separate filters, schema, ownership, or remote acquisition.

Multiple local folders

Repeat --docs-dir when a single source repo keeps agent-readable content outside the main docs folder:

npx leadtype generate \
  --src . \
  --docs-dir docs \
  --docs-dir changelog \
  --out public \
  --base-url https://example.com

The first folder becomes the generated docs root. Additional folders are nested under their folder name, so changelog/v1.mdx becomes public/docs/changelog/v1.md and /docs/changelog/v1.

Mount a folder at its own public URL prefix when it should not appear under /docs:

npx leadtype generate \
  --src . \
  --docs-dir docs \
  --docs-dir changelog=/changelog \
  --out public \
  --base-url https://example.com

Leadtype still keeps an internal generated copy for search and agent helpers, but canonical links, sitemap entries, and agent metadata point to /changelog/v1.

Collections

Use collections when each source needs explicit ownership. Collections live in a project-level leadtype.config.ts at the directory passed to --src.

import { defineCollection, defineDocsConfig } from "leadtype";

export default defineDocsConfig({
  product: {
    name: "My product",
    tagline: "Developer tools for modern apps.",
  },
  collections: {
    docs: defineCollection({
      dir: "./docs",
      prefix: "/docs",
      navigation: ["index", "quickstart"],
    }),
    changelog: defineCollection({
      dir: "./changelog",
      prefix: "/changelog",
      include: ["*.mdx"],
    }),
  },
});

Run the same site-mode generate command:

npx leadtype generate --src . --out public --base-url https://example.com

When leadtype.config.ts defines collections, the collection map fully describes the sources. Do not combine collections with --docs-dir.

Remote git sources

Set repository to make a collection remote. Pin ref to the version you want: a branch for moving docs, a tag for release docs, or a commit SHA for fully reproducible output.

For the split-repo docs UI shape, add sourceConfig: true. After sync, Leadtype loads docs.config.{ts,js,mjs,cjs} from the remote collection dir and inherits MDX-owned fields (navigation, groups, frontmatterSchema, flatteners, and mounts) into the collection.

Keep this ownership split clear:

• Source repo: MDX, navigation/sidebar order, fallback groups, frontmatter schema, source-specific flatteners, and same-tree mounts such as docs/changelog -> /changelog.
• Docs UI repo: source repository/ref, product identity as rendered by the site, organization, agent policy, app shell, output paths, and deployment.

import { defineCollection, defineDocsConfig } from "leadtype";

const sdkDocs = {
  repository: "https://github.com/acme/sdk",
  ref: "v2.4.0",
  cacheDir: ".docs-src/sdk",
} as const;

export default defineDocsConfig({
  product: {
    name: "Acme",
    tagline: "Docs for Acme SDKs and platform APIs.",
  },
  collections: {
    platform: defineCollection({
      dir: "./docs",
      prefix: "/docs",
    }),
    sdk: defineCollection({
      ...sdkDocs,
      dir: "docs",
      prefix: "/docs/sdk",
      sourceConfig: true,
      include: ["quickstart.mdx", "guides/**", "reference/**"],
      exclude: ["**/internal/**"],
    }),
  },
});

If the source repo's docs/docs.config.ts declares mounts: [{ pathPrefix: "changelog", urlPrefix: "/changelog" }], the docs UI repo inherits that mapping through sourceConfig: true. A remote page at docs/changelog/v1.mdx is generated with canonical URLs /changelog/v1 and /changelog/v1.md, not /docs/changelog/v1.

The docs UI repo can also declare mounts directly on the collection when it needs to override an older pinned source ref that does not yet include the source-owned mount:

docs: defineCollection({
  ...sdkDocs,
  dir: "docs",
  prefix: "/docs",
  sourceConfig: true,
  mounts: [{ pathPrefix: "changelog", urlPrefix: "/changelog" }],
});

Sync the remote source before generating:

npx leadtype sync --src .
npx leadtype generate --src . --out public --base-url https://example.com

Or clone missing caches and generate in one command:

npx leadtype generate --src . --out public --base-url https://example.com --sync

Pinning strategy

For CI, use tags or commit SHAs when the generated docs must be reproducible. Use branches for preview environments or docs hubs that intentionally track the latest upstream content.

Sync modes

Each synced repo gets a .leadtype-sync.json manifest in its cache directory. Leadtype reads that manifest during generate so stale or missing remote sources fail loudly instead of silently producing docs from the wrong revision.

Package bundle filters

For npm package docs, use --bundle and filter to the docs that belong to that package:

npx leadtype generate \
  --bundle \
  --src . \
  --out packages/react \
  --include "frameworks/react/**" \
  --include "shared/**" \
  --exclude "**/internal/**"

Bundle mode writes AGENTS.md and docs/*.md into the package. See Bundle docs into a package for the full publish flow.

What to read next