Scripts Folder

The scripts/ folder contains custom Node.js scripts for automation and data generation in the RMC Software Documentation project.

counters.js

Overview

The counters.js script scans all .mdx files in the docs/ directory, extracts metadata from custom components like <Figure>, <Table*>, <Equation>, and <Citation>, and generates a structured JSON file for each report. These JSON files are stored in static/counters/ and contain consistent numbering and metadata for figures, tables, equations, and citations.

What It Does

Recursively scans the docs/ directory for folders containing .mdx files.
Uses reportIdMap.js to associate each folder with a unique reportId.
For each matched folder:
- Parses all .mdx files to find:
  - <Figure figKey="..."> components
  - <TableHorizontal tableKey="...">, <TableVertical>, or <TableVerticalLeftAlign> components
  - <Equation equationKey="..."> components
  - <Citation citationKey="..."> components
- Assigns a unique number to each:
  - figNumber for figures
  - tableNumber for tables
  - equationNumber for equations
  - citationNumber for citations
- Records additional metadata for each:
  - figKey, tableKey, equationKey, or citationKey
  - parentDocId (from reportIdMap.js)
  - parentDocPath (relative path within docs/)
  - docId (name of the .mdx file)

Output

Each output file is saved to: static/counters/<reportId>.json. The structure of the JSON output looks like this:

{
  "figures": {
    "figKey": {
      "figNumber": 1,
      "parentDocId": "soil-erosion",
      "parentDocPath": "rmc/soil/contact-erosion",
      "docId": "overview.mdx"
    }
  },
  "tables": {
    "tableKey": {
      "tableNumber": 1,
      "parentDocId": "soil-erosion",
      "parentDocPath": "rmc/soil/contact-erosion",
      "docId": "overview.mdx"
    }
  },
  "equations": {
    "equationKey": {
      "equationNumber": 1,
      "parentDocId": "soil-erosion",
      "parentDocPath": "rmc/soil/contact-erosion",
      "docId": "overview.mdx"
    }
  },
  "citations": {
    "citationKey": {
      "citationNumber": 1,
      "parentDocId": "internal-erosion-suite-backward-erosion-piping-progression-v1.0",
      "parentDocPath": "toolbox-technical-manuals/internal-erosion-suite/backward-erosion-piping-progression/v1.0",
      "docId": "04-background.mdx"
    }
  }
}

Usage

This script is automatically run on project start, build, and deploy. No additional execution of this script is required.

During project build, React components like <Figure>, <Table*>, <Equation>, <Citation>, <CitationFootnote>, and <Bibliography> will use the generated counters JSON files to automatically assign sequential and appropriate numbering to figures, tables, equations, captions, and citations. This relieves the user of the burden of manually numbering these elements.

generateEventTreeToc.js

Note

This script is only used for the RMC Typical Event Tree Database document.

Overview

This Node.js script scans the docs/toolbox-technical-manuals/risk-calculations-suite/typical-event-tree-database directory and generates a versioned table of contents (eventTreeToc.json) in the src/data/ folder. It organizes .mdx files into categories and sub-items based on their numeric filename prefixes and the title found in each file’s frontmatter.

What It Does

Scans each versioned folder (e.g., v1.0, v1.4) under the event tree database directory.
Filters out .mdx files starting with 00, 01, or 02.
Parses numeric prefixes from filenames:
- Files ending in 0 (e.g., 030-...) are treated as categories.
- Files with other prefixes (e.g., 031-..., 046-...) are grouped under the most recent category.
Extracts the title value from each file’s frontmatter.
Builds a versioned TOC object mapping each category to its sub-items.
Saves the result as a JSON file in src/data/eventTreeToc.json.

info

If a file does not have a title in its frontmatter, the script will fallback to using the filename (with its numeric prefix removed) as the label. This ensures that each entry has a human-readable label even if metadata is missing.

Output

The output file (eventTreeToc.json) is saved to: src/data/eventTreeToc.json

It contains an object with each version and its associated categories and paths. Example:

