Appendix B: Build Process Overview

What Happens Behind the Scenes

When you run npm start or npm run build, a series of automated scripts work behind the scenes to prepare your documentation for display. This guide explains what's happening so you understand the "magic" - but you don't need to modify anything described here. These processes are fully automated.

For Contributors

You don't need to understand the technical details of these scripts to contribute documentation. This section is provided for transparency and troubleshooting. Focus on creating great content - the automation handles the rest!

The Build Workflow

When You Run `npm start`

Here's what happens step-by-step:

npm start
    ↓
1. Generate Report ID Map
    ↓
2. Generate Sidebars
    ↓
3. Generate Counters
    ↓
4. Generate Versions
    ↓
5. Generate Event Tree TOC
    ↓
6. Start Docusaurus Dev Server
    ↓
Site available at http://localhost:3000

Each step is essential for the documentation site to function correctly.

The Five Automation Scripts

1. Report ID Map Generator

Script: scripts/generateReportIdMap.js

What it does:

Scans the entire docs/ folder structure
Creates a unique ID for each documentation set
Maps folder paths to report IDs

Output: src/reportIdMap.js (auto-generated)

Example mapping:

docs/desktop-applications/lifesim/users-guide/v1.0/
    ↓
lifesim-users-guide-v1-0

Why it matters:

Report IDs are used by all other scripts to track documents
Enables automatic numbering and cross-referencing
Keeps internal organization consistent

What you need to know:

Never edit src/reportIdMap.js directly
The script creates IDs automatically from your folder structure
IDs are used internally - you'll rarely see them

Script: scripts/generateSidebars.js

What it does:

Scans docs/ folder structure
Reads front matter from each .mdx file
Builds hierarchical navigation structure
Determines collapsed/expanded state
Orders items based on numeric prefixes

Output: sidebars.js (auto-generated)

How it works:

Folder structure:

docs/
├── desktop-applications/
│   ├── lifesim/
│   │   └── users-guide/
│   │       └── v1.0/
│   │           ├── 00-document-info.mdx
│   │           ├── 01-preface.mdx
│   │           └── 02-introduction.mdx

Becomes sidebar:

Desktop Applications (expanded)
  └── LifeSim (collapsed)
      └── User's Guide v1.0 (collapsed)
          ├── Document Information (collapsed)
          │   ├── Document Info
          │   └── Version History
          ├── Main Report (expanded)
          │   ├── Preface
          │   └── Introduction

Sidebar rules:

Files starting with 00- go into "Document Information" (collapsed)
Files starting with 01-99 go into "Main Report" (expanded)
Appendix detection is based on file content
Items are sorted numerically by prefix

What you need to know:

Never edit sidebars.js directly - it will be overwritten
Use numeric prefixes (01-, 02-, etc.) to control order
The title from front matter becomes the sidebar label
Run npm start to regenerate sidebar after structural changes

3. Counters Generator

Script: scripts/counters.js

What it does:

Scans all .mdx files in each document
Finds components with unique keys:
- <Figure figKey="...">
- <TableVertical tableKey="...">
- <Equation equationKey="...">
- <Citation citationKey="...">
Assigns sequential numbers to each type
Stores mappings in JSON files

Output: static/counters/<report-id>.json (one per document)

Example counter file:

{
  "figures": {
    "fig-workflow": {
      "figNumber": 1,
      "parentDocId": "lifesim-users-guide-v1-0",
      "docId": "02-methodology.mdx"
    },
    "fig-results": {
      "figNumber": 2,
      "parentDocId": "lifesim-users-guide-v1-0",
      "docId": "03-results.mdx"
    }
  },
  "tables": {
    "table-parameters": {
      "tableNumber": 1,
      "parentDocId": "lifesim-users-guide-v1-0",
      "docId": "02-methodology.mdx"
    }
  },
  "equations": {
    "eq-risk": {
      "equationNumber": 1,
      "parentDocId": "lifesim-users-guide-v1-0",
      "docId": "02-methodology.mdx"
    }
  }
}

How numbering works:

