Project Structure

Understanding the project structure is essential for contributing to the RMC Software Documentation project. This guide organizes the project folders into three tiers based on how contributors interact with them:

✅ Tier 1: Active Contribution Areas - Files and folders you'll work with regularly
📖 Tier 2: Reference Areas - Resources you'll use but not modify
⛔ Tier 3: Off-Limits Areas - Auto-generated files and build artifacts you should never touch

Project Structure Overview

RMC-SOFTWARE-DOCUMENTATION/
├── docs/                           ✅ YOU WORK HERE - Write MDX documentation
├── static/
│   ├── figures/                    ✅ YOU WORK HERE - Add documentation images
│   ├── bibliographies/             ✅ YOU WORK HERE - Manage citations
│   ├── source-documents/           ✅ YOU WORK HERE - Store original files
│   ├── counters/                   ⛔ DON'T TOUCH - Auto-generated numbering
│   ├── versions/                   ⛔ DON'T TOUCH - Auto-generated version data
│   ├── fonts/                      📖 REFERENCE ONLY
│   └── img/                        📖 REFERENCE ONLY - Site-wide images
├── src/
│   ├── components/                 📖 REFERENCE ONLY - React components to use
│   ├── css/                        📖 REFERENCE ONLY - Styling
│   ├── pages/                      ⛔ DON'T TOUCH - Landing pages
│   ├── data/                       ⛔ DON'T TOUCH - Auto-generated
│   └── reportIdMap.js              ⛔ DON'T TOUCH - Auto-generated
├── scripts/                        ⛔ DON'T TOUCH - Build automation
├── docx_converter/                 📖 REFERENCE ONLY - Conversion utility
├── .docusaurus/                    ⛔ DON'T TOUCH - Build cache
├── build/                          ⛔ DON'T TOUCH - Production build
├── node_modules/                   ⛔ DON'T TOUCH - Dependencies
├── docusaurus.config.js            ⛔ DON'T TOUCH - Site configuration
├── package.json                    ⛔ DON'T TOUCH - Project dependencies
├── sidebars.js                     ⛔ DON'T TOUCH - Auto-generated sidebar
└── [other config files]            ⛔ DON'T TOUCH - Project setup

✅ Tier 1: Active Contribution Areas

These are the primary areas where you'll create and edit content.

`docs/` - Documentation Content

Purpose: Contains all .mdx documentation files organized by application type, software, and version.

Structure:

docs/
├── 00-documentation-guide/         # This guide
├── desktop-applications/           # Desktop software docs
│   ├── lifesim/
│   │   ├── users-guide/
│   │   │   ├── v1.0/              # Version-specific content
│   │   │   │   ├── 00-document-info.mdx
│   │   │   │   ├── 00-version-history.mdx
│   │   │   │   ├── 01-preface.mdx
│   │   │   │   └── ...
│   │   │   └── v1.1/              # Newer version
│   │   └── validation-studies/
│   ├── rmc-bestfit/
│   ├── rmc-rfa/
│   └── rmc-totalrisk/
├── toolbox-technical-manuals/      # Excel toolbox manuals
│   ├── internal-erosion-suite/     # Suite grouping
│   │   ├── backward-erosion-piping-initiation/
│   │   │   └── v1.0/              # Version-specific content
│   │   │       ├── 00-document-info.mdx
│   │   │       ├── 00-version-history.mdx
│   │   │       ├── 01-preface.mdx
│   │   │       └── ...
│   │   ├── breach/
│   │   ├── concentrated-leak-erosion-cracking/
│   │   └── ...
│   ├── overtopping-suite/
│   ├── risk-calculations-suite/
│   └── seismic-hazard-suite/
└── web-applications/               # Web app docs
    ├── dst/
    ├── lst/
    └── rrft/

Folder Hierarchy:

The folder structure differs depending on the application type:

For Desktop and Web Applications:

Application Type - desktop-applications, web-applications
Software Name - lifesim, rmc-rfa, dst, lst
Document Type - users-guide, validation-studies, applications-guide
Version - v1.0, v1.1, v2.0
Chapter Files - 00-document-info.mdx, 01-preface.mdx, etc.