{
  "v1.4": {
    "Geotechnical Hydrologic": [
      {
        "label": "Generic Internal Erosion",
        "path": "/docs/toolbox-technical-manuals/risk-calculations-suite/typical-event-tree-database/v1.0/Generic-Internal-Erosion"
      }
    ],
    "Geotechnical Seismic": [
      {
        "label": "Concentrated Leak Erosion (Seismic)",
        "path": "/docs/toolbox-technical-manuals/risk-calculations-suite/typical-event-tree-database/v1.0/Concentrated-Leak-Erosion-Seismic"
      }
    ],
    "Spillways Hydrologic": [
      {
        "label": "Unlined Spillway Erosion",
        "path": "/docs/toolbox-technical-manuals/risk-calculations-suite/typical-event-tree-database/v1.0/Unlined-Spillway-Erosion"
      }
    ]
  },
  "v1.5": {
    "Geotechnical Hydrologic": [
      {
        "label": "Generic Internal Erosion",
        "path": "/docs/toolbox-technical-manuals/risk-calculations-suite/typical-event-tree-database/v1.0/Generic-Internal-Erosion"
      }
    ],
    "Geotechnical Seismic": [
      {
        "label": "Concentrated Leak Erosion (Seismic)",
        "path": "/docs/toolbox-technical-manuals/risk-calculations-suite/typical-event-tree-database/v1.0/Concentrated-Leak-Erosion-Seismic"
      }
    ],
    "Spillways Hydrologic": [
      {
        "label": "Unlined Spillway Erosion",
        "path": "/docs/toolbox-technical-manuals/risk-calculations-suite/typical-event-tree-database/v1.0/Unlined-Spillway-Erosion"
      }
    ]
  }
}

Usage

This script is automatically run on project start, build, and deploy. No additional execution of this script is required.

generateReportIdMap.js

Overview

This Node.js script scans the docs/ folder structure to automatically generate a reportIdMap.js file in src/. It identifies documentation paths based on versioned subfolders (e.g., v1.0, v2.1) and builds unique report IDs based on the folder hierarchy.

What It Does

Recursively walks the docs/ directory.
Identifies folders with names matching a version pattern like v1.0, v2.1, etc.
Constructs a unique reportId in the format: <subHub>-<documentName>-<version>
- Where:
  - subHub is the folder two levels above the version folder
  - documentName is the folder directly above the version folder
  - version is the version folder name (e.g., v1.0)
Maps the full relative path to the generated report ID.
Saves the result as an exported JavaScript object in src/reportIdMap.js.

info

If the folder structure does not contain enough levels (i.e., it lacks a parent document or subHub folder), the script skips that entry and logs a warning.

Output

The output file (reportIdMap.js) is saved to: src/reportIdMap.js. It exports an object mapping documentation paths to unique report IDs. The structure looks like this:

// Auto-generated. Do not edit.
const reportIdMap = {
  "desktop-applications/lifesim/users-guide/v1.0": "lifesim-users-guide-v1.0",
  "desktop-applications/rmc-bestfit/users-guide/v1.0":
    "rmc-bestfit-users-guide-v1.0",
  "desktop-applications/rmc-rfa/users-guide/v1.0": "rmc-rfa-users-guide-v1.0",
  "desktop-applications/rmc-totalrisk/users-guide/v1.0":
    "rmc-totalrisk-users-guide-v1.0",
  "toolbox-technical-manuals/internal-erosion-suite/backward-erosion-piping-progression/v1.0":
    "internal-erosion-suite-backward-erosion-piping-progression-v1.0",
  "toolbox-technical-manuals/internal-erosion-suite/filter-evaluation-continuation/v1.0":
    "internal-erosion-suite-filter-evaluation-continuation-v1.0",
  "web-applications/lst/users-guide/v1.0": "lst-users-guide-v1.0",
};
module.exports = reportIdMap;

Usage

This script is automatically run on project start, build, and deploy. No additional execution of this script is required. It is used during the build process to allow React components to reference documentation paths by their unique report IDs.

generateSidebars.js

Overview

This script automatically generates a structured sidebars.js file for the RMC Software Documentation Docusaurus site, based on the organization of .mdx files within the docs/ directory.

What It Does

Recursively walks the docs/ directory to find all .mdx files.
Groups files into categories based on their folder structure.
Constructs a sidebar structure that follows the standard document layout and naming convention defined in Docs Folder.
Generates a sidebars.js file that exports a structured object for Docusaurus navigation.

