Configuration

The same options work in both setups: passed to the integration in astro.config.mjs, or exported from zenith.config.ts with the CLI. Paths are relative to the project root either way.

import { defineConfig } from 'astro/config';
import zenith from 'zenith-docs';

export default defineConfig({
  site: 'https://docs.example.com',
  integrations: [
    zenith({
      title: 'My Docs',
      description: 'Documentation for my project.',
      github: 'https://github.com/me/my-project',
    }),
  ],
});

import { defineConfig } from 'zenith-docs/config';

export default defineConfig({
  site: 'https://docs.example.com',
  title: 'My Docs',
  description: 'Documentation for my project.',
  github: 'https://github.com/me/my-project',
});

The rest of this documentation shows options in their integration form, zenith({ … }). With the CLI, write the same keys in zenith.config.ts.

Type: string · Default: 'ZenithDocs', or the name of the project directory with the CLI

The site name, shown in the header and appended to page titles.

Type: string · CLI only

The URL the site is deployed at, such as https://docs.example.com. Canonical links, the sitemap, llms.txt and Open Graph images need it to produce absolute URLs. With the integration, set Astro’s own site option instead.

Type: string · CLI only

The path the site is served from, when it is not the root of the domain, such as /docs. With the integration, set Astro’s own base option instead.

Links written from the root in pages, like [Install](/installation/), and the href of cards get the base added at build time, so content never repeats it. Links that already start with the base are left alone.

Type: string

Default meta description, used when a page has none.

Type: { src: string; alt?: string; replacesTitle?: boolean } | false · Default: the ZenithDocs logo

A logo shown next to the title, and on Open Graph images. src is either a path relative to the project root, like ./src/assets/logo.svg, or a public URL, like /logo.png. SVG files are inlined in the page, so they can use currentColor and follow the color scheme. Set replacesTitle to hide the text title, or logo: false to show no logo at all.

Type: string · Default: '/favicon.svg'

URL of the favicon, written from the root of the site: the base path is added for you. When the option is unset and public/favicon.svg does not exist, ZenithDocs serves its own icon at that URL, so a new site never points to a missing file.

Type: string · Default: 'en'

The language of the site, used for the lang attribute and date formatting. Ignored when locales is set.

Type: Record<string, { label: string; lang?: string; dir?: 'ltr' | 'rtl' }>

Languages of the site, keyed by content directory and URL prefix. A root entry is required: it is the default language, served without a prefix. See internationalization.

Type: Record<string, Record<string, string>>

Interface strings, keyed by locale, overriding the built-in ones.

Type: Record<string, { label: string; badge?: string }>

Documentation versions, keyed by content directory and URL prefix. A root entry is required: it is the current version, served without a prefix. See versioning.

Type: string

Repository URL, shown as an icon in the header.

Type: { label: string; href: string }[]

Extra links shown in the header, and at the bottom of the sidebar on small screens.

Type: string · Default: 'src/content/docs', or 'content' with the CLI

Directory holding the content, relative to the project root. With the integration, pass the same value to docsLoader() and metaLoader() as base.

Type: false | { minHeadingLevel?: number; maxHeadingLevel?: number } · Default: { minHeadingLevel: 2, maxHeadingLevel: 3 }

Heading levels listed in the “On this page” column. false removes it from every page; the toc frontmatter field does it for a single page.

Type: boolean · Default: true

Builds a static search index with Pagefind and shows the search dialog. See search.

Type: boolean · Default: true

Generates llms.txt, llms-full.txt and a .md version of every page. See LLMs and AI tools.

Type: boolean · Default: true

Generates a social preview image for every page. See Open Graph images.

Type: Record<string, string>

OpenAPI documents rendered by <APIPage>, keyed by the name used in pages, as paths from the project root. See OpenAPI.

Type: { baseUrl: string } · Default: none, no link

Adds an “Edit this page” link at the bottom of every page. The path of the file, relative to the project root, is appended to baseUrl.

It is off unless set, since readers who cannot write to the repository only land on a fork prompt. It suits docs that welcome outside contributions.

Type: boolean · Default: false

Shows the date of the last commit that touched each page. The site has to be built from a git checkout with its history: a shallow clone, the default in many CI services, dates every page to the last commit.

Type: boolean · Default: true

Shows an info button at the bottom of the sidebar. Hovering or focusing it lists the versions the site was built with: ZenithDocs, Astro, Pagefind when search is on, and Shiki. The versions are read at build time, and the tooltip needs no JavaScript.

Type: 'zenith' | 'slate' | 'terminal' | 'paper' | 'aurora'

Packaged theme: an accent, a backdrop and a font preset that go together, plus a few tokens such as corner radii. accent, backdrop, backdropPosition and fonts still take precedence when you set them. See theming, or try them in the theme builder.

Type: 'emerald' | 'teal' | 'amber' | 'rose' | 'violet' | 'neutral' · Default: 'emerald'

Accent color preset. See theming.

Type: 'dither' | 'aurora' | 'grid' | 'dots' | 'rays' | 'grain' | 'horizon' | 'horizon-glow' | 'glow' | 'none' | boolean · Default: 'dither'

Style of the decorative background at the top of pages. true means dither and false means none. See theming.

Type: 'left' | 'center' | 'right' · Default: 'left'

Side the dither backdrop is anchored to.

Type: 'instrument' | 'geist' | 'newsreader' | 'schibsted' | 'space' | 'atkinson' | 'literata' | boolean · Default: 'instrument'

Font preset, self-hosted through the Astro Fonts API. true means instrument and false falls back to system fonts. Compare them on the typography page.

Type: string[]

Stylesheets loaded after the built-in styles. See theming.

Type: Record<string, string>

Replaces layout components. See component overrides.

Type: Record<string, string | string[]>

Adds components at fixed places of the layout, such as banner or sidebarBottom, without replacing anything. See slots.