Skip to main content

API

The rest of this section covers the features that config turns on: Theming, Stores & search, Loaders & exportable configs, SEO & robots, Social images, and Markdown for AI agents. For authoring pages, see Page frontmatter, Menu collection, and Components.

Integration Config

The integration accepts a single config object combining site metadata and optional features. site must be set at the top level of defineConfig — Astro uses it to construct absolute URLs and the integration enforces this:

// astro.config.mjs
export default defineConfig({
  site: "https://your-name.github.io", // required
  integrations: [docsTheme({ ... })],
});
docsTheme({
  // Required: project metadata shown in header/footer
  project: {
    name: "my-project",
    description: "What it does",
    license: { name: "MIT", url: "https://..." },
    // GitHub repo info. Used to derive site URL and GitHub link.
    github: {
      user: "psd-coder", // one of user/organization required
      // organization: "my-org",
      repository: "my-project",
    },
  },

  // Optional: author link in header/footer. Omit to render no author.
  author: {
    name: "Your Name",
    url: "https://x.com/your_handle",
    // icon: path to SVG file rendered inline. Overrides the x.com auto-icon
    // when set, and is required when url is not an x.com URL.
    // icon: "src/assets/author.svg",
  },

  // Optional: additional credits rendered as "& Name" after author in footer
  credits: [{ name: "Evil Martians", url: "https://evilmartians.com/" }],

  // Optional: path to SVG file rendered as the header logo.
  // Replaces the default project name text. The logo slot in Layout still overrides this.
  // logo: "src/assets/logo.svg",

  // Optional: show theme picker in header to choose hue + saturation interactively.
  // Use it to find the right values, then set theme.hue / theme.saturation
  // and remove this.
  themePicker: true,

  // Optional: enable Astro ViewTransitions. Default: true.
  // clientRouter: false,

  // Optional: enable full-text search UI in header. Default: true.
  // search: false,

  // Optional: robots.txt Content-Signal directive (contentsignal.org). Each flag
  // maps to yes/no in the "User-agent: *" block. All default to true.
  // robots: { contentSignal: { search: true, aiTrain: false, aiInput: false } },

  // Optional: theme tokens. Hue feeds CSS variables and the auto OG template.
  theme: {
    // hue: 220,
    // Syntax highlighting themes (overrides adaptive hue-based theme)
    // shiki: { light: "github-light", dark: "github-dark" },
    // Inject bundled Martian Grotesk + Mono fonts. Default: true.
    // fonts: false,
    // CSS files to inject into every page. Paths relative to project root.
    // customCss: ["src/styles/custom.css"],
  },

  // Optional: SEO / meta settings
  meta: {
    // HTML lang attribute. Default: "en".
    // lang: "fr",
    // Appended as " | {suffix}" to every sub-page <title>. false = no suffix.
    // Default: project.name.
    // titleSuffix: "My Project — Docs",
    // titleSuffix: false,
    // Full <title> for the root/index page, bypassing the normal "{page} | {suffix}" pattern.
    // Default: "{project.name} Documentation".
    // mainPageTitle: "My Project — Fast & Simple",
    // Source icon(s) for favicons, apple-touch-icon, and webmanifest.
    // String form: single 512x512 PNG/SVG used for all sizes.
    icon: "src/assets/icon.svg",
    // Object form: separate sources. `favicon` is used for tiny renders
    // (favicon.svg, favicon.ico); `manifest` is used for 96px and up.
    // icon: {
    //   favicon: "src/assets/favicon.svg",
    //   manifest: "src/assets/icon-detailed.svg",
    // },
    // Open Graph image. Defaults to true when unset. Three forms:
    //   string   -> path to PNG, served at /og.png
    //   true     -> built-in template, uses top-level `logo` if set
    //   object   -> override any of: template, logo, title, description
    // Object fields (all optional):
    //   logo:        string path / false (opt out) / absent (uses top-level `logo`)
    //   template:    path to .ts default-exporting OgTemplateFn
    //   title:       replace project.name shown on the card
    //   description: replace project.description shown on the card
    // og: { image: { logo: "src/assets/og-logo.svg", title: "My App" }, imageAlt: "Alt" },
    // Twitter card. Image defaults to og.image.
    // twitter: { site: "@my_org", creator: "@me" },
  },

  // Optional: docs collection settings (all fields optional, sensible defaults applied)
  docs: {
    directory: "src/content/docs", // default; also controls defineDocsCollections() glob base
    renderDefaultPage: true, // default; set false to ship your own [...slug].astro
    // Optional: header navigation links (href accepts "/api" or "api").
    // `attrs` is spread onto the rendered <a> (target, rel, data-*, ...).
    navLinks: [
      { href: "/", label: "Overview" },
      { href: "/api", label: "API" },
      { href: "https://astro.build", label: "Astro", attrs: { target: "_blank" } },
    ],
    // Optional: extra entries for search index + llms.txt from non-collection pages.
    // Path to a module that default-exports ExtraEntry[] or () => Promise<ExtraEntry[]>.
    // extraEntries: "./src/extra-entries.ts",
  },
});

What the integration does

  1. Stores config in a virtual module (virtual:pigment-config) so components read it automatically
  2. Requires site in astro.config.mjs; auto-sets base from GitHub config (/repo/ in CI, / in dev)
  3. Configures markdown on Astro’s Sätteri processor: heading ids plus a self-link anchor on every heading, with GitHub Flavored Markdown (tables, strikethrough, task lists) and smart typography enabled as native features. Both apply to .md and .mdx with no consumer config
  4. Injects an adaptive Shiki theme that derives syntax colors from --theme-hue (based on Catppuccin, hue-rotated via OKLch). Override with theme.shiki to use fixed themes instead.
  5. Injects PostCSS preset-env (nesting, custom-media, media-query-ranges)
  6. Injects sitemap + llms.txt, llms-full.txt, [slug].md routes
  7. Injects /[...slug] page that renders docs from the content collection (opt out with docs.renderDefaultPage: false)
  8. When search: true (default): injects /search-index.json and renders a search input in the Layout header
  9. When clientRouter: true (default): enables Astro View Transitions via <ClientRouter />
  10. When meta.icon is configured: generates favicons (svg, ico, 96x96 png), apple-touch-icon, webmanifest + manifest icons (192x192, 512x512)
  11. Always serves /robots.txt (permissive, with a Content-Signal: directive and Sitemap: pointing at /sitemap-index.xml)
  12. Always serves /og.png (built-in template by default, or whatever meta.og.image specifies) and emits <meta property="og:image"> at 1200x630
  13. Twitter falls back to the OG image; emits summary_large_image Twitter card tags. Override with meta.twitter.image to use a different mode/path
Theme copied