# Installation

> Add ZenithDocs to a new or existing Astro project.

Source: https://aymericchaverot.github.io/zenith-docs/installation/

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](https://github.com/AymericChaverot/zenith-docs), and needs Git on your machine for that.

## Create a new site

One command creates a ready-to-run project:

<Tabs items={['npm', 'pnpm']} groupId="package-manager" persist>
  <Tab value="npm">
    ```sh
    npx github:AymericChaverot/zenith-docs create my-docs
    ```
  </Tab>
  <Tab value="pnpm">
    ```sh
    pnpm dlx --allow-build=esbuild github:AymericChaverot/zenith-docs create my-docs
    ```
  </Tab>
</Tabs>

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](/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](/customization/theming/#packaged-themes), whether to add a [Dockerfile](/deployment/#docker), and whether to install the dependencies:

```txt
┌   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.

<Steps>

### Install the package

<Tabs items={['npm', 'pnpm']} groupId="package-manager" persist>
  <Tab value="npm">
    ```sh
    npm install github:AymericChaverot/zenith-docs
    ```
  </Tab>
  <Tab value="pnpm">
    ```sh
    pnpm add github:AymericChaverot/zenith-docs
    ```
  </Tab>
</Tabs>

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](https://github.com/AymericChaverot/zenith-docs/releases) list every tag and what changed.

### Add the integration

Register ZenithDocs in your Astro configuration and give your site a title.

```js title="astro.config.mjs"

  integrations: [
    zenith({ title: 'My Docs' }), // [!code ++]
  ],
});
```

### Define the content collections

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

```ts title="src/content.config.ts"

  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
  meta: defineCollection({ loader: metaLoader(), schema: metaSchema() }),
};
```

### Write your first page

```mdx title="src/content/docs/index.mdx"
---
title: Welcome
description: The first page of my documentation.
---

Hello, world!
```

</Steps>

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.

:::note
Pages are prerendered, so `astro build` outputs a fully static site that can be hosted anywhere.
:::