Skip to main content
U.S. Army Corps of Engineers
®
US Army Corps of EngineersInstitute for Water Resources, Risk Management Center
Developer Resources

Appendix A: Source Code Structure

Advanced Topic

This appendix is intended for advanced users, developers, and site administrators who need to understand or modify the underlying source code structure.

Contributors writing documentation do NOT need to read this section. All necessary information for contributing MDX documentation is covered in the main guide.

Overview​

The src/ folder contains all source code for custom React components, styles, pages, and theme files used in the RMC Software Documentation project. This folder is part of the project's ⛔ Off-Limits Areas for regular contributors.

Directory Structure:

src/
├── components/        → React components used in MDX
│   └── icons/         → SVG icon components for landing pages
├── contexts/          → React context for state management
├── clientModules/     → Client-side modules (analytics, scroll behavior)
├── css/               → Global stylesheets
├── data/              → Build-generated data files
├── pages/             → Custom web pages (homepage, landing pages)
├── theme/             → Docusaurus theme overrides
├── docConfig.js       → Central document active/draft registry
├── draftDocs.js       → Thin shim around docConfig.js
├── imageDimensions.js → Auto-generated image metadata
└── reportIdMap.js     → Auto-generated ID mappings

Components Directory​

Location: src/components/

Contains all custom React components used throughout the documentation site. These components are imported and used within MDX files by contributors.

Component Categories​

Document Metadata:

  • DocumentMetadata.js

Figures & Images:

  • Figure.js
  • FigureReference.js
  • FigureInline.js
  • FigureNoRef.js
  • GIF.js

Tables:

  • TableVertical.js
  • TableVerticalNoRef.js
  • TableHorizontal.js
  • TableAcronyms.js
  • TableReference.js
  • TableVersionHistory.js
  • TableBestFitDistributions.js
  • TableChangelog.js

Equations:

  • Equation.js
  • EquationNoRef.js
  • EquationReference.js
  • EquationChip.js

Citations:

  • Citation.js
  • CitationFootnote.js
  • Bibliography.js

Content Organization:

  • ProcessList.js - Step-by-step procedures
  • DocTabs.js - Tabbed content panels
  • CollectionList.js - Expandable grouped items
  • CategoryList.js - Navigation tiles/menus

Multimedia:

  • Video.js - Numbered video embeds
  • VideoReference.js - Video cross-references

Navigation:

  • Button.js
  • NavLink.js
  • NavContainer.js
  • VersionSelector.js

Specialized:

  • EventTree.js - Event tree diagrams with download
  • EventTreeTOC.js - Event tree table of contents
  • Counters.js - Build-time counter utility
  • ModuleMap.js - Module diagram rendering
  • DocChapterNav.js - Chapter-level navigation

Landing Page Components:

  • ContentBox.js / ContentBoxLarge.js - Dashboard cards
  • ContentBubble.js / ContentBubbleLarge.js - Dashboard card sub-components
  • ContentCard.js - Content card layout

Site Features:

  • SiteTour.js - Guided site tour overlay
  • TourButton.js - Tour launch button
  • VersionNotice.js - Version mismatch notice (used internally by NavContainer)

Schema Components (DST Database):

  • SchemaGroup.js - Schema group container
  • SchemaTable.js - Database schema table
  • SchemaTableCompact.js - Compact schema table variant
  • SchemaTag.js - Schema tag labels
  • SchemaRelationshipDiagram.js - Entity relationship diagrams

Icon Components (src/components/icons/):

19 SVG icon components for landing pages and navigation: CodeIcon, DesktopAppIcon, DocumentationGuideIcon, DSTDatabaseIcon, DSTIcon, GitHubIcon, InternalErosionIcon, LSTIcon, OvertoppingIcon, RiskCalculationsIcon, RiverineErosionIcon, RRFTIcon, SeismicHazardIcon, SparkleIcon, SpillwayErosionIcon, StructuralIcon, StyleGuideIcon, ToolboxIcon, WebAppIcon