For Toolbox Technical Manuals:

Application Type - toolbox-technical-manuals
Suite Name - internal-erosion-suite, overtopping-suite, risk-calculations-suite
Tool/Document Name - backward-erosion-piping-initiation, breach, concentrated-leak-erosion-cracking
Version - v1.0, v1.1, v2.0
Chapter Files - 00-document-info.mdx, 01-preface.mdx, etc.

Structural Difference

Toolbox technical manuals have an additional organizational level because they document suites of related tools (e.g., internal-erosion-suite, overtopping suite, risk calculations suite), whereas desktop and web applications document individual standalone software products.

Naming Convention for Chapter Files:

Every chapter follows this pattern: ##-chapter-name.mdx

## - Two-digit prefix determining sidebar order (00, 01, 02, etc.)
chapter-name - Lowercase with hyphens (preface, methodology, results)
.mdx - File extension

Required Files:

Every document must include:

00-document-info.mdx - First chapter, contains metadata using <DocumentMetadata /> component
00-version-history.mdx - Second chapter, version history using <TableVersionHistory /> component
01-preface.mdx - Third chapter (first chapter of main report)

CRITICAL: First Chapter Must Be Preface

File name: 01-preface.mdx
Title in file: Preface

The first chapter of the main report must always be named 01-preface.mdx with the title "Preface" - even if your source document's first chapter is titled "Introduction," "Overview," or something else.

Why this requirement exists:

Consistency: Ensures all documents follow the same structure
Automation: The automatic sidebar generation script expects this naming convention
Navigation: Users can reliably find introductory content in the same place across all documents

Converting from source documents: If your source document has "Introduction" as the first chapter, rename it to "Preface" when creating the MDX file. The content can remain the same - only the title changes.

Exception process: If your specific document absolutely requires a different first chapter title, contact a site administrator before creating the document. A custom sidebar configuration may be created, but this requires administrator approval and coordination.

Standard Document Structure:

Document Information (sidebar collapsed by default)
- 00-document-info.mdx
- 00-version-history.mdx
Main Report (sidebar expanded by default)
- 01-preface.mdx (always first chapter of main report)
- 02-chapter-title.mdx
- 03-chapter-title.mdx
- 04-methodology.mdx
- 05-results.mdx
Appendices (sidebar collapsed by default)
- 06-appendix-acronyms.mdx
- 07-appendix-analysis.mdx
- 08-appendix-calculations.mdx

Important

The numeric prefix determines sidebar order. If you number chapters out of sequence (e.g., 01, 02, 05, 03), the sidebar will display them in numeric order, not the order you intended.

Example: Adding a New Chapter

If you want to add a new chapter between existing chapters 03 and 04:

Rename existing 04- files to 05-, 05- to 06-, etc.
Create your new chapter as 04-new-chapter.mdx
The sidebar will automatically update on next build

When to Create a New Version Folder:

Create a new version folder (e.g., v1.1) when:

Making significant changes to existing documentation
Releasing updated software with new features
Correcting substantial errors or outdated information
See Versioning System for details

tip

For minor typos or small clarifications, edit the existing version. For major updates, create a new version folder and copy all chapter files from the previous version before making changes.

`static/figures/` - Documentation Images

Purpose: Store all images, diagrams, screenshots, and figures used in documentation.

Structure:

The folder structure mirrors the docs/ folder:

static/
└── figures/
    ├── desktop-applications/
    │   └── lifesim/
    │       └── users-guide/
    │           └── v1.0/
    │               ├── conceptual-diagram.png
    │               ├── user-interface.png
    │               └── workflow-chart.png
    ├── toolbox-technical-manuals/
    │   └── internal-erosion-suite/
    │       └── backward-erosion-piping-progression/
    │           └── v1.1/
    │               ├── methodology-flowchart.png
    │               └── results-graph.png
    └── documentation-guide/
        ├── node-download.png
        └── edit-env-variables.png

