Skip to main content

Docs Folder

The docs/ folder contains all .mdx documentation files for the RMC Software Documentation project. It is organized by application type and document, with a consistent structure for all documentation sets.

Folder Structure Overview​

The documentation is organized in a structured hierarchy to support scalability and clarity.

1. Root Documentation Folder​

  • docs/ - The root folder for all documentation content.

2. Hub Subfolders​

Each subfolder corresponds to a type of application, called a "hub":

  • desktop-applications/ – For desktop tools like RMC-TotalRisk, RMC-RFA, LifeSim, etc.

  • toolbox-technical-manuals/ – RMC Toolbox technical manuals

  • web-applications/ – For web tools like LST, DST, RRFT, etc.

3. Sub-Hub Subfolders​

Each hub folder contains folders for individual software or tool suites, called "sub-hubs":

  • rmc-totalrisk/ – Documentation for RMC-TotalRisk
  • internal-erosion-suite/ – Documentation for the Internal Erosion Toolbox
  • lst/ – Documentation for the LST web application

4. Document-Specific Subfolders​

Within each software folder, documents are grouped by title:

  • users-guide/
  • backward-erosion-piping-progression/

5. Version-Specific Subfolders​

Each document includes version folders, such as:

  • v1.0/
  • v1.1/
  • v2.0/

6. Chapter Files​

Each version folder contains one .mdx file per chapter, named using a consistent convention (e.g., 01-preface.mdx, 02-methodology.mdx, etc.).

Document Layout and Naming Convention​

Every chapter within a document should follow the naming convention:

##-document-title.mdx

The numeric prefix (##) determines the order of the chapter in the sidebar and ensures proper navigation.

Documents are organized into three main sections:

  1. Document Information
  2. Main Report
  3. Appendices

1. Document Information​

This section appears in a collapsible sidebar titled "Document Information" (collapsed by default). It includes two required chapters:

00-document-info.mdx​

  • Always the first chapter in the document.
  • Uses the <DocumentMetadata /> React component.
  • Provides metadata such as project title, authorship, document number, approval status, and publication date.

00-version-history.mdx​

  • Always the second chapter.
  • Uses the <TableVersionHistory /> component.
  • Displays version numbers, change summaries, dates, and the names of individuals who authored, reviewed, and approved each version.

2. Main Report​

This section appears in a collapsible sidebar titled "Main Report" (expanded by default).
Each chapter begins with a two-digit prefix that increases sequentially.

Example Chapter Filenames​

  • 01-preface.mdx (always the first chapter)
  • 02-chapter-2.mdx
  • 03-chapter-3.mdx
  • 04-methodology.mdx
  • 05-results.mdx

Chapters should follow a clear naming convention and reflect the actual content.

3. Appendices​

This section appears in a collapsible sidebar titled "Appendices" (collapsed by default).
Chapters continue the sequential numbering from the main report.

Example Appendix Filenames​

  • 06-appendix-acronyms.mdx
  • 07-appendix-analysis.mdx
  • 08-appendix-calculations.mdx

Appendices may include supplementary data, calculations, or additional figures.

warning

Important: Always verify that the numeric prefixes in filenames match the desired sidebar order. Inconsistent numbering can lead to broken navigation and reader confusion.

Example Directory Structures​

docs/
└── desktop-applications/
    └── rmc-totalrisk/
        └── users-guide/
            └── v1.0/
                ├── 00-document-info.mdx
                ├── 00-version-history.mdx
                ├── 01-preface.mdx
                ├── 02-chapter-1.mdx
                ├── 03-chapter-2.mdx
                └── 04-appendix-acronyms.mdx
docs/
└── toolbox-technical-manuals/
    └── internal-erosion-suite/
        └── backward-erosion-piping-progression/
            └── v1.1/
                ├── 00-document-info.mdx
                ├── 00-version-history.mdx
                ├── 01-preface.mdx
                ├── 02-chapter-1.mdx
                ├── 03-chapter-2.mdx
                └── 04-appendix-acronyms.mdx

Best Practices​

  • Use clear, consistent naming for all .mdx files.
  • Always start with 00-document-info.mdx and 00-version-history.mdx.
  • Use numeric prefixes (01-, 02-, etc.) for main chapters and appendices to ensure correct ordering in the sidebar.
  • Place all images, figures, and supporting files in the appropriate subfolders under static/.

For more on sidebar configuration and navigation, see the sidebars.js

Last updated on