Component Architecture​

Common Patterns:

  1. Automatic Numbering:

    • Components like Figure, TableVertical, Equation, Video use automatic numbering
    • Numbers stored in JSON counter files in static/counters/
    • Updated by scripts/counters.js script

  2. Cross-Referencing:

    • Reference components (FigureReference, TableReference, etc.) link to numbered items
    • Use React Context to share data between components
    • Require matching keys between item and reference

  3. Styling:

    • Primarily use Tailwind CSS utility classes
    • Props allow customization (colors, sizes, alignment)
    • Support light/dark themes via CSS variables

Creating New Components:

Site Administrators Only

Only experienced React developers and site administrators should create or modify components. Improper changes can break the entire documentation site.

Requirements for New Components:

  • Must be compatible with Docusaurus MDX processing
  • Must support server-side rendering (SSR)
  • Should use Tailwind CSS for styling consistency
  • Must be documented in React Components Reference
  • Should follow existing naming and API conventions

Testing New Components:

  1. Create component file in src/components/
  2. Test in isolation with simple MDX file
  3. Verify SSR compatibility (test production build)
  4. Add TypeScript/PropTypes for prop validation
  5. Document all props and usage examples
  6. Test with different themes (light/dark)
  7. Verify accessibility (keyboard navigation, screen readers)

Contexts Directory​

Location: src/contexts/

Contains React Context files for state management and sharing data across components.

ReportIdContext.js​

Purpose: Provides report ID information to components that need it.

Usage in Components:

import { useReportId } from '@site/src/contexts/ReportIdContext';

function MyComponent() {
  const reportId = useReportId();
  // Use reportId for component logic
}

How It Works:

  1. reportIdMap.js (auto-generated) contains mappings of document paths to report IDs
  2. Context provider wraps the entire site via Docusaurus plugin
  3. Components access report ID via useReportId() hook
  4. Used for automatic counter numbering scoped to documents

Modifying Context:

Only modify if adding new context providers or changing report ID logic. Requires understanding of React Context API and Docusaurus plugin system.

TourContext.js​

Purpose: Manages state for the guided site tour feature (SiteTour component).

Provides:

  • Tour active/inactive state
  • Current tour step tracking
  • Tour start/stop/navigation functions

Used By: SiteTour.js, TourButton.js, and Root.js theme wrapper.

Client Modules Directory​

Location: src/clientModules/

Client modules run on every page load and are registered in docusaurus.config.js.

analyticsEvents.js​

Purpose: Sends custom Google Analytics 4 events for page views, search interactions, and tour tracking.

gtagPolyfill.js​

Purpose: Provides a polyfill for the gtag() function to prevent errors when the Google Analytics script hasn't loaded yet.

scrollToAnchor.js​

Purpose: Handles smooth scrolling to anchor links on page navigation, ensuring hash-based navigation works correctly.

CSS Directory​

Location: src/css/

The RMC Software Documentation site primarily uses Tailwind CSS for styling. However, some global styles require traditional CSS files.

Global Style Files​

custom.css

Contains global styles applied across the entire site:

  • CSS variable definitions for theming
  • Base element styles (body, html)
  • Utility classes not covered by Tailwind
  • Print styles
  • Overrides for Docusaurus default styles

Key CSS Variables:

:root {
  --ifm-color-primary: #0078d4;
  --ifm-font-family-base: 'Roboto', sans-serif;
  /* ...and more theme variables */
}

[data-theme='dark'] {
  --ifm-color-primary: #4dabf7;
  /* Dark theme overrides */
}

equation.css

Global styles for equation components:

  • KaTeX equation rendering styles
  • Equation numbering appearance
  • Equation caption formatting
  • Equation reference link styles

tables.css

Global styles for table components:

  • Table border and spacing
  • Header row styling
  • Alternating row colors
  • Responsive table behavior
  • Table caption formatting

schema.css

Global styles for DST database schema components:

  • Schema table and group layout
  • Schema tag colors and sizing
  • Relationship diagram styling