Script reads files in alphabetical order (01-, 02-, 03-, ...)
Encounters first <Figure figKey="fig-workflow"> → assigns Figure 1
Encounters second <Figure figKey="fig-results"> → assigns Figure 2
Tables, equations, and citations are numbered separately

What you need to know:

Always use unique keys for each component
Numbers are assigned automatically based on order of appearance
If numbering seems wrong, run npm run counters to regenerate
Cross-references work because keys map to numbers

4. Versions Generator

Script: scripts/versions.js

What it does:

Scans all documents for version folders (v1.0, v1.1, v2.0, etc.)
Determines the latest version for each document
Creates version lists for version selector dropdown
Generates configuration for Algolia search crawler

Output: Three JSON files in static/versions/

latestVersions.json - Maps each document to its latest version

{
  "lifesim-users-guide": "v1.1",
  "rmc-rfa-users-guide": "v2.0"
}

versionList.json - All available versions per document

{
  "lifesim-users-guide": ["v1.0", "v1.1"],
  "rmc-rfa-users-guide": ["v1.0", "v1.5", "v2.0"]
}

algoliaCrawlerVersions.json - Search indexing configuration

What you need to know:

Latest version is displayed by default when users visit a document
Version selector dropdown is populated automatically
Simply create new version folders (v1.1, v2.0) - the script detects them
Versions are sorted semantically (v1.9 comes before v1.10)

5. Event Tree TOC Generator

Script: scripts/generateEventTreeTOC.js

What it does:

Specialized script for the RMC Typical Event Tree Database document
Scans event tree documentation folders
Groups files into categories based on numeric prefixes
Builds a table of contents structure

Output: src/data/eventTreeToc.json

What you need to know:

Only relevant if working on the Event Tree Database document
Most contributors won't interact with this script
Runs automatically during build process

