Docusaurus

Setup

1. Scaffold Docusaurus into the repo root. If the directory is not empty, scaffold into a temp folder and copy the config files over manually:

   npx create-docusaurus@latest /tmp/docusaurus-scaffold classic --typescript --skip-install

   Copy the config files into your repo (leave your existing docs/ untouched):

   cp /tmp/docusaurus-scaffold/docusaurus.config.ts .
   cp /tmp/docusaurus-scaffold/sidebars.ts .
   cp /tmp/docusaurus-scaffold/package.json .
   cp /tmp/docusaurus-scaffold/tsconfig.json .
   cp -r /tmp/docusaurus-scaffold/src .
   cp -r /tmp/docusaurus-scaffold/static .

2. Install dependencies:

   npm install -g pnpm
   pnpm install

   pnpm blocks build scripts for @swc/core and core-js on first install — approve them:

   pnpm approve-builds

3. Start the dev server:

   pnpm start

Configuration

Update docusaurus.config.ts with your site details — title, URL, organisation. Remove the placeholder footer links and disable the blog if not needed (blog: false).

Deploying via Coolify

Create a new Application resource in Coolify using Deploy Key as the authentication method.

Field	Value
Repository URL	ssh://git@<domain>:<forgejo-ssh-port>/<org>/<repo>.git
Branch	main
Build Pack	Nixpacks
Is it a static site?	✓
Build Command	pnpm build
Publish Directory	build

Forgejo's SSH port is not 22 — the host already uses that. Check the actual mapped port with docker ps | grep forgejo and use that in the URL. For example, if the port is 22222:

ssh://git@code.example.com:22222/org/repo.git

For automatic redeployment on push, copy the webhook URL from the Coolify resource and add it in Forgejo under Settings → Webhooks.

Sidebar

Docusaurus auto-generates the sidebar from the folder structure. Add a _category_.json to each folder to set the label and position:

{
  "label": "My Category",
  "position": 1
}

Add frontmatter to each markdown file to control the sidebar label and order within a category:

---
sidebar_position: 1
sidebar_label: Setup
---