Installation

Add ZenithDocs to a new or existing Astro project.

On this page

ZenithDocs needs Astro 7 and Node.js 22.18 or later. It is not published to the npm registry: it installs straight from its GitHub repository, and needs Git on your machine for that.

Create a new site

One command creates a ready-to-run project:

npm

npx github:AymericChaverot/zenith-docs create my-docs

pnpm

pnpm dlx --allow-build=esbuild github:AymericChaverot/zenith-docs create my-docs

It is the same zenith command you then use in the project, run straight from GitHub. The first run downloads ZenithDocs and Astro, which can take a minute on a machine that has never installed them; later runs come from the cache. pnpm needs --allow-build=esbuild because it blocks install scripts that you have not approved.

Template	What you get
`cli`, the default	A `zenith.config.ts` and a `content/` folder, run by the CLI
`astro`	An Astro project with the integration, ready for pages of your own

Run in a terminal, the command asks where to put the site, its title, the template, a packaged theme, whether to add a Dockerfile, and whether to install the dependencies:

┌   ZenithDocs  let’s set up your documentation
│
◇  Where should the site go?
│  acme-docs
│
◇  What is the site called?
│  Acme Handbook
│
◇  Which template?
│  cli
│
◆  Which theme?
│  ● default (Keep the defaults)
│  ○ zenith
│  ○ slate
│  ○ terminal
│  ○ paper
│  ○ aurora
└

The directory is given as an argument or typed at the first question. It has to be empty, apart from dotfiles such as .git. Once the files are written, the dependencies are installed if you said yes, with the package manager that ran the command, and the next steps are printed.

Every answer has a flag, for scripts and CI: --template, --title, --theme, --docker and --install. Add --yes to skip the questions and take the defaults for anything not given: the directory is then zenith-docs, and nothing is installed unless --install is set. Outside a terminal, as in CI, the questions are skipped the same way.

Add to an Astro project

ZenithDocs is an Astro integration, so an existing project only needs a few steps.

Install the package

npm

npm install github:AymericChaverot/zenith-docs

pnpm

pnpm add github:AymericChaverot/zenith-docs

This follows the main branch. Add a release tag to pin a version, as in github:AymericChaverot/zenith-docs#v0.2.1: sites made with create are pinned that way from the start. The releases list every tag and what changed.

Add the integration

astro.config.mjs

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

export default defineConfig({
  integrations: [
    zenith({ title: 'My Docs' }),
  ],
});

Define the content collections

ZenithDocs reads pages from a docs collection and navigation metadata from a meta collection.

src/content.config.ts

import { defineCollection } from 'astro:content';
import { docsLoader, docsSchema, metaLoader, metaSchema } from 'zenith-docs/content';

export const collections = {
  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
  meta: defineCollection({ loader: metaLoader(), schema: metaSchema() }),
};

Write your first page

src/content/docs/index.mdx

---
title: Welcome
description: The first page of my documentation.
---

Hello, world!

Run astro dev and open the site: your page is served at the root, with the sidebar, table of contents and dark mode already set up.