What Gets Generated (Don't Edit These!)

These files and folders are created automatically by the scripts above:

Auto-Generated Files

File/Folder	Generated By	Purpose
`sidebars.js`	generateSidebars.js	Navigation structure
`src/reportIdMap.js`	generateReportIdMap.js	Document ID mappings
`static/counters/*.json`	counters.js	Figure/table/equation numbering
`static/versions/*.json`	versions.js	Version management
`src/data/eventTreeToc.json`	generateEventTreeTOC.js	Event tree navigation
`.docusaurus/`	Docusaurus	Build cache
`build/`	Docusaurus	Production output

How to Tell If a File is Auto-Generated

Check .gitignore in the project root. If a file is listed there, it's auto-generated and shouldn't be manually edited.

Common auto-generated patterns:

sidebars.js
src/reportIdMap.js
src/data/
static/counters/
static/versions/
.docusaurus/
build/
node_modules/

The Docusaurus Build Process

After the five scripts complete, Docusaurus takes over:

Development Mode (`npm start`)

Pre-build phase:
- Runs all 5 automation scripts
- Validates configuration
- Loads plugins
Build phase:
- Compiles MDX files to React components
- Processes CSS and Tailwind utilities
- Optimizes images
- Generates routes
Dev server:
- Starts local server on port 3000
- Enables hot reload (changes appear automatically)
- Provides error messages in browser
Watch mode:
- Monitors files for changes
- Recompiles changed files
- Updates browser automatically

Production Mode (`npm run build`)

Pre-build phase:
- Runs all 5 automation scripts
- Validates all links and references
- Checks for broken assets
Build phase:
- Compiles all MDX to static HTML
- Minifies CSS and JavaScript
- Optimizes and compresses images
- Generates sitemap
- Creates search index
Output:
- Static files in build/ folder
- Ready for deployment to GitHub Pages
- No server required (static site)

When Scripts Run

Automatically

Scripts run automatically during:

npm start      # Runs all 5 scripts, then starts dev server
npm run build  # Runs all 5 scripts, then builds for production

Common Scenarios

Scenario 1: I Added a New Chapter

What happens automatically:

Next npm start runs generateSidebars.js
New file is detected and added to sidebar
Numeric prefix determines position
Front matter title becomes sidebar label

You don't need to:

Edit sidebars.js
Run any commands manually
Restart server (hot reload handles it)

Scenario 2: Figure Numbers Are Wrong

What to do:

Check that each figure has a unique figKey
Verify files are numbered correctly (01-, 02-, 03-)
Restart the dev server npm start
Refresh browser

What's happening:

Counters are generated in file order
Duplicate keys cause issues
Out-of-order files result in unexpected numbering

Scenario 3: Created New Version Folder

What happens automatically:

Next npm start runs versions.js
New version is detected
Version selector dropdown is updated
Latest version determination is updated

You don't need to:

Edit any version files
Manually update version dropdowns
Configure anything

Scenario 4: Build Fails with "Cannot find module"

Possible causes:

Missing import in MDX file
Component doesn't exist
Typo in component name
Cache corruption

Solutions:

npm run clear     # Clear Docusaurus cache
npm start         # Rebuild from scratch

Understanding Build Output

Terminal Output During `npm start`

You'll see output like this:

> npm run report-map && npm run sidebars && ...

[Report Map] Scanning docs folder...
[Report Map] Generated mappings for 45 documents
[Report Map] ✓ src/reportIdMap.js

[Sidebars] Scanning docs folder...
[Sidebars] Generated sidebar with 12 categories
[Sidebars] ✓ sidebars.js

[Counters] Scanning docs folder...
[Counters] Processing lifesim-users-guide-v1-0...
[Counters]   - 15 figures
[Counters]   - 8 tables
[Counters]   - 12 equations
[Counters] ✓ Generated 45 counter files

[Versions] Scanning for version folders...
[Versions] Found 73 versions across 45 documents
[Versions] ✓ Generated version files

[Docusaurus] Starting development server...
[Docusaurus] Compiled successfully!
[Docusaurus] ✓ http://localhost:3000

What each message means:

✓ = Success
Numbers indicate how many items were processed
"Compiled successfully!" means site is ready
URL indicates where to view the site

Build Errors

If you see errors, read the message carefully:

Example error:

ERROR in ./docs/desktop-applications/lifesim/users-guide/v1.0/03-methodology.mdx
Module not found: Can't resolve '@site/src/components/Figre'

How to read it:

File location: docs/.../03-methodology.mdx
Problem: Can't resolve component
Issue: Typo in import (Figre should be Figure)

Performance Notes

Build Times

Typical build times on modern hardware:

npm start (first run): 20-60 seconds
- 5-10 seconds for automation scripts
- 15-50 seconds for Docusaurus compilation
npm start (subsequent): 5-15 seconds
- Docusaurus uses cached builds
- Only changed files are recompiled
npm run build: 1-3 minutes
- Full production build
- All optimizations applied
- No caching used

Hot Reload Speed

When editing files with dev server running:

MDX content changes: ~1-2 seconds
Component changes: ~2-5 seconds
Configuration changes: Requires restart

Optimization Tips

Faster Development

Clear cache if issues:

npm run clear
npm start

Faster Builds

Production builds are slower but create optimized sites:

Only build for production when ready to deploy
Use npm start for development (much faster)

Configuration Files (Reference Only)

These files configure the build process but are rarely modified:

`docusaurus.config.js`

Purpose: Main site configuration

Contains:

Site URL and base path
Theme configuration
Plugin settings
Navigation bar setup
Footer configuration
Search integration (Algolia)
Analytics setup (Google)

When to modify: Coordinate with site administrators

`package.json`

Purpose: Project dependencies and scripts

Contains:

List of all npm packages used
Script definitions (start, build, deploy)
Node.js version requirements
Project metadata

When to modify: Adding new dependencies (rare for contributors)

`tailwind.config.js`

Purpose: Styling configuration

Contains:

Custom color definitions
Font configurations
Breakpoint settings
Tailwind utility extensions
Dark mode configuration

When to modify: Coordinate with site administrators for styling changes

Deployment to Production (Administrator-Level Only)

Important - Administrators Only

Deployment is an administrator-level task. Contributors should focus on creating and editing documentation content using npm start for local testing. Site administrators will handle all building and deployment to production.

Contributors do NOT need to run npm run build or npm run deploy. If you encounter any issues while testing locally with npm start, contact the repository administrator rather than attempting to troubleshoot build processes.

Unauthorized deployment may overwrite live documentation and disrupt the website.

Deployment Workflow

If you are a site administrator deploying to GitHub Pages, follow these steps:

Step 1: Build for Production

npm run build

What this does:

Runs all 5 automation scripts (Report ID Map, Sidebars, Counters, Versions, Event Tree TOC)
Compiles all MDX files to static HTML
Minifies CSS and JavaScript
Optimizes and compresses images
Generates sitemap for search engines
Creates search index
Validates all links and references
Outputs production-ready files to build/ directory

Expected output:

Success! Generated static files in "build".

You can now deploy the "build" folder to your static hosting service.

Step 2: Test the Production Build Locally

Before deploying to production, always test the build locally:

npx serve build

This serves the production build locally (typically at http://localhost:3000 or http://localhost:5000).

Important verification steps:

✓ All pages load correctly
✓ Navigation works as expected
✓ Images and static assets display properly
✓ Links are not broken
✓ Search functionality works (if configured)
✓ Version selector functions correctly
✓ No console errors appear in browser developer tools
✓ Mobile responsive design works
✓ Dark mode toggle works (if applicable)

Press Ctrl+C to stop the server when testing is complete.

Common Production Issues

Production builds can reveal issues not present in development:

Missing dependencies: Components that work in dev but fail in production
Image path errors: Relative paths that break during build
Link issues: Internal links that don't resolve correctly
Memory errors: Large documents that exceed build limits

Always test locally before deploying to catch these issues.

Step 3: Set GitHub User Environment Variable

$env:GIT_USER="USACE-RMC"

Why this is needed:

The deploy script needs git credentials to push to the gh-pages branch
GIT_USER specifies the GitHub organization/user account
This variable is only needed for the current PowerShell session

Step 4: Deploy to GitHub Pages

npm run deploy

What this does:

Runs npm run build again (to ensure latest changes)
Pushes the contents of build/ directory to gh-pages branch
GitHub Pages automatically serves the updated site
Site updates are live within 1-2 minutes

Expected output:

Published

Build Redundancy

Note that npm run deploy automatically runs the build process, so technically Step 1 is redundant if you skip testing. However, testing the production build before deployment (Steps 1-2) is strongly recommended to catch any production-specific issues before they go live.

Post-Deployment Verification

After deploying, verify the live site:

Visit the production URL: https://software.rmc.usace.army.mil (or your configured domain)
Spot check critical pages:
- Homepage loads correctly
- Recently updated documentation displays properly
- Navigation works across all sections
- Search returns relevant results
Check for errors:
- Open browser developer console (F12)
- Look for any console errors (red messages)
- Verify no 404 errors for images or assets
Test on multiple devices:
- Desktop browser
- Mobile browser
- Different browsers (Chrome, Firefox, Edge)

Troubleshooting Deployment Issues

Deployment fails with authentication error:

Verify GIT_USER is set correctly
Check that you have push permissions to the repository
Ensure Git credentials are configured

Build succeeds but site doesn't update:

Wait 2-3 minutes for GitHub Pages to rebuild
Clear browser cache and hard refresh (Ctrl+Shift+R)
Check GitHub repository settings for Pages configuration

Production site shows errors not present in development:

Review build output for warnings
Test production build locally with npx serve build
Check browser console for specific error messages

Deployment takes too long or times out:

Check internet connection
Verify GitHub is accessible (not blocked by firewall)
Try deploying again - temporary network issues can cause failures

Deployment Best Practices

Before deploying:

✓ Test all changes locally with npm start
✓ Commit all changes to Git
✓ Pull latest changes from remote repository
✓ Run npm run build and test locally
✓ Review build output for warnings

During deployment:

✓ Deploy during low-traffic periods when possible
✓ Announce significant updates to team
✓ Keep terminal window open to monitor progress

After deployment:

✓ Verify live site immediately
✓ Check for broken links or missing assets
✓ Test search functionality
✓ Monitor for user feedback

Rollback Procedure

If deployment causes issues:

Identify last working commit:
```
git log --oneline
```

Revert to previous version:

git checkout <commit-hash>
npm run deploy

Fix issues in development:
- Debug the problem locally
- Test thoroughly before redeploying
- Consider creating a branch for testing
Redeploy when ready:
```
git checkout main
npm run deploy
```

Summary

What You Should Remember

✅ Automation handles everything:

Sidebar generation
Figure/table/equation numbering
Version management
Navigation structure

✅ Run npm start and it just works:

All scripts run automatically
Dev server starts
Changes reload automatically

✅ Never edit auto-generated files:

sidebars.js
src/reportIdMap.js
static/counters/
static/versions/

✅ Focus on content:

Write MDX files
Add images
Use components
Let automation handle the rest

What You Don't Need to Know

❌ How scripts are implemented
❌ JavaScript/Node.js programming
❌ Docusaurus internals
❌ Build optimization details

When to Think About Build Process

Only when:

Troubleshooting errors
Numbering isn't working correctly
Sidebar isn't updating
Need to understand what files are auto-generated

Next Steps

Now that you understand what happens behind the scenes:

Continue creating content: Creating and Editing Pages
Use React components: React Components
Convert Word documents: DOCX Converter
Quick troubleshooting: Troubleshooting & FAQ

Remember: Understanding the build process is helpful but not required. Focus on creating great documentation - the automation takes care of everything else!

What Happens Behind the Scenes​

The Build Workflow​

When You Run npm start​

The Five Automation Scripts​

1. Report ID Map Generator​

2. Sidebar Generator​

3. Counters Generator​

4. Versions Generator​

5. Event Tree TOC Generator​

What Gets Generated (Don't Edit These!)​

Auto-Generated Files​

How to Tell If a File is Auto-Generated​

The Docusaurus Build Process​

Development Mode (npm start)​

Production Mode (npm run build)​

When Scripts Run​

Automatically​

Common Scenarios​

Scenario 1: I Added a New Chapter​

Scenario 2: Figure Numbers Are Wrong​

Scenario 3: Created New Version Folder​

Scenario 4: Build Fails with "Cannot find module"​

Understanding Build Output​

Terminal Output During npm start​

Build Errors​

Performance Notes​

Build Times​

Hot Reload Speed​

Optimization Tips​

Faster Development​

Faster Builds​

Configuration Files (Reference Only)​

docusaurus.config.js​

package.json​

tailwind.config.js​

Deployment to Production (Administrator-Level Only)​

Deployment Workflow​

Step 1: Build for Production​

Step 2: Test the Production Build Locally​

Step 3: Set GitHub User Environment Variable​

Step 4: Deploy to GitHub Pages​

Post-Deployment Verification​

Troubleshooting Deployment Issues​

Deployment Best Practices​

Rollback Procedure​

Summary​

What You Should Remember​

What You Don't Need to Know​

When to Think About Build Process​

Next Steps​

What Happens Behind the Scenes

The Build Workflow

When You Run `npm start`

The Five Automation Scripts

1. Report ID Map Generator

2. Sidebar Generator

3. Counters Generator

4. Versions Generator

5. Event Tree TOC Generator

What Gets Generated (Don't Edit These!)

Auto-Generated Files

How to Tell If a File is Auto-Generated

The Docusaurus Build Process

Development Mode (`npm start`)

Production Mode (`npm run build`)

When Scripts Run

Automatically

Common Scenarios

Scenario 1: I Added a New Chapter

Scenario 2: Figure Numbers Are Wrong

Scenario 3: Created New Version Folder

Scenario 4: Build Fails with "Cannot find module"

Understanding Build Output

Terminal Output During `npm start`

Build Errors

Performance Notes

Build Times

Hot Reload Speed

Optimization Tips

Faster Development

Faster Builds

Configuration Files (Reference Only)

`docusaurus.config.js`

`package.json`

`tailwind.config.js`

Deployment to Production (Administrator-Level Only)

Deployment Workflow

Step 1: Build for Production

Step 2: Test the Production Build Locally

Step 3: Set GitHub User Environment Variable

Step 4: Deploy to GitHub Pages

Post-Deployment Verification

Troubleshooting Deployment Issues

Deployment Best Practices

Rollback Procedure

Summary

What You Should Remember

What You Don't Need to Know

When to Think About Build Process

Next Steps