Skip to content
Tasty Docs

Configuration reference

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

import { defineDocsConfig } from "tasty-docs";


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:

navigation: [
  "/",
  {
    label: "Start here",
    items: ["/getting-started", "/configuration"],
  },
  {
    label: "Reference",
    autogenerate: { directory: "/reference" },
  },
  {
    label: "Playground",
    link: "https://example.com/playground",
  },
];

Every internal route named in navigation must exist.

Theme

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

The default brand is #315efb. 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: {
  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.