Figure Naming Standards

This project uses two approved naming conventions. Choose the standard that fits your workflow:

Standard A: Sequential Generic (Recommended for DOCX conversions)

figKey: figure-1, figure-2, figure-3, etc.
Filename: figure1.png, figure2.png, figure3.png, etc.
When to use: Documents converted from Word using the DOCX converter
Alignment: figKey and filename match numerically
Handling insertions: Use letter suffixes (e.g., insert figure-24a.png with figKey="figure-24a" between figures 24 and 25)

Example:

<Figure
  figKey="figure-42"
  src="/figures/desktop-applications/lifesim/users-guide/v1.0/figure42.png"
  alt="Study Menu - Destination Data"
  caption="Study Menu - Destination Data"
/>

Standard B: Descriptive Semantic (Optional for hand-authored documentation)

figKey: menu-screenshot, workflow-diagram, settings-dialog, etc.
Filename: menu-screenshot.png, workflow-diagram.png, settings-dialog.png, etc.
When to use: Hand-authored documentation where semantic names improve maintainability
Alignment: figKey and filename match conceptually (filename is a slug of the figKey)
Handling insertions: Add new descriptive name; no renumbering needed

Example:

<Figure
  figKey="fig-workflow-diagram"
  src="/figures/desktop-applications/lifesim/users-guide/v1.0/workflow-diagram.png"
  alt="LifeSim workflow diagram"
  caption="Figure shows the overall workflow for LifeSim analysis"
/>

Consistency Required

DO NOT mix naming conventions within a single document. Pick Standard A or Standard B and use it consistently throughout the entire document.

Never use arbitrary or inconsistent naming. Always follow Standard A or Standard B completely.

Additional Best Practices:

File formats: PNG for screenshots/diagrams, JPG for photos, SVG for scalable graphics
File size: Optimize images before adding (aim for < 500KB per image)
Organization: Always place images in the folder matching your document path

How Figure Numbering Works:

Figure display numbering (e.g., "Figure 1", "Figure 2") is automatically generated at build time based on the order of <Figure> components in your MDX files, not the file names or figKey values. This means:

You don't need to renumber files when adding or removing figures
The figure file name can be figure42, but the displayed number might be "Figure 38" depending on position in the document
File names and figKey values are for organization and reference only

`static/bibliographies/` - Citation Files

Purpose: Store bibliography data for citations in documentation.

Structure:

The folder structure mirrors the docs/ folder:

static/
└── bibliographies/
    ├── desktop-applications/
    │   └── rmc-totalrisk/
    │       └── users-guide/
    │           └── v1.0/
    │               └── bib.json
    └── toolbox-technical-manuals/
        └── internal-erosion-suite/
            └── backward-erosion-piping-progression/
                └── v1.0/
                    └── bib.json

File Format:

Each bib.json file contains an array of citation objects following the IEEE style guide:

[
  {
    "citationKey": "Beard1960",
    "entryType": "article",
    "author": ["L. R. Beard"],
    "year": 1960,
    "title": "Probability Estimates Based on Small Normal-Distribution Samples",
    "journal": "Journal of Geophysical Research"
  },
  {
    "citationKey": "BobeeAshkar1991",
    "entryType": "book",
    "author": ["B. Bobee", "F. Ashkar"],
    "year": 1991,
    "title": "The Gamma Family and Derived Distributions Applied in Hydrology",
    "address": "Littleton, CO",
    "institution": "Water Resources Publications"
  }
]

Creating bib.json Files with AI Assistance

Creating bib.json files manually can be time-consuming. AI language models can significantly speed up this process:

Recommended Workflow:

Gather your references from your source document (bibliography section, reference list, etc.)
Find an example bib.json file from an existing document in this project to use as a template
Provide both to an AI Large Language Model (Claude, ChatGPT, etc.) with a prompt such as:

"I need to create a bib.json file for my documentation project. Here's an example bib.json file from the project showing the required format:

[paste example bib.json]

