Astro Config

An Astro configuration factory for theholocron docs sites.

Installation

pnpm add -D @theholocron/astro-config

defineConfig() always wires in the @astrojs/react integration (needed by @theholocron/docs-theme consumers that render React components in their docs), so @astrojs/react, react, and react-dom are declared as peerDependencies — install them alongside this package:

pnpm add -D @astrojs/react react react-dom

Without them, pnpm install still succeeds (with an unmet-peer warning), but astro build/astro dev fails at build time trying to resolve @astrojs/react/server.js — Vite resolves that import from the consuming project's own node_modules, not from this package's, so the peer can't be satisfied transitively.

Usage

Pass starlight and docsTheme from your own imports alongside the docs config. This keeps Astro's module loader in control of those framework imports:

// astro.config.ts
import starlight from "@astrojs/starlight";
import { docsTheme } from "@theholocron/docs-theme";
import { defineConfig } from "@theholocron/astro-config";
import clientsConfig from "@theholocron/clients-docs";

export default defineConfig({
  docs: clientsConfig,
  importMetaUrl: import.meta.url,
  starlight,
  docsTheme,
});

Custom sidebar label

By default the sidebar group label is derived from docs.sidebar[1].label. Override it when the label differs:

import starlight from "@astrojs/starlight";
import { docsTheme } from "@theholocron/docs-theme";
import { defineConfig } from "@theholocron/astro-config";
import holocronConfig from "@theholocron/holocron-docs";

export default defineConfig({
  docs: holocronConfig,
  importMetaUrl: import.meta.url,
  starlight,
  docsTheme,
  sidebarLabel: "Reference",
});

What it generates

• site — https://theholocron.github.io
• base — /${docs.slug}
• Starlight integration with the @theholocron/docs-theme plugin
• GitHub social link to https://github.com/theholocron/${docs.slug}
• Sidebar with an Overview link and an autogenerated sub-pages group