Skip to Content

Getting started

Start a documentation site for a project from this base.

This repository is the starting point for the documentation site of each Aiviarium project. A project copies it, edits one file and replaces the brand files. The pages, the theme and the build stay the same.

What you need

  • Node.js 22 or newer, with npm.
  • Git. The "Last updated" date on each page comes from the git history.
  • The brand files of your project, from the brand/ folder of the .github repository.

Start a site

Copy the base

Clone the base into a new folder and start a fresh history.

git clone https://github.com/aiviarium/docs-base hatchery-docs
cd hatchery-docs
rm -rf .git && git init -b main
npm install

You can also copy the files into a docs/ folder of the project repository.

Edit the config

Open docs.config.ts and change the values. The file lists every setting with a comment, and ends with a full example for Hatchery. See Configuration for each field.

Replace the assets

Put the files of your project into public/brand/ and delete the Aiviarium files. The site needs nine files:

FileUse
<name>.svg, <name>-light.svgThe detailed icon on the landing page, at 128 px
<name>-icon.svg, <name>-icon-light.svgThe icon in the header, at 27 px
<name>-16.svg, <name>-16-light.svgThe favicon
<name>-wordmark.svg, <name>-wordmark-light.svgThe faceted wordmark on the landing page
<name>-wordmark-mono.svgThe plain wordmark in the header

The wordmarks are in brand/wordmarks/ and are named <name>.svg there. Rename them as you copy them, or point the config at the names you keep.

Write pages

Pages are MDX files in content/docs/. Delete the sample pages, or keep the component pages as a reference while you write. See Writing pages.

Run it

npm run dev

The site runs at http://localhost:3000. To check the static build, run npm run build and then npm start, which serves out/.

Checks

CommandWhat it checks
npm run typecheckThe TypeScript code and the generated content types
npm run lintESLint over the code
npm run linksLinks between pages, including headings
npm run valeThe prose rules of the organisation
npm run buildThe static export

CI runs all of them on each push and pull request.

Edit on GitHub

Last updated on

On this page