Configuration reference

Use defineDocsConfig() for type inference and immediate validation of unknown keys:

import { defineDocsConfig } from "@tenphi/cookbook";

export default defineDocsConfig({
  site: { title: "Example" },
  content: { sources: [{ file: "README.md", route: "/" }] },
});

All built-in options are JSON-serializable. Unknown top-level and section keys are errors.

Site

site: {
  title: "Example Project",
  description: "Documentation for Example Project",
  url: "https://docs.example.com",
  repository: "https://github.com/example/project"
}

url is the canonical deployed origin. Set Astro’s site value too when the host needs absolute canonical URLs or sitemap metadata.

Content

content: {
  sources: [
    { file: "README.md", route: "/" },
    { glob: "docs/**/*.{md,mdx}", base: "docs" }
  ],
  allowOutsideRoot: false,
  localizeRepositoryLinks: false
}

See Content sources for every declaration and its route rules.

Navigation can mix direct routes, nested groups, autogenerated directories, and external links. Groups are recursive and can be nested to any practical depth. Use the object form to add an optional primary tab row above the documentation shell:

navigation: {
  tabs: [
    {
      label: "Guides",
      link: "/",
      items: [
        "/",
        {
          label: "Build",
          items: [
            {
              label: "Frontend",
              items: [
                {
                  label: "Frameworks",
                  items: ["/react", "/vue"]
                }
              ]
            }
          ]
        }
      ]
    },
    {
      label: "API",
      link: "/reference",
      items: [
        {
          label: "Reference",
          autogenerate: { directory: "/reference" }
        }
      ]
    },
    { label: "Playground", link: "https://example.com/playground" }
  ],
  items: [
    "/",
    {
      label: "Start here",
      items: ["/getting-started", "/configuration"]
    },
    {
      label: "Reference",
      autogenerate: { directory: "/reference" }
    }
  ]
}

Tabs are omitted when tabs is not set. Give a tab items to replace the sidebar for that section. Those items also establish section membership, so a tab can own routes that do not share its URL prefix. A tab stays active for pages nested below its link; / matches only the home page. When multiple tabs could match, an exact tab link wins, followed by the longest link prefix and then sidebar membership. Tabs without items use the top-level items fallback. Every internal route named anywhere in navigation must exist.

Theme

theme: {
  variant: "default",
  brand: {
    from: "#2f5bff",
    contrast: { apca: 45 }
  },
  palette: {
    surface: "#fcfcff",
    text: "#20232a",
    textSoft: "#626875"
  },
  tokens: {
    "$radius": "6px",
    "$card-radius": "10px",
    "$border-width": "1px",
    "$layout-width": "87.5rem",
    "$content-width": "58rem",
    "$sidebar-width": "17.5rem"
  },
  states: {},
  presets: {
    body: { fontFamily: "Inter, sans-serif" },
    heading: { fontFamily: "Newsreader, serif", fontWeight: 650 }
  },
  styles: {},
  contrastLevel: "auto"
}

The default brand is #315efb; controls use a 6px radius and cards use 10px. Onest is the default body and heading family, while JetBrains Mono is used for code. The default layout is capped at 87.5rem (1400px), matching the Tasty site, with a 58rem reading column and a 17.5rem sidebar. palette supplies semantic Glaze inputs rather than component colors, so the whole interface continues to adapt in dark and high-contrast modes. A requested APCA floor below 45 requires the explicit unsafeContrast: true escape hatch. Learn more in Theme and components.

Markdown

markdown: {
  stripLeadingBadges: true,
  rawHtml: "sanitize",
  strictLanguages: false,
  executablePreviews: true,
  remarkPlugins: [],
  rehypePlugins: []
}

rawHtml accepts "sanitize", "allow", or "reject". Package sources still follow their declared trust level.

Search

search: {
  enabled: true;
}

Search is generated locally with Pagefind during a static build. Disable it for hosts or fixtures that do not need an index.

Components

components: {
  overrides: {
    Header: "./src/components/Header.astro";
  }
}

Component replacement is the advanced escape hatch. Prefer theme tokens and named styles for visual changes that do not need new structure.

Build

build: {
  strict: true,
  ci: process.env.CI === "true",
  base: "/",
  cacheDir: "",
  maxArtifactBytes: 25 * 1024 * 1024,
  maxUnpackedBytes: 100 * 1024 * 1024,
  maxFiles: 10_000,
  maxPathDepth: 24,
  maxAssetBytes: 20 * 1024 * 1024
}

base must match Astro’s base path for project sites such as https://owner.github.io/repository/. Package limits protect builds from unexpected registry artifacts; raise them deliberately for a reviewed package.