chapter-nav.css

Styles for the DocChapterNav chapter navigation component:

  • Navigation layout and spacing
  • Active state indicators

Tailwind CSS Integration​

Configuration: tailwind.config.js (root directory)

Custom Theme Extensions:

// Example from tailwind.config.js
theme: {
  extend: {
    colors: {
      'ifm-primary': 'var(--ifm-color-primary)',
      // Custom colors
    },
    fontFamily: {
      'usace': ['Roboto', 'sans-serif'],
    }
  }
}

Using Tailwind in Components:

<div className="flex items-center justify-between bg-gray-100 p-4 dark:bg-gray-800">
  <h2 className="text-primary text-2xl font-bold">Title</h2>
</div>

Resources:

Style Modifications

Do not modify global CSS files or Tailwind configuration unless you are a site administrator. Improper changes can break styling across the entire site.

For component-specific styles, prefer Tailwind utility classes or component-level CSS-in-JS.

Data Directory​

Location: src/data/

Contains JSON files generated during the build process.

Event Tree Data​

The primary use case is for the RMC Typical Event Tree Database document, which requires structured data for rendering event trees.

Files:

  • eventTreeToc.json — Table of contents data for the Typical Event Tree Database
  • dstSchemaData.js — Schema metadata for DST database documentation

Generated By: scripts/generateEventTreeTOC.js and build-time data extraction

Used By: EventTreeTOC and schema components for rendering structured data

Auto-Generated

Files in this directory are typically auto-generated and should not be manually edited.

Pages Directory​

Location: src/pages/

Contains custom web pages that are not part of the documentation structure. These pages have their own routes and do not follow the versioned documentation pattern.

Homepage​

File: index.js or index.jsx

Route: https://your-site.com/

The main landing page for the RMC Software Documentation website.

Typical Contents:

  • Welcome message
  • Featured documentation
  • Quick links to software manuals
  • Search functionality
  • Recent updates or announcements

Landing Pages​

Additional pages for organizing documentation by category:

Category Hub Pages:

  • desktop-applications.js - Hub page for all desktop applications
  • toolboxes.js - Hub page for all toolbox technical manuals
  • web-applications.js - Hub page for all web applications
  • changelog.js - Site changelog page
  • feedback.js - User feedback form page

Application-Specific Pages (desktop-applications/):

  • lifesim.js, rmc-bestfit.js, rmc-rfa.js, rmc-totalrisk.js

Toolbox-Specific Pages (toolboxes/):

  • internal-erosion-suite.js, overtopping-suite.js, risk-calculations-suite.js, seismic-hazard-suite.js

Web Application Pages (web-applications/):

  • dst.js, lst.js, rrft.js

Developer Pages (docs/):

  • dev.js - Developer resources landing page

Page Structure:

import React from 'react';
import Layout from '@theme/Layout';

export default function MyPage() {
  return (
    <Layout title="Page Title" description="Page description">
      <main>
        <h1>Page Content</h1>
        {/* Page components and content */}
      </main>
    </Layout>
  );
}

Routing:

  • Files in src/pages/ automatically become routes
  • index.js → /
  • about.js → /about
  • subfolder/page.js → /subfolder/page

Adding New Pages:

  1. Create .js or .jsx file in src/pages/
  2. Use Layout component for consistent header/footer
  3. Add page to navigation if needed (modify docusaurus.config.js)
  4. Build and test: npm run build && npm run serve
Growing Pages

This directory continues to grow as the site expands with new hubs and navigation pages.

Theme Directory​

Location: src/theme/

Docusaurus uses a theme system called "Swizzling" that allows overriding default theme components with custom implementations.

What is Theme Swizzling?​

Swizzling lets you customize or replace any component from the default Docusaurus theme by creating a file with the same name in src/theme/.

Swizzle Levels:

  • Safe: Docusaurus guarantees API stability
  • Unsafe: Component may change in future Docusaurus versions

Command to Swizzle:

npm run swizzle @docusaurus/theme-classic ComponentName

