Skip to main content

Website Development Setup

Purpose: For contributors, shows how to run and update the Docusaurus documentation site used by this repository.

What you'll have at the end​

A locally running Docusaurus site where you can preview docs changes, update navigation, and verify the site builds cleanly before pushing.

Prerequisites​

  • Node.js >=24.8.0
  • Bun (latest)
  • Git

Check the installed versions:

node --version
bun --version

Step 1: Install dependencies​

From the repository root:

bun install

This installs Docusaurus, React, and the documentation tooling declared in package.json.

Step 2: Start the local site​

Use either the package script or the Makefile shortcut:

bun run start

or:

make start

The site runs at http://localhost:9000. Docusaurus watches for file changes and reloads the page automatically.

Step 3: Understand the site structure​

opencenter-docs/
├── docs/                  # Documentation content
├── blog/                  # Blog posts
├── src/                   # React components and custom pages
├── static/                # Static assets copied as-is
├── docusaurus.config.ts   # Site configuration
├── sidebars.js            # Manual sidebar definitions
├── package.json           # Scripts and dependencies
└── Makefile               # Common development shortcuts

Key locations:

  • docs/ contains the Markdown documentation pages rendered by Docusaurus.
  • _category_.json files inside docs/ define autogenerated category metadata.
  • sidebars.js defines the main documentation sidebar structure.
  • docusaurus.config.ts controls site-wide behavior such as navbar items, search, broken-link handling, and themes.
  • src/ contains the custom React UI for the site shell and homepage.

Step 4: Add or edit content​

Documentation pages use Markdown with frontmatter. Add new pages under the appropriate folder in docs/.

Example:

---
id: my-new-page
title: "My New Page"
description: Short summary for search and previews.
doc_type: tutorial
audience: "contributors"
tags: [example]
---

Page content here.

If the page should appear in the main navigation, update sidebars.js or the relevant category metadata.

Step 5: Verify before pushing​

Run the basic checks from the repository root:

bun run prettier:check
bun run build

Verify that:

  • The page renders correctly at http://localhost:9000
  • Navigation and sidebar entries point to the right page
  • The production build completes without broken links or broken anchors

Check your work​

bun run start
bun run build

The local preview should load on port 9000, and the production build should write static output to build/.

Troubleshooting​

SymptomFix
bun: command not foundInstall Bun via curl -fsSL https://bun.sh/install | bash, then rerun bun install.
node version is too oldUpgrade Node to >=24.8.0 to match package.json.
Page does not appear in navUpdate sidebars.js or the relevant _category_.json entry.
Build fails on broken linksFix the referenced path or anchor; this site is configured to fail on broken links and anchors.
Config changes do not appear immediatelyRestart the local dev server after editing docusaurus.config.ts or sidebar structure.

Next steps​