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 Image Dimensions
    ↓
2. Generate Report ID Map
    ↓
3. Generate Sidebars
    ↓
4. Generate Counters
    ↓
5. Generate Versions
    ↓
6. Generate Event Tree TOC
    ↓
7. Start Docusaurus Dev Server
    ↓
Site available at http://localhost:3000

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

The Six Automation Scripts

1. Image Dimensions Generator

Script: scripts/generateImageDimensions.js

What it does:

Scans all image files referenced in the documentation
Extracts width and height metadata for each image
Generates a JavaScript module with dimension data

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

Why it matters:

Enables responsive image rendering with correct aspect ratios
Prevents layout shift by reserving space before images load
Used by Figure components for proper image sizing

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

4. 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": {
    "figure-3": {
      "figNumber": 1,
      "parentDocId": "lifesim-users-guide-v1-0",
      "docId": "02-methodology.mdx"
    },
    "figure-6": {
      "figNumber": 2,
      "parentDocId": "lifesim-users-guide-v1-0",
      "docId": "03-results.mdx"
    }
  },
  "tables": {
    "table-3": {
      "tableNumber": 1,
      "parentDocId": "lifesim-users-guide-v1-0",
      "docId": "02-methodology.mdx"
    }
  },
  "equations": {
    "equation-2": {
      "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="figure-3"> → assigns Figure 1
Encounters second <Figure figKey="figure-6"> → 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

5. 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)

6. 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
`src/imageDimensions.js`	generateImageDimensions.js	Image dimension metadata
`src/reportIdMap.js`	generateReportIdMap.js	Document ID mappings
`sidebars.js`	generateSidebars.js	Navigation structure
`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
`src/data/dstSchemaData.js`	Build process	DST schema data
`.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/imageDimensions.js
src/data/
static/counters/
static/versions/
.docusaurus/
build/
node_modules/

The Docusaurus Build Process

After the six scripts complete, Docusaurus takes over:

Development Mode (`npm start`)

Pre-build phase:
- Runs all 6 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 6 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 6 scripts, then starts dev server
npm run build  # Runs all 6 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, and the manual compress-video utility)
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

`scripts/compress-video.js` (manual utility)

Purpose: Compress oversized video files before committing them.

Unlike the scripts above, this is not part of the automated build — it is an on-demand helper. Run npm run compress-video -- <path-to-video> to re-encode a video in place (H.264/CRF via the bundled ffmpeg-static, so no system install is required). The original is preserved as a gitignored *-raw.* file. See Videos and GIFs for the contributor workflow.

Production Build and Deployment

Important - Administrators Only

Contributors use npm start while editing and should run npm run build when their changes can affect the site. Pull-request builds and previews do not receive production publishing credentials.

Production builds automatically only from main. Only administrators merge to main and approve the protected production environment. Do not run npm run deploy from an author, Director Review, or Publication PR branch.

Local production verification

Step 1: Build for Production

npm run build

What this does:

Runs all 6 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:

npm run serve

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

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.

After local verification, push the branch and use the review workflow. An eligible PR merged by an administrator triggers the production build from the exact main revision and waits for environment approval.

Post-Deployment Verification

After the approved deployment succeeds, 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

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 fails, preserve completed review state and any Director preview. Correct the problem through a PR to main, then let an administrator retry production. Do not automatically restart reviews, publish a historical commit directly, or delete the stable preview.

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 Six Automation Scripts​

1. Image Dimensions Generator​

2. Report ID Map Generator​

3. Sidebar Generator​

4. Counters Generator​

5. Versions Generator​

6. 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​

scripts/compress-video.js (manual utility)​

Production Build and Deployment​

Local production verification​

Step 1: Build for Production​

Step 2: Test the Production Build Locally​

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 Six Automation Scripts

1. Image Dimensions Generator

2. Report ID Map Generator

3. Sidebar Generator

4. Counters Generator

5. Versions Generator

6. 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`

`scripts/compress-video.js` (manual utility)

Production Build and Deployment

Local production verification

Step 1: Build for Production

Step 2: Test the Production Build Locally

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