tip

This script supports special-case logic for documents that require unique sidebar handling. Contact a site administrator if special-case logic is needed.

Output

The output file is saved to: sidebars.js. It exports an object that defines the sidebar structure for Docusaurus. The structure looks like this:

rmcTotalriskusersGuide_v1_0: {
    "Users Guide": [
      {
        "type": "category",
        "label": "Document Information",
        "collapsible": true,
        "collapsed": true,
        "items": [
          {
            "type": "doc",
            "id": "desktop-applications/rmc-totalrisk/users-guide/v1.0/document-info",
            "label": "Document Info"
          },
          {
            "type": "doc",
            "id": "desktop-applications/rmc-totalrisk/users-guide/v1.0/version-history",
            "label": "Version History"
          }
        ]
      },
      {
        "type": "category",
        "label": "Main Report",
        "collapsible": true,
        "collapsed": false,
        "items": [
          {
            "type": "doc",
            "id": "desktop-applications/rmc-totalrisk/users-guide/v1.0/preface",
            "label": "Preface"
          },
          {
            "type": "doc",
            "id": "desktop-applications/rmc-totalrisk/users-guide/v1.0/welcome",
            "label": "Welcome to RMC-TotalRisk"
          }
        ]
      },
      {
        "type": "category",
        "label": "Appendices",
        "collapsible": true,
        "collapsed": true,
        "items": [
          {
            "type": "doc",
            "id": "desktop-applications/rmc-totalrisk/users-guide/v1.0/appendix-acronyms",
            "label": "Appendix A - Acronyms"
          }
        ]
      }
    ]
  },

Usage

This script is automatically run on project start, build, and deploy. No additional execution of this script is required. The generated sidebars.js file will be used by Docusaurus to render the sidebar navigation for the documentation site.

versions.js

Overview

This script scans the docs/ folder to identify and collect version information. It produces JSON files that list the latest versions available, all available versions, and generates URLs for use with the Algolia crawler to index the correct documentation versions.

What It Does

Defines the base folders where documentation groups live (e.g., "desktop-applications", "toolbox-technical-manuals", "web-applications").
Recursively walks through these folders to detect version folders that match a pattern like v1.0, v2.3, etc.
Identifies the latest version by sorting the version folders descending alphabetically.
Collects all versions found for each document group.
Outputs three JSON files: latest version map, full version list, and Algolia crawler URLs.

Output

latestVersions.json: Contains a mapping of document paths to their latest version folder.

{
  "toolbox-technical-manuals/internal-erosion-suite/backward-erosion-piping-progression": "v1.0",
  "toolbox-technical-manuals/internal-erosion-suite/filter-evaluation-continuation": "v1.0",
  "desktop-applications/lifesim/users-guide": "v1.0",
  "desktop-applications/rmc-bestfit/users-guide": "v1.0",
  "desktop-applications/rmc-totalrisk/users-guide": "v1.0",
  "web-applications/lst/users-guide": "v1.0"
}

versionList.json: Contains a mapping of document paths to all available version folders.

{
  "toolbox-technical-manuals/internal-erosion-suite/backward-erosion-piping-progression": [
    "v1.0"
  ],
  "toolbox-technical-manuals/internal-erosion-suite/filter-evaluation-continuation": [
    "v1.0"
  ]
}

algoliaCrawlerVersions.json: Contains start URLs and discovery patterns based on the latest versions for Algolia's documentation crawler.

Usage

This script is automatically run on project start, build, and deploy. No additional execution of this script is required.

The output JSON files will be saved in the static/versions folder.

counters.js​

Overview​

What It Does​

Output​

Usage​

generateEventTreeToc.js​

Overview​

What It Does​

Output​

Usage​

generateReportIdMap.js​

Overview​

What It Does​

Output​

Usage​

generateSidebars.js​

Overview​

What It Does​

Output​

Usage​

versions.js​

Overview​

What It Does​

Output​

Usage​

counters.js

Overview

What It Does

Output

Usage

generateEventTreeToc.js

Overview

What It Does

Output

Usage

generateReportIdMap.js

Overview

What It Does

Output

Usage

generateSidebars.js

Overview

What It Does

Output

Usage

versions.js

Overview

What It Does

Output

Usage