Here are the references from my document that need to be converted:

[paste your bibliography/reference list]

Please create a bib.json file following the exact format of the example, ensuring all citation keys are unique and formatted correctly."
Review the AI-generated output carefully:
- Verify citation keys are unique and follow naming conventions
- Check that author names, years, and titles are accurate
- Ensure all required fields are present for each entry type
- Confirm formatting matches the IEEE style guide
Save the file to the appropriate location in static/bibliographies/

Example bib.json locations to reference:

static/bibliographies/desktop-applications/rmc-totalrisk/users-guide/v1.0/bib.json
static/bibliographies/toolbox-technical-manuals/internal-erosion-suite/backward-erosion-piping-progression/v1.0/bib.json

AI Time Saver

Using AI to generate bib.json files can reduce what might take hours of manual formatting to just minutes. However, always review the output carefully - AI can make mistakes with names, dates, or formatting.

Using Citations in MDX:

import Citation from '@site/src/components/Citation';
import CitationFootnote from '@site/src/components/CitationFootnote';
import Bibliography from '@site/src/components/Bibliography';

// Inline citation
The method was developed by Beard <Citation citationKey="Beard1960" />.

// Citation footnote at end of page
<CitationFootnote />

// Full bibliography (usually in appendix)
<Bibliography />

For complete documentation on citation components including all props and usage examples, see the Citations section of the React Components reference guide.

warning

Bibliography files must be created before building the documentation. If referenced citation keys don't exist in bib.json, the build will fail or citations won't render correctly.

`static/source-documents/` - Original Source Files

Purpose: Store original Word documents, PDFs, and other source materials.

Structure:

The folder structure mirrors the docs/ folder (same as static/figures/ and static/bibliographies/):

static/
└── source-documents/
    ├── desktop-applications/
    │   └── lifesim/
    │       └── users-guide/
    │           ├── v1.0/
    │           │   └── lifesim-users-guide-v1.0.docx
    │           └── v1.1/
    │               └── lifesim-users-guide-v1.1.docx
    └── toolbox-technical-manuals/
        └── internal-erosion-suite/
            └── backward-erosion-piping-initiation/
                └── v1.0/
                    └── backward-erosion-piping-initiation-v1.0.docx

Purpose:

Archive original documents for reference
Source material for MDX conversion using docx_converter
Historical record of documentation evolution

Naming Convention:

Use descriptive filenames that include the document name and version:

software-name-document-type-v1.0.docx
tool-name-v1.1.pdf

📖 Tier 2: Reference Areas

These resources are important to understand but you generally won't modify them.

`src/components/` - React Components

Purpose: Custom React components you can use in your MDX documentation.

Location: c:\GitHub\RMC-Software-Documentation\src\components\

Available Components:

Over 30 custom components are available including:

Figures: Figure, FigureInline, FigureReference
Tables: TableVertical, TableHorizontal, TableReference
Equations: Equation, EquationReference
Citations: Citation, Bibliography
Content Organization: DocTabs, ProcessList, CollectionList
Multimedia: Video, VideoReference
Navigation: Button, NavLink

For complete documentation, see React Components.

`docx_converter/` - Word Document Conversion

Purpose: Python utility to convert Word documents (following RMC template) into MDX format.

What It Does:

Extracts text, headings, and formatting from .docx files
Converts figures into <Figure> components
Converts tables into <TableVertical> or <TableHorizontal> components
Extracts equations and converts to LaTeX format
Processes citations and creates bib.json files
Generates properly formatted MDX files with correct component imports

For detailed usage instructions, see DOCX Converter.

⛔ Tier 3: Off-Limits Areas

Never edit these files or folders directly. They are site configuration files or auto-generated files that are overwritten during site build.

`scripts/` - Build Automation Scripts

Purpose: Automated scripts that run during npm start and npm run build.

Key Scripts:

generateSidebars.js - Creates sidebar navigation from folder structure
counters.js - Generates figure/table/equation numbering
versions.js - Creates version metadata for version selector
generateReportIdMap.js - Maps document paths to unique IDs
generateEventTreeTOC.js - Builds event tree table of contents for the RMC Event Tree Database