Current Theme Overrides​

Root.js

File: src/theme/Root.js

Purpose: Wraps the entire application with context providers (ReportIdContext, TourContext) and global components (SiteTour).

Layout Override

Files: src/theme/Layout/index.jsx and supporting modules:

  • buildNavLinks.js — Constructs navigation link data
  • externalLinks.js — External link configuration
  • ThemeToggle.jsx — Light/dark theme toggle component
  • usaceLinks.js — USACE-specific navigation links
  • useHeaderOffsets.js — Header offset calculation hook
  • useLatestVersions.js — Latest version resolution hook

Purpose: Custom layout wrapper that adds USACE branding, navigation links, and version-aware header behavior.

NotFound Override

File: src/theme/NotFound/Content/index.js

Purpose: Custom 404 page content with site-specific messaging and navigation.

DocItem Theme Component

Files: src/theme/DocItem/index.js, src/theme/DocItem/Layout/index.js, src/theme/DocItem/Layout/styles.module.css

Purpose: Override the default documentation page wrapper to add a version-aware DRAFT watermark and custom layout styles.

Custom Functionality:

  • Reads the current page's pathname and matches it against the draftDocs list (which is derived from src/docConfig.js)
  • Cross-references the version in the URL against latestVersions.json so the watermark only renders on the latest version of a flagged document — older versions of the same document stay unwatermarked
  • Preserves all default DocItem behavior

How It Works:

import React from 'react';
import DocItem from '@theme-original/DocItem';
import { useLocation } from '@docusaurus/router';
import { draftDocs } from '../../draftDocs';
import latestVersions from '@site/static/versions/latestVersions.json';

