Docusaurus

License	FOSS problems	Maintenance	SSO	Users	Tested
MITPermissive license. Preserve the copyright notice. Applies only to the covered code — your surrounding project can stay under any license.	—	Active	—	—	✅

Evaluation

What it is

Docusaurus is a static site generator built by Meta. Content is written in Markdown files stored in a git repository — there's no database, no admin panel, and no editing UI. The site is built on every push and served as plain HTML. This documentation site runs on it. Astro Starlight is a comparable alternative in the same class.

Why it could be useful

Static sites are fast, cheap to host, and version-controlled by default. Every change is a git commit, which means a full history, easy rollbacks, and the ability to review changes before they go live. It's an excellent fit for technical documentation, developer guides, or any content that benefits from a structured, stable format.

Why not to go for it

Editing requires a code editor and git — or Forgejo if you want a web-based editing interface. It's not suitable for non-technical contributors who expect a WYSIWYG editor and a publish button. There are no user accounts, no permissions, and no collaborative editing — content management is entirely handled through git workflows.

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
---