When Scripts Run:

These scripts execute automatically every time you run:

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

Why You Shouldn't Edit Them:

These scripts are part of the build system and should only be modified by site administrators. Any changes could break the automatic generation of sidebars, numbering, or version metadata.

info

If you see files like sidebars.js, static/counters/, or static/versions/ appear after running npm start, these are auto-generated by these scripts. Don't edit them manually - they'll be overwritten on the next build.

`sidebars.js` - Auto-Generated Navigation

Generated by: scripts/generateSidebars.js

Purpose: Defines the sidebar navigation structure for Docusaurus.

Why You Shouldn't Edit It:

This file is completely auto-generated from your folder structure. Any manual edits will be lost the next time you run npm start or npm build.

How to Change Sidebar:

To change the sidebar, modify your folder and file structure in docs/. The sidebar will automatically update to reflect your changes.

Custom Sidebars

If you have a document that requires a custom sidebar structure, contact a site administrator for assistance.

`static/counters/` - Auto-Generated Numbering

Generated by: scripts/counters.js

Purpose: JSON files storing sequential numbers for figures, tables, equations, and videos in each document.

Example: static/counters/lifesim-users-guide-v1-0.json

Why You Shouldn't Edit It:

The counters script scans all your MDX files and assigns sequential numbers automatically. Manual edits will be overwritten and could break cross-references.

How Numbering Works:

Script scans all MDX files for components with unique keys (e.g., figKey="fig-workflow")
Assigns sequential numbers in order of appearance
Stores mappings in JSON files
Components use these mappings to display correct numbers

`static/versions/` - Auto-Generated Version Data

Generated by: scripts/versions.js

Purpose: JSON files for version management and search indexing.

Files:

latestVersions.json - Latest version of each document
versionList.json - All versions of each document
algoliaCrawlerVersions.json - Search crawler configuration

Why You Shouldn't Edit It:

The versions script automatically detects all version folders in docs/ and generates this data. It's regenerated on every build.

`src/pages/` - Landing Pages

Purpose: Contains React-based landing pages for the site.

Why You Shouldn't Edit It:

These are custom React pages that define the site's landing pages and navigation structure. They should only be modified by site administrators who understand the site architecture.

`src/data/` - Auto-Generated Data

Generated by: Various build scripts

Purpose: Contains auto-generated data files used by the site for navigation, search, and internal references.

Why You Shouldn't Edit It:

All files in this folder are automatically generated during the build process and will be overwritten.

`src/reportIdMap.js` - Auto-Generated Mappings

Generated by: scripts/generateReportIdMap.js

Purpose: Maps document paths to unique report IDs used internally for numbering and references.

Why You Shouldn't Edit It:

This file is auto-generated from your folder structure and is regenerated on every build.

`.docusaurus/` - Build Cache

Purpose: Docusaurus internal cache directory.

Why You Shouldn't Edit It:

This folder contains temporary build files and cached data. It's automatically created and managed by Docusaurus.

When to Delete It:

If you experience strange build issues, you can safely delete this folder and run:

npm run clear   # Clears the cache
npm start       # Rebuilds cache and starts dev server

`build/` - Production Build Output

Purpose: Contains the final static HTML, CSS, and JavaScript files for deployment.

Generated by: npm run build

Why You Shouldn't Edit It:

This folder is the compiled output of your documentation. Any edits will be overwritten on the next build.

`node_modules/` - Dependencies

Purpose: Contains all installed npm packages and dependencies.

Generated by: npm install

Why You Shouldn't Edit It:

This folder contains third-party libraries managed by npm. Never edit files here directly. It can be safely deleted and regenerated by running npm install.

`docusaurus.config.js` - Site Configuration

Purpose: Main configuration file for Docusaurus defining site URL, title, theme, plugins, search, and analytics.

Why You Shouldn't Edit It:

This file controls core site functionality and should only be modified by site administrators. Incorrect changes can break the entire site.