function getDocInfo(pathname) {
  const stripped = pathname
    .replace(/^\/RMC-Software-Documentation\/docs\//, '')
    .replace(/^\/docs\//, '')
    .replace(/^docs\//, '');
  const match = stripped.match(/^(.+?)\/(v\d+\.\d+(?:\.\d+)?)(?:\/|$)/);
  if (!match) return null;
  return { docBasePath: match[1], version: match[2] };
}

function isDraftDoc(pathname) {
  const info = getDocInfo(pathname);
  if (!info) return false;
  const isFlagged = draftDocs.some(
    (base) => info.docBasePath === base || info.docBasePath.startsWith(base + '/')
  );
  if (!isFlagged) return false;
  const latest = latestVersions[info.docBasePath];
  if (!latest) return true;
  return info.version === latest;
}

export default function DocItemWrapper(props) {
  const location = useLocation();
  const showWatermark = isDraftDoc(location.pathname);
  return (
    <>
      {showWatermark && (
        <div className="pointer-events-none fixed left-1/2 top-[40%] z-[9999] -translate-x-1/2 -translate-y-1/2 -rotate-[30deg] select-none text-[10rem] font-bold uppercase text-[rgba(200,0,0,0.15)]">
          DRAFT
        </div>
      )}
      <DocItem {...props} />
    </>
  );
}

SearchBar Theme Component

File: src/theme/SearchBar/index.js or similar

Purpose: Replace default search bar with custom Algolia search integration.

Custom Functionality:

  • Integrates with Algolia DocSearch API
  • Applies custom styling matching site theme
  • Adds search result categorization
  • Implements keyboard shortcuts (Ctrl+K)

Configuration:

Creating New Theme Overrides​

Advanced Customization

Only swizzle theme components if absolutely necessary. Theme overrides can break during Docusaurus updates and require maintenance.

Best Practices:

  1. Check if your goal can be achieved without swizzling (custom components, plugins, CSS)
  2. Prefer "safe" swizzles over "unsafe" when possible
  3. Document all customizations
  4. Test thoroughly after Docusaurus updates
  5. Minimize changes to original theme component code

Resources:

docConfig.js and draftDocs.js​

Location: src/docConfig.js and src/draftDocs.js

src/docConfig.js is the central source of truth for which documents are published and which display the DRAFT watermark. Every published document tile has exactly one entry in the docs array with two orthogonal flags:

{
  category: 'desktop-applications',
  software: 'lifesim',
  doc_location: 'desktop-applications/lifesim/users-guide',
  doc_name: 'LifeSim Users Guide',
  active: true,    // controls build inclusion, sidebar, and search
  draft: false,    // controls watermark only
},

The file is CommonJS so both the React app (for landing-page tile rendering) and Node build scripts (for sidebar generation, version metadata, build exclusion) can consume it from the same source. It also exports three helper functions:

  • filterByCategoryAndSoftware(category, software) — used by landing pages to filter the doc list
  • getInactiveDocLocations() / getDraftDocLocations() — used by build scripts
  • shouldExcludeFromBuild(docsRelativePath) — used by scripts/generateSidebars.js and scripts/versions.js to skip inactive docs in prod builds

Active vs. draft semantics:

  • active: true → doc is built, served, sidebar-registered, and indexed by the search crawler.
  • active: false → doc is excluded from the prod build (no static HTML, no sidebar, no Algolia entry); landing page renders a "Coming Soon" tile. In dev (DOCS_MODE !== 'prod'), the doc is built so contributors can work on it without exposing it publicly.
  • draft: true → DRAFT watermark renders on the latest version of the doc only.
  • draft: false → no watermark.

The two flags are orthogonal. A doc may be active+draft (published with watermark, fully searchable) or inactive+draft (unpublished, watermark configured for whenever it goes active).

Download-only entries — entries with a downloadUrl but no doc_location — link directly to a PDF and are unaffected by the build-inclusion logic.

src/draftDocs.js is a thin shim that imports getDraftDocLocations() and exports the resulting array of doc locations. It exists because src/theme/DocItem/index.js needs a clean ESM-style import for the client-side watermark check, while docConfig.js is consumed via require() from build scripts. Concretely:

// src/draftDocs.js
import { getDraftDocLocations } from './docConfig';
export const draftDocs = getDraftDocLocations();

Updating the list:

Edit src/docConfig.js directly — flip active or draft on the relevant entry, or add a new entry for a new document. The file is checked into version control and is not auto-generated.

reportIdMap.js​

Location: src/reportIdMap.js

Purpose: Auto-generated file that maps documentation base paths (including version) to unique report IDs.

Auto-Generated File

Do not edit this file manually. It is automatically regenerated by the generateReportIdMap.js script.

Generated By: scripts/generateReportIdMap.js

When Generated:

  • Before each build (npm run build)
  • Manually via npm run build (which runs all pre-build scripts)

Example Structure:

// reportIdMap.js
const reportIdMap = {
  'lifesim/v1.0': 'lifesim-v10',
  'lifesim/v1.1': 'lifesim-v11',
  'watersim/v2.0': 'watersim-v20',
  // ...more mappings
};

export default reportIdMap;

How It's Used:

  1. ReportIdContext provides current document's report ID
  2. Counter Components use report ID to scope numbering (e.g., Figure 1 in lifesim-v10, Figure 1 in lifesim-v11)
  3. Counter Files organized by report ID: static/counters/lifesim-v10-counters.json

Mapping Rules:

  • Each version folder gets unique report ID
  • Format: {software}-{version} with special characters removed
  • Ensures figure/table/equation numbers are independent per version

Regenerating Map:

If you add new version folders or documentation:

# Regenerate all build artifacts
npm run build

The report ID map will be automatically updated as part of the build process.

Technical Architecture Notes​

Build Process Integration​

The src/ folder is integrated into the Docusaurus build process:

  1. Pre-Build Scripts:

    • Generate reportIdMap.js
    • Update counter files
    • Generate sidebar configuration

  2. Build Phase:

    • Webpack bundles all components
    • Tailwind processes utility classes
    • CSS files compiled and minified
    • React components optimized and split

  3. Post-Build:

    • Static HTML generated for all pages
    • Components hydrated on client side
    • Service worker generated (if enabled)

Component Development Workflow​

For site administrators adding new components:

  1. Design Component API:

    • Determine required and optional props
    • Design consistent with existing components
    • Consider accessibility requirements

  2. Implement Component:

    • Create file in src/components/
    • Use Tailwind for styling
    • Add prop validation (PropTypes or TypeScript)
    • Support light/dark themes

  3. Test Component:

    • Create test MDX file
    • Test in development: npm start
    • Test production build: npm run build && npm run serve
    • Verify SSR compatibility
    • Test on different screen sizes

  4. Document Component:

    • Add to React Components Reference
    • Include all props with types and defaults
    • Provide usage examples
    • Note any special considerations

  5. Deploy:

    • Commit to repository
    • Update deployment
    • Announce new component to contributors

State Management​

Current state management approach:

React Context:

  • Used for report ID sharing
  • Minimal context to avoid re-render issues
  • Provided at app root level

Component State:

  • Local state with useState for component-specific needs
  • Keep state close to where it's used
  • Avoid prop drilling with composition

External State:

  • Counter files (JSON) for figure/table/equation numbers
  • Bibliography files (JSON) for citations
  • Configuration files (JS) for site settings

Performance Considerations​

Code Splitting:

  • Components automatically split by Webpack
  • Lazy loading for heavy components (if implemented)
  • Tree shaking removes unused code

CSS Optimization:

  • Tailwind purges unused styles in production
  • Global CSS minimized
  • Critical CSS inlined for faster first paint

Image Optimization:

  • Images should be properly sized before adding
  • Use appropriate formats (PNG for screenshots, JPG for photos, SVG for graphics)
  • Consider lazy loading for many images

When to Modify Source Code​

Contributors: NEVER​

Regular documentation contributors should never need to modify anything in the src/ folder.

If You Think You Need To:

  • Review existing components - one likely already does what you need
  • Check component props for customization options
  • Ask site administrators for help

Site Administrators: RARELY​

Even administrators should modify source code sparingly:

Good Reasons to Modify:

  • Adding genuinely new functionality not possible with existing components
  • Fixing bugs in existing components
  • Updating for major Docusaurus version changes
  • Performance optimizations

Bad Reasons to Modify:

  • Making one-off customizations (use props instead)
  • Styling changes (use Tailwind classes or global CSS)
  • Adding content (use MDX files, not components)

Testing Requirements​

Before Committing Source Code Changes:

  • ✓ Component renders correctly in development
  • ✓ Production build succeeds: npm run build
  • ✓ Component works in production: npm run serve
  • ✓ No console errors or warnings
  • ✓ Accessible via keyboard navigation
  • ✓ Works with light and dark themes
  • ✓ Responsive on mobile/tablet/desktop
  • ✓ Documentation updated in components guide
  • ✓ Changes committed with clear description
  • ✓ Tested by at least one other person

Additional Resources​

Docusaurus Documentation​

React Resources​

Styling Resources​

Build Tools​

Summary​

The src/ folder contains the technical foundation of the RMC Software Documentation site:

Key Directories:

  • components/ - React components for use in MDX (including icons/ subdirectory)
  • contexts/ - React context providers (ReportIdContext, TourContext)
  • clientModules/ - Client-side modules (analytics, scroll behavior)
  • css/ - Global stylesheets
  • data/ - Build-generated data files
  • pages/ - Custom web pages and landing pages
  • theme/ - Docusaurus theme overrides (Root, Layout, DocItem, NotFound, SearchBar)

Auto-Generated Files:

  • reportIdMap.js - Document ID mappings
  • imageDimensions.js - Image dimension metadata

Contributor-Edited Files:

  • docConfig.js - Central registry of active/draft flags for every document tile
  • draftDocs.js - Thin shim around docConfig.js consumed by the DocItem theme component

Important Principles:

  • Contributors don't need to touch this folder
  • Only administrators should modify source code
  • Changes require thorough testing
  • Document all customizations

For More Information:

Questions about source code structure? Contact site administrators or maintainers for guidance.

Last updated on