Skip to main content

Environment Setup

This guide walks you through setting up the Rhino Group Documentation Platform on your local machine for the first time.

Prerequisites​

Before you begin, install these tools:

ToolVersionPurpose
Node.js≥ 20.0Runtime for Docusaurus
npm≥ 10Package manager (comes with Node.js)
GitLatestVersion control
VS CodeLatestRecommended editor

Installing Node.js​

Download from nodejs.org or use NVM for Windows:

# With NVM for Windows
nvm install 20
nvm use 20
node --version    # Should show v20.x.x
npm --version     # Should show v10.x.x

Installing Git​

Download from git-scm.com or install via winget:

winget install Git.Git

Step 1: Clone the Repository​

Open PowerShell and navigate to your workspace directory:

cd Z:\Repos
git clone https://github.com/Rhino-Group/docs.git
cd docs

Step 2: Install Dependencies​

Install all required npm packages:

npm install

This downloads Docusaurus and all plugins. It may take 1-2 minutes.

Step 3: Run the Development Server​

Start the local development server:

npm run start

This will:

  • Build the site in development mode
  • Open http://localhost:3000 in your browser
  • Watch for file changes and auto-reload
tip

The dev server only compiles pages as you navigate to them, so startup is fast even with hundreds of pages.

You should see the homepage with all client cards. Try navigating to different documentation pages to verify everything works.

Step 4: Test a Production Build​

Before making changes, verify that a full production build works:

npm run build

This command:

  • Compiles all pages
  • Reports any broken links
  • Creates a build/ directory with static HTML

If there are errors, check the output for details. The build must complete successfully before deploying.

Step 5: Serve the Production Build Locally​

To test the production build locally:

npm run serve

This serves the build/ directory at http://localhost:3000. Use this to verify that the production build looks correct before deploying.

Project Structure​

Here's what the key directories contain:

docs/
├── clients/                    ← All client documentation (markdown files)
│   ├── gsm-outdoors/
│   │   ├── index.md           ← Client landing page
│   │   ├── middleware/
│   │   ├── stealthcam/
│   │   └── walkers/
│   ├── scottsdale-mint/
│   └── rhinogroup/
├── src/                        ← React components, homepage, CSS
│   ├── components/
│   ├── pages/
│   └── theme/
├── plugins/                    ← Custom Docusaurus plugins
├── typesense/                  ← Search server config
├── scripts/                    ← Utility scripts
├── docusaurus.config.ts        ← Main config (auto-discovers clients)
└── package.json                ← npm dependencies and scripts

Useful Commands​

CommandPurpose
npm run startStart dev server with hot-reload
npm run buildProduction build (checks for broken links)
npm run serveServe the production build locally
npx docusaurus clearClear build cache (fixes stale data issues)
.\scripts\create-new-client-site.ps1Interactive wizard to create a new client/site

Install these extensions for the best authoring experience:

  • MDX (by unified) — Syntax highlighting for MDX files
  • Markdown All in One (by Yu Zhang) — Markdown shortcuts and preview
  • GitHub Copilot — AI-assisted authoring (see AI-Assisted Authoring)
  • ESLint — JavaScript/TypeScript linting
  • Prettier — Code formatting

Troubleshooting​

Port 3000 Already in Use​

If you get an error about port 3000 being in use:

# Kill the process using port 3000
npx kill-port 3000

# Or use a different port
npm run start -- --port 3001

Build Fails with Memory Error​

If the build runs out of memory:

# Increase Node memory limit
$env:NODE_OPTIONS="--max-old-space-size=4096"
npm run build

Stale Build Cache​

If you see outdated content or weird errors:

# Clear the build cache
npx docusaurus clear

# Then rebuild
npm run build

Next Steps​

Now that your environment is set up:

  1. Edit existing documentation — Modify markdown files and rebuild
  2. Add new content — Create new pages, clients, and sites
  3. Use AI-assisted authoring — Copilot prompts for faster documentation