`package.json` - Project Dependencies

Purpose: Defines npm dependencies, scripts, and project metadata.

Why You Shouldn't Edit It:

This file manages the project's dependency tree and build scripts. Modifying it without proper knowledge can break the build system or introduce version conflicts. Only site administrators should modify this file.

Other Configuration Files

Files:

tailwind.config.js - Styling and theming configuration
.gitignore - Files excluded from Git version control
tsconfig.json - TypeScript configuration
.eslintrc.js - Code linting rules

Why You Shouldn't Edit Them:

These configuration files define project-wide settings and should only be modified by site administrators who understand their impact on the entire codebase.

Decision Trees for Common Tasks

"Where should I put my new document?"

Step 1: Determine the application type:

Desktop software (exe/installer) → desktop-applications/
Excel-based toolbox → toolbox-technical-manuals/
Web-based tool → web-applications/

Step 2: Find or create the software folder:

Software already exists? → Use existing folder
New software? → Create new folder with lowercase-hyphenated name

Step 3: Find or create the document folder:

Document type already exists? → Use existing folder
New document type? → Create new folder with descriptive name

Step 4: Create or use version folder:

First version? → Create v1.0/
Updating existing? → Create next version v1.1, v2.0, etc.

Step 5: Create your MDX files:

Start with 00-document-info.mdx and 00-version-history.mdx
Add chapters: 01-preface.mdx, 02-chapter.mdx, etc.

Example:

New LifeSim validation study (version 1.0):

docs/desktop-applications/lifesim/validation-studies/v1.0/
├── 00-document-info.mdx
├── 00-version-history.mdx
├── 01-preface.mdx
└── ...

"Where should I put my images?"

Create a folder path in static/figures/ that exactly matches your document path.

Document path:

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

Image path:

static/figures/desktop-applications/lifesim/users-guide/v1.0/

Place all images for that document in this folder.

"Where should I put my bibliography file?"

Create a folder path in static/bibliographies/ that exactly matches your document path, and name the file bib.json.

Document path:

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

Bibliography path:

static/bibliographies/desktop-applications/lifesim/users-guide/v1.0/bib.json

Common Questions

Can I create new React components or revise existing ones?

For beginner contributors: No. Use the existing components documented in React Components.

For advanced contributors: Coordinate with site administrators before creating custom components or revising existing ones. This requires understanding React, JSX, and Tailwind CSS.

Yes! The sidebar is automatically generated from your folder structure. To change it:

Rename or reorganize folders in docs/
Renumber file prefixes to change order
Run npm start - the sidebar updates automatically

Don't edit sidebars.js directly - it will be overwritten.

Custom Sidebars

If you have a document that requires a custom sidebar structure, contact a site administrator for assistance.

What if I see a file not listed here?

If you encounter files or folders not mentioned in this guide:

Check if they're in .gitignore (likely auto-generated)
Consult with site administrators before modifying
When in doubt, don't edit it

How do I know if a file is auto-generated?

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

Common auto-generated files:

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

Summary: What Should Contributors Touch?

✅ Frequently Edit

MDX files in docs/
Images in static/figures/
Citation files in static/bibliographies/
Source documents in static/source-documents/

📖 Read and Reference

React components in src/components/
CSS styling in src/css/
Site-wide images in static/img/
Site fonts in static/fonts/
DOCX converter utility in docx_converter/

⛔ Never Edit

Build scripts in scripts/
Auto-generated sidebars.js
Auto-generated src/reportIdMap.js
Auto-generated src/data/
Landing pages in src/pages/
Auto-generated counters in static/counters/
Auto-generated versions in static/versions/
Build cache in .docusaurus/
Production build in build/
Dependencies in node_modules/
Configuration files (docusaurus.config.js, package.json, etc.)

Next Steps

Now that you understand the project structure, you're ready to start creating content:

Create MDX documents: See Creating and Editing Pages
Use React components: See React Components
Convert Word documents: See DOCX Converter
Manage versions: See Versioning System