Skip to main content

Docs Portal: Local Preview Guide

This guide explains how to preview the WEP Digital Hub documentation portal (powered by Docusaurus 3.7) on your local machine.

Prerequisites​

  • Node.js v18 or later (tested with v24)
  • npm (bundled with Node.js)
  • Repository cloned locally

Quick Start​

cd docs-portal

# First time only: install dependencies
npm install

# Build the static site
npm run build

# Serve locally on port 3001
npm run serve -- --port 3001 --no-open

Open http://localhost:3001/ in your browser.

Why Static Mode Only (No Hot-Reload)​

The npm run start command (Docusaurus dev server with hot-reload) does not work on this project. The reason is architectural:

The Docusaurus config uses docs.path: '../' to read markdown files from the repository root. This means the dev server's file watcher tries to monitor the entire repo directory, including docs-portal/node_modules/ (~50,000+ files). This exceeds macOS kernel limits and causes:

Error: EMFILE: too many open files, watch

Workarounds That Were Tested and Failed​

ApproachResult
ulimit -n 65536No effect — macOS kernel limit, not shell limit
WATCHPACK_POLLING=trueSame EMFILE on initial scan
Custom webpack watchOptions.ignored pluginCrash occurs before webpack loads
Symlinked content/ directoryAvoids EMFILE but breaks Docusaurus routing

Implication​

After editing any markdown file in the repository, you must rebuild to see changes:

npm run build && npm run serve -- --port 3001 --no-open

💡 Tip for Agents: Use the /docusaurus-local workflow to automate this process with turbo commands.

Troubleshooting​

npm install fails with EPERM​

If you see:

npm error code EPERM
npm error Your cache folder contains root-owned files

Use a temporary cache directory:

npm install --cache /tmp/npm-cache-docusaurus

Port already in use​

If port 3001 is busy, use a different one:

npm run serve -- --port 3002 --no-open

The build may show warnings like Broken link on source page path = /docs/.... These are pre-existing issues with footer links and do not prevent the build from succeeding. The config uses onBrokenLinks: 'warn' (not 'throw').

Architecture Notes​

The Docusaurus portal is configured in docs-portal/:

FilePurpose
docusaurus.config.jsMain config — reads docs from ../ (repo root)
sidebars.jsAuto-generated sidebars per section
src/pages/index.jsCustom homepage with feature cards
src/css/custom.cssTheme customization
static/Static assets (logo, favicon)

The docs.include pattern in the config controls which directories are included:

include: [
  '00-Meta/**/*.md',
  '01-Architecture/**/*.md',
  '02-Processes/**/*.md',
  '03-Security/**/*.md',
  '04-Systems/**/*.md',
  'README.md',
]

Adding a new top-level section requires updating both this include array and the sidebars.js file.