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

React Components Reference

Introduction​

This comprehensive guide documents all React components available for use in your MDX documentation. Components are organized by category to help you quickly find the right tool for your needs.

What Are React Components?​

React components are reusable UI elements that you can insert into your MDX files. They handle complex layouts, automatic numbering, and consistent styling without requiring you to write HTML or CSS.

Benefits:

  • ✅ Automatic numbering (figures, tables, equations, videos)
  • ✅ Cross-referencing between elements
  • ✅ Consistent formatting across all documentation
  • ✅ Professional appearance
  • ✅ Responsive design (works on all screen sizes)

How to Use Components​

Basic workflow:

  1. Import the component at the top of your MDX file
  2. Use the component with JSX syntax
  3. Configure with props (properties)

Example:

---
title: My Chapter
---

import Figure from '@site/src/components/Figure';

# My Chapter

<Figure
  figKey="fig-workflow"
  src="/figures/my-document/workflow.png"
  alt="Workflow diagram"
  caption="Overall analysis workflow"
  width="80%"
/>

Component Categories​

Components are organized into these categories:

Quick Component Selector​

Need to display an image?

Need to create a table?

Need to show a process?

Need to add equations?

Document Metadata​

DocumentMetadata ⭐​

⭐ COMMONLY USED COMPONENT

Purpose: Displays report metadata in a professional table format at the beginning of documents.

When to use:

  • 00-document-info.mdx files
  • Beginning of technical reports
  • Any document requiring formal metadata

Import:

import DocumentMetadata from '@site/src/components/DocumentMetadata';

Usage:

---
reportDate: November 2023
reportType: User's Guide
reportTitle: LifeSim Life Safety Model
reportSubTitle: Version 1.0
reportAuthors: ["John Doe, Risk Management Center", "Jane Smith, RMC"]
reportAbstract: This guide provides instructions for using LifeSim software...
reportSubjectTerms: ["life safety", "dam failure", "risk analysis"]
responsiblePersonName: John Doe
responsiblePersonNumber: 555-0100
---

import DocumentMetadata from '@site/src/components/DocumentMetadata';

<DocumentMetadata />

Props: None - reads from front matter

Front Matter Fields:

FieldTypeDescription
reportDateStringPublication date
reportTypeStringDocument type (User's Guide, Technical Manual, etc.)
reportTitleStringFull document title
reportSubTitleStringSubtitle or version
reportAuthorsArrayList of author names
reportAbstractStringDocument summary
reportSubjectTermsArrayKeywords/topics
responsiblePersonNameStringPoint of contact
responsiblePersonNumberStringContact phone number

TableVersionHistory ⭐​

⭐ COMMONLY USED COMPONENT

Purpose: Displays document version history in a formatted table.

When to use:

  • 00-version-history.mdx files
  • Tracking document revisions

Import:

import TableVersionHistory from '@site/src/components/TableVersionHistory';

Usage:

<TableVersionHistory
  versions={['1.0', '1.1']}
  dates={['November 2023', 'March 2024']}
  descriptions={['Initial release', 'Updated methodology section, added new examples']}
  modifiedBy={['J. Doe', 'J. Doe']}
  reviewedBy={['J. Smith', 'J. Smith']}
  approvedBy={['A. Manager', 'A. Manager']}
/>

Advanced Usage with Multiple Description Items:

<TableVersionHistory
  versions={['1.0', '1.1']}
  dates={['November 2023', 'March 2024']}
  descriptions={['Initial release', ['Updated methodology section', 'Added new examples', 'Fixed typos']]}
  modifiedBy={['J. Doe', 'J. Doe']}
  reviewedBy={['J. Smith', 'J. Smith']}
  approvedBy={['A. Manager', 'A. Manager']}
/>

Props:

PropTypeRequiredDefaultDescription
versionsArrayNo[]Version numbers (e.g., "1.0")
datesArrayNo[]Release dates
descriptionsArrayNo[]Description of changes (string or array of strings for bullet list)
modifiedByArrayNo[]Document authors
reviewedByArrayNo[]Technical reviewers
approvedByArrayNo[]Approving authorities

Figures & Images​

Figure ⭐​

⭐ COMMONLY USED COMPONENT

Purpose: Numbered figure with caption and automatic cross-referencing.

When to use:

  • Any diagram, chart, or image that needs a figure number
  • Images that will be referenced from text
  • Professional documentation figures

Import:

import Figure from '@site/src/components/Figure';

Basic Usage:

<Figure
  figKey="fig-workflow"
  src="/figures/desktop-applications/lifesim/users-guide/v1.0/workflow.png"
  alt="Flowchart showing three-step analysis process"
  caption="LifeSim analysis workflow"
/>

Advanced Usage:

<Figure
  figKey="fig-results"
  src="/figures/my-software/results-graph.png"
  alt="Bar chart comparing model results across three scenarios"
  caption="Comparison of model results for baseline, alternative A, and alternative B scenarios"
  width="90%"
  background="transparent"
/>

Props:

PropTypeRequiredDefaultDescription
figKeyStringYes-Unique identifier for numbering and cross-refs
srcStringYes-Image path (relative to static folder)
altStringYes-Accessibility description
captionStringYes-Figure caption text
widthStringNo"80%"Display width
backgroundStringNo"filled""filled" or "transparent" background
idStringNo-Custom HTML id (defaults to figKey)

Tips:

  • Use descriptive figKey values: fig-workflow, fig-results-1
  • Always start paths with /figures/
  • Write detailed alt text for accessibility
  • Keep captions concise but descriptive

Common Mistakes:

  • ❌ Forgetting leading slash: figures/image.png
    • ✅ Correct: /figures/image.png
  • ❌ Duplicate figKey values
    • ✅ Each figure needs unique key

FigureReference ⭐​

⭐ COMMONLY USED COMPONENT

Purpose: Creates cross-references to numbered figures.

When to use:

  • Referencing figures from body text
  • Creating figure call-outs

Import:

import FigureReference from '@site/src/components/FigureReference';

Usage:

The analysis workflow is shown in <FigureReference figKey="fig-workflow" />.

See <FigureReference figKey="fig-results" /> for detailed results.

Props:

PropTypeRequiredDescription
figKeyStringYesMust match a Figure's figKey

Output: Renders as clickable link: "Figure 1", "Figure 2", etc.

FigureInline​

Purpose: Small inline image that displays at text height (1em), useful for icons or inline graphics.

When to use:

  • Inline icons within text
  • Small decorative graphics
  • Inline symbols or badges

Import:

import FigureInline from '@site/src/components/FigureInline';

Usage:

Click the <FigureInline src="/figures/icons/settings-icon.png" /> icon to open settings.

Props:

PropTypeRequiredDescription
srcStringYesImage path (relative to static folder)

FigureNoRef​

Purpose: Simple image display without caption or numbering.

When to use:

  • Quick image insertion
  • Screenshots in tutorials
  • Images that don't need captions

Import:

import FigureNoRef from '@site/src/components/FigureNoRef';

Usage:

<FigureNoRef src="/figures/icons/warning-icon.png" alt="Warning icon" width="100px" />

Props:

PropTypeRequiredDefaultDescription
srcStringYes-Image path
altStringYes-Accessibility description
widthStringNo"80%"Display width
backgroundStringNo"filled""filled" or "transparent"

Tables​

TableVertical ⭐​

⭐ COMMONLY USED COMPONENT

Purpose: Standard columnar table with automatic numbering.

When to use:

  • Standard data tables
  • Comparison tables
  • Results tables
  • Most tabular data

Import:

import TableVertical from '@site/src/components/TableVertical';

Basic Usage:

<TableVertical
  tableKey="table-parameters"
  alt="Model input parameters"
  headers={[[{ value: 'Parameter' }, { value: 'Value' }, { value: 'Units' }]]}
  columns={[
    ['Population', 'Flow Rate', 'Duration'],
    ['10,000', '5,000', '24'],
    ['people', 'cfs', 'hours'],
  ]}
  caption="Model input parameters"
/>

Props:

PropTypeRequiredDefaultDescription
tableKeyStringYes-Unique identifier
altStringYes-Accessibility description
headersArrayYes-Array of header row arrays
columnsArrayYes-Array of column arrays
captionStringYes-Table caption
colWidthsArrayNo-Column widths (e.g., [14, "20ch", "minmax(16ch, 1fr)"])
colAlignArrayNo-Column horizontal alignment (e.g., ["left", "center", "right"])
headerAlignArrayNo-Header horizontal alignment (e.g., ["center", "center", "right"])
colVAlignArrayNo-Column vertical alignment (e.g., ["top", "middle", "bottom"])
headerVAlignArrayNo-Header vertical alignment (e.g., ["middle", "bottom", "middle"])
widthModeStringNo"full""full" or "intrinsic"
footnotesArrayNo-Array of footnote strings or ReactNodes
idStringNo-Custom HTML id (defaults to tableKey)

Advanced Usage with Merged Cells:

<TableVertical
  tableKey="table-merged"
  alt="Example table with merged cells"
  headers={[
    [
      { value: 'Scenario' },
      { value: 'Hydraulic Parameters', colSpan: 2 }, // This header spans 2 columns
      { value: 'Notes' },
    ],
  ]}
  columns={[
    // Column 1: Scenario names
    [
      { value: 'Baseline', rowSpan: 2 }, // This cell spans 2 rows, so row 2 in this column is AUTO-SKIPPED
      'Alternative A',
      'Alternative B',
    ],
    // Column 2: Flow rates
    [
      '5,000 cfs', // Row 1
      '5,000 cfs', // Row 2 (Baseline's 2nd row)
      '7,500 cfs', // Row 3 (Alternative A)
      '10,000 cfs', // Row 4 (Alternative B)
    ],
    // Column 3: Velocities
    [
      '10 fps', // Row 1
      '12 fps', // Row 2 (Baseline's 2nd row)
      '15 fps', // Row 3 (Alternative A)
      '18 fps', // Row 4 (Alternative B)
    ],
    // Column 4: Notes
    [
      'Normal conditions', // Row 1
      'High water', // Row 2 (Baseline's 2nd row)
      'Moderate risk', // Row 3 (Alternative A)
      'High risk scenario', // Row 4 (Alternative B)
    ],
  ]}
  caption="Table demonstrating merged cells"
/>

Important Notes on Merged Cells:

  • Column spanning (colSpan): Used in headers to make a header span multiple columns. Other header cells in that row are pushed to the right.

  • Row spanning (rowSpan): When a cell spans multiple rows, you MUST still provide values for ALL rows in the other columns. The component handles skipping the spanned cells automatically.

  • Key rule: Think of columns as providing data for every visible row. If Column 1 Row 1 has rowSpan: 2, you still need to provide data for Column 2 Row 2, Column 3 Row 2, etc. The rowSpan only affects its own column.

  • Counting rows: In the example above, "Baseline" spans 2 rows, creating 4 total rows (2 for Baseline + 1 for Alt A + 1 for Alt B). All other columns must have 4 values.

Advanced Usage with Alignment and Footnotes:

<TableVertical
  tableKey="table-advanced"
  alt="Advanced table with custom alignment"
  headers={[[{ value: 'Item' }, { value: 'Value' }, { value: 'Units' }]]}
  columns={[
    ['Population', 'Flow Rate', 'Duration'],
    ['10,000', '5,000', '24'],
    ['people', 'cfs', 'hours'],
  ]}
  caption="Model parameters with footnotes"
  colAlign={['left', 'right', 'center']}
  headerAlign={['center', 'center', 'center']}
  colWidths={['40%', '30%', '30%']}
  footnotes={['Flow rate measured at dam outlet', 'Duration represents time from breach initiation']}
/>

TableVerticalNoRef​

Purpose: Standard columnar table without automatic numbering or cross-referencing.

When to use:

  • Documentation tables (like props tables, reference tables)
  • Tables that don't need figure numbers
  • Tables that won't be referenced from text
  • Quick reference tables and guides

Import:

import TableVerticalNoRef from '@site/src/components/TableVerticalNoRef';

Usage:

<TableVerticalNoRef
  alt="Table: Prop, Type, Required, Default, Description"
  headers={[[{ value: 'Prop' }, { value: 'Type' }, { value: 'Required' }, { value: 'Default' }, { value: 'Description' }]]}
  columns={[
    [
      '<code>alt</code>',
      '<code>headers</code>',
      '<code>columns</code>',
      '<code>colWidths</code>',
      '<code>colAlign</code>',
      '<code>headerAlign</code>',
      '<code>colVAlign</code>',
      '<code>headerVAlign</code>',
      '<code>widthMode</code>',
      '<code>footnotes</code>',
    ],
    ['String', 'Array', 'Array', 'Array', 'Array', 'Array', 'Array', 'Array', 'String', 'Array'],
    ['Yes', 'Yes', 'Yes', 'No', 'No', 'No', 'No', 'No', 'No', 'No'],
    ['-', '-', '-', '-', '-', '-', '-', '-', '<code>&quot;full&quot;</code>', '-'],
    [
      'Accessibility description',
      'Array of header row arrays',
      'Array of column arrays',
      'Column widths (e.g., <code>[14, &quot;20ch&quot;, &quot;minmax(16ch, 1fr)&quot;]</code>)',
      'Column horizontal alignment (e.g., <code>[&quot;left&quot;, &quot;center&quot;, &quot;right&quot;]</code>)',
      'Header horizontal alignment (e.g., <code>[&quot;center&quot;, &quot;center&quot;, &quot;right&quot;]</code>)',
      'Column vertical alignment (e.g., <code>[&quot;top&quot;, &quot;middle&quot;, &quot;bottom&quot;]</code>)',
      'Header vertical alignment (e.g., <code>[&quot;middle&quot;, &quot;bottom&quot;, &quot;middle&quot;]</code>)',
      '<code>&quot;full&quot;</code> or <code>&quot;intrinsic&quot;</code>',
      'Array of footnote strings or ReactNodes',
    ],
  ]}
/>

Renders as:

PropTypeRequiredDefaultDescription
altStringYes-Accessibility description
headersArrayYes-Array of header row arrays
columnsArrayYes-Array of column arrays
colWidthsArrayNo-Column widths (e.g., [14, "20ch", "minmax(16ch, 1fr)"])
colAlignArrayNo-Column horizontal alignment (e.g., ["left", "center", "right"])
headerAlignArrayNo-Header horizontal alignment (e.g., ["center", "center", "right"])
colVAlignArrayNo-Column vertical alignment (e.g., ["top", "middle", "bottom"])
headerVAlignArrayNo-Header vertical alignment (e.g., ["middle", "bottom", "middle"])
widthModeStringNo"full""full" or "intrinsic"
footnotesArrayNo-Array of footnote strings or ReactNodes

Key Differences from TableVertical:

  • ❌ No tableKey prop (not numbered)
  • ❌ No caption prop (no caption display)
  • ❌ No id prop (no anchor linking)
  • ❌ Cannot be referenced with <TableReference>
  • ✅ All other features identical (merged cells, alignment, footnotes, etc.)

When to Choose:

  • Use TableVertical for content tables that need numbering ("Table 1", "Table 2")
  • Use TableVerticalNoRef for meta-tables (props, references, documentation tables)

TableReference ⭐​

⭐ COMMONLY USED COMPONENT

Purpose: Cross-references to numbered tables.

When to use:

  • Referencing tables from text

Import:

import TableReference from '@site/src/components/TableReference';

Usage:

Input parameters are listed in <TableReference tableKey="table-parameters" />.

Props:

PropTypeRequiredDescription
tableKeyStringYesMust match a table's tableKey

TableHorizontal​

Purpose: Row-based table where each row represents a record.

When to use:

  • Entity descriptions
  • Feature comparisons
  • Record-based data

Import:

import TableHorizontal from '@site/src/components/TableHorizontal';

Usage:

<TableHorizontal
  tableKey="table-software-comparison"
  alt="Software feature comparison"
  rows={[
    {
      header: 'Software A',
      data: ['Windows', 'Yes', '< 1 hour'],
    },
    {
      header: 'Software B',
      data: ['Windows, Mac', 'No', '2-3 hours'],
    },
  ]}
  columnHeaders={['Platform', 'Open Source', 'Runtime']}
  caption="Comparison of software features"
/>

Props:

PropTypeRequiredDescription
tableKeyStringYesUnique identifier
altStringYesAccessibility description
rowsArrayYesArray of row objects
columnHeadersArrayYesColumn header labels
captionStringYesTable caption

TableAcronyms​

Purpose: Two-column table specifically for acronyms and abbreviations.

When to use:

  • Appendix for acronyms
  • Abbreviation lists

Import:

import TableAcronyms from '@site/src/components/TableAcronyms';

Usage:

<TableAcronyms
  acronyms={[
    { acronym: 'USACE', definition: 'U.S. Army Corps of Engineers' },
    { acronym: 'RMC', definition: 'Risk Management Center' },
    { acronym: 'DST', definition: 'Dam Safety Toolbox' },
  ]}
/>

Props:

PropTypeRequiredDescription
acronymsArrayYesArray of {acronym, definition} objects

TableVerticalLeftAlign​

Purpose: Left-aligned variant of TableVertical.

When to use:

  • Tables with long text entries
  • Text-heavy tables

Usage: Same as TableVertical with left-aligned content.

Equations​

Equation ⭐​

⭐ COMMONLY USED COMPONENT

Purpose: Numbered LaTeX equation with automatic numbering.

When to use:

  • Mathematical formulas that need numbering
  • Equations referenced from text

Import:

import Equation from '@site/src/components/Equation';

Basic Usage:

<Equation equationKey="eq-risk" equation="R = P \times C" />

Advanced Usage:

<Equation equationKey="eq-quadratic" equation="\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}" />

Complex Example:

<Equation equationKey="eq-total-risk" equation="R_{total} = \sum_{i=1}^{n} P_i \times C_i" />

Props:

PropTypeRequiredDescription
equationKeyStringYesUnique identifier
equationStringYesLaTeX equation string

LaTeX Quick Reference:

Common Operations:

OperationLaTeXExample
Fraction\frac{numerator}{denominator}a/b
Square root\sqrt{x} or \sqrt[n]{x}√x or ⁿ√x
Subscriptx_i or x_{ij}xᵢ or xᵢⱼ
Superscriptx^2 or x^{n+1}x² or xⁿ⁺¹
Both sub/superx_i^2xᵢ²

Summation, Products, and Integrals:

SymbolLaTeXExample
Summation\sum_{i=1}^{n}∑ᵢ₌₁ⁿ
Product\prod_{i=1}^{n}∏ᵢ₌₁ⁿ
Integral\int_a^b∫ₐᵇ
Double integral\iint_D∬ᴰ
Limit\lim_{x \to \infty}lim x→∞

Greek Letters (Common):

LetterLaTeXLetterLaTeX
α (alpha)\alphaλ (lambda)\lambda
β (beta)\betaΛ (Lambda)\Lambda
γ (gamma)\gammaμ (mu)\mu
Γ (Gamma)\Gammaπ (pi)\pi
δ (delta)\deltaΠ (Pi)\Pi
Δ (Delta)\Deltaσ (sigma)\sigma
ε (epsilon)\epsilonΣ (Sigma)\Sigma
θ (theta)\thetaφ (phi)\phi

Comparison and Logic:

SymbolLaTeXSymbolLaTeX
≤\leq or \le≡\equiv
≥\geq or \ge∈\in
≠\neq or \ne∉\notin
≈\approx⊂\subset
∝\propto⊆\subseteq

Operations and Symbols:

SymbolLaTeXSymbolLaTeX
×\times∞\infty
÷\div∂\partial
±\pm∇\nabla
∓\mp∀\forall
·\cdot∃\exists

Parentheses and Brackets:

TypeLaTeXNotes
Parentheses( )Regular parentheses
Brackets[ ]Regular brackets
Braces\{ \}Braces require backslash
Auto-sizing\left( \frac{a}{b} \right)Auto-size to content height
Angle brackets\langle \rangleFor inner products, averages

Examples:

DescriptionLaTeX Code
Quadratic formulax = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
Binomial coefficient\binom{n}{k} = \frac{n!}{k!(n-k)!}
Partial derivative\frac{\partial f}{\partial x}
Matrix/vector notation\mathbf{x} = [x_1, x_2, \ldots, x_n]^T
ProbabilityP(A|B) = \frac{P(B|A)P(A)}{P(B)}

EquationReference​

Purpose: Cross-references to numbered equations.

When to use:

  • Referencing equations from text

Import:

import EquationReference from '@site/src/components/EquationReference';

Usage:

Using <EquationReference equationKey="eq-risk" />, we calculate total risk.

Props:

PropTypeRequiredDescription
equationKeyStringYesMust match an Equation's equationKey

EquationNoRef​

Purpose: Unnumbered LaTeX equation (display only).

When to use:

  • Supporting equations without numbering
  • Equation examples

Import:

import EquationNoRef from '@site/src/components/EquationNoRef';

Usage:

<EquationNoRef equation="E = mc^2" />

Props:

PropTypeRequiredDescription
equationStringYesLaTeX equation string

EquationChip​

Purpose: Inline badge/chip for short equations or variable names.

When to use:

  • Inline variable references
  • Short formulas in text
  • Mathematical notation badges

Import:

import EquationChip from '@site/src/components/EquationChip';

Usage:

The variable <EquationChip>$P$</EquationChip> represents probability, while <EquationChip>$C$</EquationChip> represents consequence.

Props:

PropTypeRequiredDescription
childrenReactNodeYesContent to display (typically LaTeX in $...$)

Citations​

Citation Numbering: Citations are numbered based on the order they first appear in the document, not alphabetically. The first citation you use becomes [1], the second becomes [2], and so on.

Citation​

Purpose: Inline citation reference that displays a numbered bracket link.

When to use:

  • Citing sources in text
  • Referencing bibliography entries

Import:

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

Usage:

The methodology was developed by Smith <Citation citationKey="Smith2020" />.

Multiple authors have studied this topic <Citation citationKey="Jones2018" /> <Citation citationKey="Brown2019" />.
IMPORTANT CITATION RULES

⚠️ Always include author/year text before the <Citation> component. The citation number should never appear alone without context.

✅ Good - Author/year precedes citation:
The methodology was developed by Smith <Citation citationKey="Smith2020" />.
Recent studies (Jones 2018 <Citation citationKey="Jones2018" />) show similar results.

❌ Bad - Citation number hanging alone:
The methodology was developed by <Citation citationKey="Smith2020" />.
<Citation citationKey="Jones2018" /> shows similar results.

Best Practices:

  • Include author name and/or year before the Citation component
  • Use natural sentence structure: "Smith (2020) demonstrated..." or "...was demonstrated by Smith [citation]."
  • For multiple citations, provide context for each: "Several studies (Jones 2018 [1], Brown 2019 [2]) have shown..."

Props:

PropTypeRequiredDescription
citationKeyStringYesMust match key in bib.json

Output: Renders as: [1], [2], etc. (clickable link to the citation in the CitationFootnote)

Numbering:

Citations are numbered in the order they first appear in the document.

CitationFootnote ⭐​

⭐ COMMONLY USED COMPONENT

Purpose: Displays list of citations used on current page in order of appearance.

When to use:

  • End of each page with citations
  • Before full bibliography

Import:

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

Usage:

## References

<CitationFootnote />

Props: None

Missing CitationFootnote

Insert the <CitationFootnote> component at the end of each MDX page. Failure to do so could result in build errors.

Bibliography​

Purpose: Full bibliography listing all references for a document in order of appearance.

When to use:

  • References appendix (typically at the end of a document)

Import:

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

Usage:

## Appendix: Bibliography

<Bibliography />

Props: None

How It Works:

The Bibliography component automatically determines which bib.json file to load based on the current page's location in the file structure. It maps the document path in /docs/ to the corresponding bib.json file in /bibliographies/, then displays all citations used throughout the document in numerical order based on first appearance (not alphabetically).

bib.json Placement

Ensure your bib.json file is placed in the correct location within the bibliographies directory structure. Incorrect placement will produce an error from the <Bibliography> component.

Content Organization​

ProcessList ⭐​

⭐ COMMONLY USED COMPONENT

Purpose: Step-by-step numbered procedures with optional sub-steps, expandable details, and freeform content blocks.

When to use:

  • Installation instructions
  • Workflows and procedures
  • Multi-step tutorials
  • Configuration guides
  • Any sequential process requiring clear numbering

Import:

import ProcessList from '@site/src/components/ProcessList';

Example 1: Simple Numbered List​

Basic numbered steps without sub-steps or details:

<ProcessList
  items={[
    { title: 'Install Python 3.8 or later' },
    { title: 'Download the software package from the website' },
    { title: 'Run the installer and follow the prompts' },
    { title: 'Verify installation by running python --version' },
  ]}
/>

Renders as:

  1. Install Python 3.8 or later
  2. Download the software package from the website
  3. Run the installer and follow the prompts
  4. Verify installation by running python --version

Example 2: Multi-Level Steps (Nested Sub-steps)​

Steps with lettered sub-steps (a, b, c, etc.):

<ProcessList
  items={[
    {
      title: 'Prepare your development environment',
      child: [
        { title: 'Install Node.js version 18 or later' },
        { title: 'Install Visual Studio Code or your preferred editor' },
        { title: 'Install Git for version control' },
      ],
    },
    {
      title: 'Clone and configure the project',
      child: [
        { title: 'Clone the repository from GitHub' },
        { title: 'Navigate to the project directory' },
        { title: 'Copy .env.example to .env and configure environment variables' },
      ],
    },
    {
      title: 'Install dependencies',
      child: [{ title: 'Run npm install in the project root' }, { title: 'Wait for all packages to download and install' }],
    },
    { title: 'Start the development server with npm run dev' },
  ]}
/>

Renders as:

  1. Prepare your development environment
    1. Install Node.js version 18 or later
    2. Install Visual Studio Code or your preferred editor
    3. Install Git for version control
  2. Clone and configure the project
    1. Clone the repository from GitHub
    2. Navigate to the project directory
    3. Copy .env.example to .env and configure environment variables
  3. Install dependencies
    1. Run npm install in the project root
    2. Wait for all packages to download and install
  4. Start the development server with npm run dev

Example 3: Expandable Details Panels​

Steps with expandable detail sections that can contain rich content:

<ProcessList
  items={[
    {
      title: 'Install required software',
      details: (
        <>
          <p>You'll need to install several software packages. Click each link to download:</p>
          <ul>
            <li>
              <a href="https://nodejs.org">Node.js</a> - JavaScript runtime
            </li>
            <li>
              <a href="https://code.visualstudio.com">VS Code</a> - Code editor
            </li>
            <li>
              <a href="https://git-scm.com">Git</a> - Version control
            </li>
          </ul>
          <p>
            <strong>Tip:</strong> Install the LTS (Long Term Support) versions for maximum stability.
          </p>
        </>
      ),
    },
    {
      title: 'Configure your environment',
      details: (
        <>
          <p>Create a .env file in the project root with the following variables:</p>
          <pre>
            {`DATABASE_URL=postgresql://localhost:5432/mydb
API_KEY=your_api_key_here
NODE_ENV=development`}
          </pre>
          <p>
            <strong>Note:</strong> Never commit your .env file to version control!
          </p>
        </>
      ),
    },
    {
      title: 'Run the application',
      details: (
        <>
          <p>Start the development server:</p>
          <pre>npm run dev</pre>
          <p>
            Open your browser to <code>http://localhost:3000</code>
          </p>
        </>
      ),
    },
  ]}
/>

Renders as:

  1. Install required software
  2. Configure your environment
  3. Run the application

Example 4: Combining Sub-steps and Details​

Complex workflow with both lettered sub-steps AND expandable details:

<ProcessList
  items={[
    {
      title: 'Pre-flight checks',
      child: [
        { title: 'Verify all team members have necessary access' },
        { title: 'Ensure backup systems are operational' },
        { title: 'Review deployment checklist' },
      ],
      details: (
        <>
          <p>
            <strong>Critical:</strong> Do not proceed with deployment until all pre-flight checks pass.
          </p>
          <p>Contact the DevOps team if any checks fail.</p>
        </>
      ),
    },
    {
      title: 'Deploy to staging',
      child: [
        { title: 'Run build process: npm run build' },
        { title: 'Deploy to staging environment' },
        { title: 'Run automated test suite' },
        { title: 'Perform manual smoke tests' },
      ],
      details: (
        <>
          <p>Deployment command:</p>
          <pre>npm run deploy:staging</pre>
          <p>Wait for the deployment to complete (typically 5-10 minutes).</p>
        </>
      ),
    },
    {
      title: 'Deploy to production',
      details: (
        <>
          <p>
            <strong>Warning:</strong> This will deploy to production. Ensure staging tests passed.
          </p>
          <pre>npm run deploy:production</pre>
          <p>Monitor application logs for any errors after deployment.</p>
        </>
      ),
    },
  ]}
/>

Renders as:

  1. Pre-flight checks
    1. Verify all team members have necessary access
    2. Ensure backup systems are operational
    3. Review deployment checklist
  2. Deploy to staging
    1. Run build process: npm run build
    2. Deploy to staging environment
    3. Run automated test suite
    4. Perform manual smoke tests
  3. Deploy to production

Example 5: Using Freeform Content Blocks​

Include un-numbered content blocks within a step (doesn't break numbering sequence):

<ProcessList
  items={[
    { title: 'Open the software application' },
    {
      title: 'Navigate to File > New Project',
      freeform: (
        <p>
          <strong>Note:</strong> First-time users will be prompted to complete the setup wizard before proceeding.
        </p>
      ),
    },
    { title: 'Enter project details in the dialog box' },
    { title: 'Click Create to initialize the project' },
  ]}
/>

Renders as:

  1. Open the software application
  2. Navigate to File > New Project

    Note: First-time users will be prompted to complete the setup wizard before proceeding.

  3. Enter project details in the dialog box
  4. Click Create to initialize the project

Example 6: Custom Starting Number and Indentation​

Control the starting number and indentation levels:

<ProcessList
  items={[{ title: 'Review preliminary analysis results' }, { title: 'Prepare final report sections' }, { title: 'Submit for technical review' }]}
  startAt={5}
  indentPx={40}
/>

Renders as:

  1. Review preliminary analysis results
  2. Prepare final report sections
  3. Submit for technical review

Props Reference​

Core Props:

PropTypeRequiredDefaultDescription
itemsArrayYes-Array of step objects (see Item Object Structure below)
startAtNumberNo1Starting number (e.g., 5 starts at "5")
indentPxNumberNo0Indentation per level in pixels
maxIndentPxNumberNoAutoMaximum total indentation (auto: 40% of container width)
bubbleSizePxNumberNo28Size of numbered circle bubbles in pixels
bubbleGapPxNumberNo10Gap between bubble and text in pixels
nowrapBooleanNofalsePrevent title text from wrapping

Child Layout Props:

PropTypeRequiredDefaultDescription
childBaseIndentPxNumberNo15Base indentation for child sub-steps
childIndentPxNumberNoSame as indentPxIndentation increment for nested sub-steps
childMaxIndentPxNumberNoAutoMaximum indentation for sub-steps

Item Object Structure​

FieldTypeDescription
titleString/ReactNodeStep text or JSX content
childArrayArray of sub-step objects (renders as a, b, c, etc.)
detailsReactNodeExpandable details panel with additional content
freeformReactNodeUn-numbered content block inserted between steps

Usage Notes:

  • title: Use for the main step description
  • child: Nest an array of sub-items that will be lettered (a, b, c, etc.)
  • details: Add expandable panels with rich content (paragraphs, code blocks, lists, etc.)
  • freeform: Insert callout boxes, warnings, notes between numbered steps without breaking numbering sequence

DocTabs ⭐​

⭐ COMMONLY USED COMPONENT

Purpose: Tabbed content panels for organizing alternative content, multi-platform instructions, or version comparisons.

When to use:

  • Version-specific documentation (different software versions or releases)
  • Alternative workflow methods (GUI vs API vs configuration file)
  • User role-based content (Administrator, Analyst, End User)
  • Different deployment scenarios (standalone vs distributed)
  • Tutorial vs reference content
  • Configuration examples for different use cases

Import:

import DocTabs from '@site/src/components/DocTabs';

Example 1: Version-Specific Documentation​

Show different instructions for different software versions:

<DocTabs
  items={[
    {
      title: 'Version 3.0',
      label: 'Version 3.0+',
      child: (
        <>
          <p>Configuration for version 3.0 and later:</p>
          <ol>
            <li>Open the Settings dialog</li>
            <li>Navigate to Data Sources → Import</li>
            <li>Select your file format from the dropdown</li>
            <li>Click Import and the software will auto-detect field mappings</li>
          </ol>
          <p>
            <strong>Note:</strong> Version 3.0 includes automatic field mapping.
          </p>
        </>
      ),
    },
    {
      title: 'Version 2.x',
      label: 'Version 2.x',
      child: (
        <>
          <p>Configuration for version 2.x:</p>
          <ol>
            <li>Open File → Import Data</li>
            <li>Browse to your data file</li>
            <li>Manually map each field using the Field Mapper dialog</li>
            <li>Click OK to complete the import</li>
          </ol>
          <p>
            <strong>Note:</strong> Manual field mapping is required in version 2.x.
          </p>
        </>
      ),
    },
    {
      title: 'Legacy',
      label: 'Version 1.x (Legacy)',
      child: (
        <>
          <p>Configuration for legacy version 1.x:</p>
          <p>Edit the configuration file manually:</p>
          <pre>
            {`[DataImport]
SourceFile=C:\\data\\input.csv
FieldMap=field1:col1,field2:col2`}
          </pre>
          <p>Then restart the application to apply changes.</p>
        </>
      ),
    },
  ]}
  defaultValue={0}
/>

Renders as:

Configuration for version 3.0 and later:

  1. Open the Settings dialog
  2. Navigate to Data Sources → Import
  3. Select your file format from the dropdown
  4. Click Import and the software will auto-detect field mappings

Note: Version 3.0 includes automatic field mapping.

Example 2: Alternative Workflow Methods​

Show different ways to accomplish the same task:

<DocTabs
  items={[
    {
      title: 'Interactive',
      label: 'Interactive Workflow',
      child: (
        <>
          <h4>Using the Interactive Interface</h4>
          <ol>
            <li>Click Tools → Run Analysis</li>
            <li>Select your input dataset from the list</li>
            <li>Configure parameters using the visual parameter editor</li>
            <li>Click Run to execute the analysis</li>
            <li>Review results in the Results Viewer</li>
          </ol>
          <p>
            <strong>Best for:</strong> Exploratory analysis, one-off computations, learning the software
          </p>
        </>
      ),
    },
    {
      title: 'Config File',
      label: 'Configuration File',
      child: (
        <>
          <h4>Using Configuration Files</h4>
          <p>Create a configuration file to define your analysis:</p>
          <pre>
            {`# analysis-config.yaml
input:
  dataset: simulation_results.csv
parameters:
  threshold: 0.95
  iterations: 1000
output:
  format: PDF
  location: ./reports/`}
          </pre>
          <p>
            Then execute: <code>run-analysis --config analysis-config.yaml</code>
          </p>
          <p>
            <strong>Best for:</strong> Reproducible workflows, version control, sharing configurations
          </p>
        </>
      ),
    },
    {
      title: 'Scripting',
      label: 'Scripting API',
      child: (
        <>
          <h4>Using the Scripting Interface</h4>
          <p>Automate your workflow with the built-in scripting API:</p>
          <pre>
            {`# analysis-script.py
from software import Analysis

analysis = Analysis()
analysis.load_data("simulation_results.csv")
analysis.set_parameters(threshold=0.95, iterations=1000)
results = analysis.run()
results.export("./reports/output.pdf")`}
          </pre>
          <p>
            <strong>Best for:</strong> Batch processing, automation, integration with other tools
          </p>
        </>
      ),
    },
  ]}
/>

Renders as:

Using the Interactive Interface

  1. Click Tools → Run Analysis
  2. Select your input dataset from the list
  3. Configure parameters using the visual parameter editor
  4. Click Run to execute the analysis
  5. Review results in the Results Viewer

Best for: Exploratory analysis, one-off computations, learning the software

Example 3: Deployment Scenarios​

Show configuration for different deployment types:

<DocTabs
  items={[
    {
      title: 'Standalone',
      label: 'Standalone',
      child: (
        <>
          <p>Configuration for standalone deployment:</p>
          <pre>
            {`# config.ini
[Deployment]
Mode=Standalone
Database=./data/local.db

[Performance]
MaxThreads=4
CacheSize=1GB`}
          </pre>
          <p>All data and processing occur on a single machine. Suitable for individual users or small projects.</p>
        </>
      ),
    },
    {
      title: 'Client-Server',
      label: 'Client-Server',
      child: (
        <>
          <p>Configuration for client-server deployment:</p>
          <pre>
            {`# config.ini
[Deployment]
Mode=Client
ServerHost=analysis-server.example.com
ServerPort=8080

[Connection]
Timeout=30
RetryAttempts=3`}
          </pre>
          <p>Multiple clients connect to a central server. Ideal for teams sharing data and computational resources.</p>
        </>
      ),
    },
    {
      title: 'Distributed',
      label: 'Distributed',
      child: (
        <>
          <p>Configuration for distributed deployment:</p>
          <pre>
            {`# config.ini
[Deployment]
Mode=Distributed
ClusterNodes=node1,node2,node3
LoadBalancer=load-balancer.example.com

[DistributedCompute]
PartitionStrategy=DataSize
MaxNodesPerJob=10`}
          </pre>
          <p>Computation distributed across multiple nodes. Designed for large-scale analyses and high-performance computing.</p>
        </>
      ),
    },
  ]}
  equalWidth={true}
  showDividers={true}
/>

Renders as:

Configuration for standalone deployment:

# config.ini [Deployment] Mode=Standalone Database=./data/local.db [Performance] MaxThreads=4 CacheSize=1GB

All data and processing occur on a single machine. Suitable for individual users or small projects.

Example 4: User Role-Based Content​

Different instructions based on user role and responsibilities:

<DocTabs
  items={[
    {
      title: 'End User',
      label: 'End User',
      value: 'enduser',
      child: (
        <>
          <h4>Running a Simulation</h4>
          <p>As an end user, you can run pre-configured simulations:</p>
          <ol>
            <li>Open the Simulation menu</li>
            <li>Select a simulation template from the library</li>
            <li>Review the input parameters (ask your analyst if you have questions)</li>
            <li>Click Run Simulation</li>
            <li>View results in the Output tab</li>
          </ol>
          <p>
            <strong>Note:</strong> Contact your analyst to create new simulation templates.
          </p>
        </>
      ),
    },
    {
      title: 'Analyst',
      label: 'Analyst',
      value: 'analyst',
      child: (
        <>
          <h4>Creating Simulation Templates</h4>
          <p>As an analyst, you can create and configure simulation templates:</p>
          <ul>
            <li>Design custom simulation scenarios</li>
            <li>Configure input parameters and validation rules</li>
            <li>Set up automated result processing</li>
            <li>Publish templates to the library for end users</li>
            <li>Review and approve simulation results</li>
          </ul>
          <p>
            <strong>Permissions:</strong> Template creation, data analysis, result review
          </p>
        </>
      ),
    },
    {
      title: 'Administrator',
      label: 'Administrator',
      value: 'admin',
      child: (
        <>
          <h4>System Administration</h4>
          <p>As an administrator, you manage the entire system:</p>
          <ul>
            <li>Manage user accounts and role assignments</li>
            <li>Configure system-wide settings and security policies</li>
            <li>Monitor system performance and resource usage</li>
            <li>Set up data connections and integration points</li>
            <li>Manage backup and recovery procedures</li>
            <li>Install updates and maintain the software</li>
          </ul>
          <p>
            <strong>Permissions:</strong> Full system access and configuration
          </p>
        </>
      ),
    },
  ]}
  defaultValue="enduser"
/>

Renders as:

Running a Simulation

As an end user, you can run pre-configured simulations:

  1. Open the Simulation menu
  2. Select a simulation template from the library
  3. Review the input parameters (ask your analyst if you have questions)
  4. Click Run Simulation
  5. View results in the Output tab

Note: Contact your analyst to create new simulation templates.

Example 5: Compact Tabs Without Dividers​

Shorter tab labels with custom styling:

<DocTabs
  items={[
    {
      title: 'Step1',
      label: 'Step 1',
      child: <p>First, open the application and create a new project.</p>,
    },
    {
      title: 'Step2',
      label: 'Step 2',
      child: <p>Next, import your data files using File → Import.</p>,
    },
    {
      title: 'Step3',
      label: 'Step 3',
      child: <p>Configure analysis parameters in the Settings panel.</p>,
    },
    {
      title: 'Step4',
      label: 'Step 4',
      child: <p>Run the analysis and review the results.</p>,
    },
  ]}
  equalWidth={false}
  showDividers={false}
  defaultValue={0}
/>

Renders as:

First, open the application and create a new project.

Props Reference​

PropTypeRequiredDefaultDescription
itemsArrayYes-Array of tab objects
defaultValueNumber/StringNo0Default active tab (0-based index or value string)
equalWidthBooleanNotrueMake all tabs equal width
showDividersBooleanNotrueShow vertical dividers between tabs

Tab Object Structure​

FieldTypeDescription
titleStringTab identifier (internal, for accessibility)
labelStringTab display text shown to users
valueStringOptional custom value (for defaultValue targeting)
childReactNodeTab content (can be any JSX/React elements)

Best Practices:

  • Use clear, concise tab labels (ideally 1-2 words)
  • Keep content length similar across tabs for consistent experience
  • Use defaultValue to show the most common/recommended option first
  • Consider mobile users - fewer, wider tabs work better on small screens
  • Don't nest DocTabs within DocTabs (use CollectionList for hierarchical content)

CollectionList ⭐​

⭐ COMMONLY USED COMPONENT

Purpose: Grouped expandable/collapsible items with optional numbering, multiple layout modes, and flexible styling options.

When to use:

  • FAQs (Frequently Asked Questions)
  • Feature lists and software capabilities
  • Expandable content groups
  • Card-based navigation
  • Module or chapter summaries
  • Troubleshooting guides

Import:

import CollectionList from '@site/src/components/CollectionList';

Example 1: Simple List (No Expandable Items)​

List of titles without children - items without a child property are not expandable:

<CollectionList
  title="Quick Reference"
  items={[
    { title: 'System Requirements: Windows 10 64-bit or later, 8GB RAM minimum' },
    { title: 'Installation Path: C:\\Program Files\\SoftwareName\\' },
    { title: 'Support Email: support@example.com' },
    { title: 'Documentation: https://docs.example.com' },
  ]}
/>

Renders as:

Quick Reference

  1. System Requirements: Windows 10 64-bit or later, 8GB RAM minimum
  2. Installation Path: C:\Program Files\SoftwareName\
  3. Support Email: support@example.com
  4. Documentation: https://docs.example.com

Example 2: Simple FAQ (First Item Open)​

Basic FAQ with the first item expanded by default:

<CollectionList
  title="Frequently Asked Questions"
  items={[
    {
      title: 'What is LifeSim?',
      child: (
        <>
          <p>
            LifeSim is a life safety model for estimating loss of life due to dam and levee failures. It combines hydraulic, population, and
            evacuation data to assess consequences.
          </p>
        </>
      ),
    },
    {
      title: 'What platforms are supported?',
      child: <p>LifeSim runs on Windows 10 and later. A 64-bit operating system is required.</p>,
    },
    {
      title: 'How long does a typical analysis take?',
      child: (
        <p>
          Analysis runtime depends on model complexity and grid resolution. Simple models may complete in minutes, while complex scenarios can take
          several hours.
        </p>
      ),
    },
    {
      title: 'Where can I find example projects?',
      child: (
        <>
          <p>Example projects are included with the software installation in the following directory:</p>
          <pre>C:\Program Files\LifeSim\Examples\</pre>
        </>
      ),
    },
  ]}
  defaultOpen="first"
/>

Renders as:

Frequently Asked Questions

  1. LifeSim is a life safety model for estimating loss of life due to dam and levee failures. It combines hydraulic, population, and evacuation data to assess consequences.

  2. LifeSim runs on Windows 10 and later. A 64-bit operating system is required.

  3. Analysis runtime depends on model complexity and grid resolution. Simple models may complete in minutes, while complex scenarios can take several hours.

  4. Example projects are included with the software installation in the following directory:

    C:\Program Files\LifeSim\Examples\

Example 2: Numbered List (All Items Expanded)​

Feature list with decimal numbering and expand/collapse all buttons:

<CollectionList
  title="Software Features"
  items={[
    {
      title: 'Hydraulic Routing',
      child: (
        <>
          <p>Advanced flood wave propagation modeling using the full 2D shallow water equations. Includes features for:</p>
          <ul>
            <li>Dam and levee breach modeling</li>
            <li>Terrain-based flow routing</li>
            <li>Time-varying boundary conditions</li>
          </ul>
        </>
      ),
    },
    {
      title: 'Population Analysis',
      child: (
        <>
          <p>Detailed population-at-risk calculations including:</p>
          <ul>
            <li>Census-based population distribution</li>
            <li>Building occupancy analysis</li>
            <li>Time-of-day population variations</li>
            <li>Vulnerable population identification</li>
          </ul>
        </>
      ),
    },
    {
      title: 'Evacuation Modeling',
      child: (
        <>
          <p>Time-dependent evacuation simulations with:</p>
          <ul>
            <li>Multiple evacuation scenarios</li>
            <li>Warning dissemination modeling</li>
            <li>Mobilization time estimates</li>
            <li>Safe destination identification</li>
          </ul>
        </>
      ),
    },
    {
      title: 'Results Visualization',
      child: (
        <>
          <p>Comprehensive visualization tools:</p>
          <ul>
            <li>Interactive 2D flood maps</li>
            <li>Time-series animations</li>
            <li>Statistical summary reports</li>
            <li>Export capabilities for GIS integration</li>
          </ul>
        </>
      ),
    },
  ]}
  autoNumber={true}
  numberStyle="decimal"
  showExpandAll={true}
  defaultOpen="all"
/>

Renders as:

Software Features

  1. Advanced flood wave propagation modeling using the full 2D shallow water equations. Includes features for:

    • Dam and levee breach modeling
    • Terrain-based flow routing
    • Time-varying boundary conditions

  2. Detailed population-at-risk calculations including:

    • Census-based population distribution
    • Building occupancy analysis
    • Time-of-day population variations
    • Vulnerable population identification

  3. Time-dependent evacuation simulations with:

    • Multiple evacuation scenarios
    • Warning dissemination modeling
    • Mobilization time estimates
    • Safe destination identification

  4. Comprehensive visualization tools:

    • Interactive 2D flood maps
    • Time-series animations
    • Statistical summary reports
    • Export capabilities for GIS integration

Example 4: Grid Layout with Cards (No Expandable Items)​

Card-based grid layout with titles only (no child property means no expand/collapse):

<CollectionList
  title="Analysis Modules"
  items={[
    { title: 'Consequence Estimation' },
    { title: 'Risk Assessment' },
    { title: 'Uncertainty Analysis' },
    { title: 'Sensitivity Analysis' },
    { title: 'Portfolio Analysis' },
    { title: 'Decision Analysis' },
  ]}
  layout="grid"
  columns={{ base: 1, sm: 2, md: 3, xl: 3 }}
/>

Renders as:

Analysis Modules

Consequence Estimation
Risk Assessment
Uncertainty Analysis
Sensitivity Analysis
Portfolio Analysis
Decision Analysis

Example 5: Different Numbering Styles​

Demonstrate various numbering formats:

<CollectionList
  title="Roman Numeral Numbering"
  items={[
    { title: 'Introduction', child: 'Overview of the methodology and approach.' },
    { title: 'Data Requirements', child: 'Description of required input data and sources.' },
    { title: 'Analysis Procedures', child: 'Step-by-step analysis instructions.' },
  ]}
  autoNumber={true}
  numberStyle="upper-roman"
  defaultOpen="none"
/>

</br>

<CollectionList
  title="Alphabetic Numbering"
  items={[
    { title: 'Scenario A: Sunny Day Failure', child: 'Failure occurs during normal operations with no precipitation.' },
    { title: 'Scenario B: PMF Event', child: 'Failure during Probable Maximum Flood event.' },
    { title: 'Scenario C: Seismic Event', child: 'Failure triggered by maximum credible earthquake.' },
  ]}
  autoNumber={true}
  numberStyle="upper-alpha"
  startAt={1}
/>

Renders as:

Roman Numeral Numbering

  1. Overview of the methodology and approach.
  2. Description of required input data and sources.
  3. Step-by-step analysis instructions.

Alphabetic Numbering

  1. Failure occurs during normal operations with no precipitation.
  2. Failure during Probable Maximum Flood event.
  3. Failure triggered by maximum credible earthquake.

Example 6: Specific Items Open by Default​

Control exactly which items are expanded using index array:

<CollectionList
  title="Chapter Summary"
  items={[
    {
      title: 'Chapter 1: Getting Started',
      child: 'Introduction to the software and basic concepts.',
    },
    {
      title: 'Chapter 2: Data Preparation',
      child: 'How to prepare and import data for analysis.',
    },
    {
      title: 'Chapter 3: Running Analyses',
      child: 'Step-by-step instructions for running various analysis types.',
    },
    {
      title: 'Chapter 4: Interpreting Results',
      child: 'Understanding and visualizing analysis outputs.',
    },
    {
      title: 'Chapter 5: Advanced Topics',
      child: 'Advanced features for experienced users.',
    },
  ]}
  defaultOpen={[1, 3]}
  autoNumber={true}
/>

Renders as:

Chapter Summary

  1. Introduction to the software and basic concepts.
  2. How to prepare and import data for analysis.
  3. Step-by-step instructions for running various analysis types.
  4. Understanding and visualizing analysis outputs.
  5. Advanced features for experienced users.

Props Reference​

PropTypeRequiredDefaultDescription
titleStringNo-Optional title displayed above the list
itemsArrayYes-Array of item objects (see below)
startAtNumberNo1Starting number for numbering (if autoNumber is true)
autoNumberBooleanNofalseEnable automatic numbering
numberStyleStringNo"decimal"Numbering format: "decimal", "upper-alpha", "lower-alpha", "upper-roman", "lower-roman"
defaultOpenString/ArrayNo"none"Control which items are expanded: "none", "first", "all", or array of indices (e.g., [0, 2])
showExpandAllBooleanNofalseShow expand all / collapse all buttons
layoutStringNo"stack"Layout mode: "stack" (vertical) or "grid" (cards)
columnsObjectNo-Grid columns for different breakpoints: { base: 1, sm: 2, md: 3, xl: 4 }

Item Object Structure​

FieldTypeDescription
titleString/ReactNodeItem title/heading (always visible)
childString/ReactNodeItem content (shown when expanded or if defaultOpen includes this item)

Best Practices:

  • FAQs: Can use defaultOpen="first" to show users there's expandable content
  • Feature lists: Can use defaultOpen="all" with showExpandAll={true} for easy navigation
  • Module navigation: Can use layout="grid" with appropriate column counts
  • Always-visible content: Set defaultOpen="all" and showExpandAll={false}
  • Keep item titles concise (under 10 words)
  • Use rich JSX content in child for better formatting

Multimedia​

Video​

Purpose: Numbered video component with automatic numbering.

When to use:

  • Tutorial videos
  • Demonstration videos
  • Multimedia documentation

Import:

import Video from '@site/src/components/Video';

Basic Usage:

<Video
  videoKey="video-tutorial"
  caption="Software installation tutorial"
  src="/videos/installation-tutorial.mp4"
  poster="/videos/installation-poster.jpg"
  width="90%"
/>

Multiple Sources:

<Video
  videoKey="video-demo"
  caption="Feature demonstration"
  sources={[
    { src: '/videos/demo.mp4', type: 'video/mp4' },
    { src: '/videos/demo.webm', type: 'video/webm' },
  ]}
  poster="/videos/demo-poster.jpg"
  controls={true}
/>

With Captions:

<Video
  videoKey="video-presentation"
  caption="Conference presentation"
  src="/videos/presentation.mp4"
  trackSrc="/videos/presentation-captions.vtt"
  trackLang="en"
  trackLabel="English"
/>

Props:

PropTypeRequiredDefaultDescription
videoKeyStringYes-Unique identifier
captionStringYes-Video caption
posterStringNo-Poster image path
srcStringNo-Single video source
sourcesArrayNo[]Multiple sources [{src, type}]
widthStringNo"80%"Display width
controlsBooleanNotrueShow video controls
autoPlayBooleanNofalseAuto-play on load
loopBooleanNofalseLoop playback
mutedBooleanNoAutoMute audio (auto=true if autoPlay)
playsInlineBooleanNotrueiOS inline playback
preloadStringNo"metadata"Preload strategy
trackSrcStringNo-VTT captions file
trackLangStringNo"en"Caption language
trackLabelStringNo"English"Caption label
creditStringNo-Video source/credit

VideoReference​

Purpose: Cross-references to numbered videos.

When to use:

  • Referencing videos from text

Import:

import VideoReference from '@site/src/components/VideoReference';

Usage:

See <VideoReference videoKey="video-tutorial" /> for installation instructions.

Props:

PropTypeRequiredDescription
videoKeyStringYesMust match a Video's videoKey

Button​

Purpose: Styled button or link.

When to use:

  • Call-to-action links
  • Navigation buttons
  • Download buttons

Import:

import Button from '@site/src/components/Button';

Link Button:

<Button href="/docs/getting-started">Get Started</Button>

External Link:

<Button href="https://example.com">Visit Website</Button>

Click Handler:

<Button onClick={() => alert('Clicked!')}>Click Me</Button>

Renders as:

Props:

PropTypeRequiredDescription
childrenReactNodeYesButton text/content
hrefStringNoLink URL (renders as <a>)
toStringNoInternal link (alias for href)
onClickFunctionNoClick handler (renders as <button>)
classNameStringNoAdditional CSS classes

Purpose: Styled navigation link with arrow.

When to use:

  • Section navigation
  • Included automatically in NavContainer
  • Rarely used standalone

Import:

import NavLink from '@site/src/components/NavLink';

Usage: Typically used internally by NavContainer.

Purpose: Navigation layout with version selector.

When to use:

  • Page navigation sections
  • Version-aware navigation

Import:

import NavContainer from '@site/src/components/NavContainer';

Usage:

<NavContainer navLink="../" navTitle="User's Guide" navDoc="lifesim-users-guide">
  <p>Navigation content here</p>
</NavContainer>

Props:

PropTypeRequiredDescription
navLinkStringYesParent link URL
navTitleStringYesNavigation title
navDocStringYesDocument identifier
childrenReactNodeYesNavigation content

VersionSelector​

Purpose: Dropdown for switching document versions.

When to use:

  • Included automatically in NavContainer
  • Rarely used standalone

Import:

import VersionSelector from '@site/src/components/VersionSelector';

Usage: Typically used internally by NavContainer.

Component Best Practices​

General Guidelines​

Always provide required props:

✅ Good:
<Figure
  figKey="fig-1"
  src="/figures/image.png"
  alt="Detailed description"
  caption="Informative caption"
/>

❌ Bad:
<Figure src="/figures/image.png" />  // Missing required props

Use unique keys:

✅ Good:
<Figure figKey="fig-workflow" ... />
<Figure figKey="fig-results" ... />

❌ Bad:
<Figure figKey="fig-1" ... />
<Figure figKey="fig-1" ... />  // Duplicate key!

Write descriptive alt text:

✅ Good:
alt="Bar chart comparing baseline, alternative A, and alternative B scenarios"

❌ Bad:
alt="Chart"
alt="Figure 1"

Accessibility​

All images need alt text:

  • Describe what's shown in the image
  • Don't say "image of" or "picture of"
  • Be specific and concise

Use semantic structure:

  • Headings in logical order
  • Proper table markup
  • Meaningful link text

Performance​

Optimize images:

  • Keep file sizes reasonable (< 500KB each)
  • Use appropriate formats (PNG for diagrams, JPG for photos)
  • Compress images before adding

Lazy loading:

  • Images and videos load automatically as needed
  • No action required from contributors

Common Mistakes​

Forgetting imports:

❌ Error: Component not defined
// Forgot to import Figure

✅ Fix:
import Figure from '@site/src/components/Figure';

Wrong path format:

❌ Bad:
src="figures/image.png"  // Missing leading slash
src="../figures/image.png"  // Relative path

✅ Good:
src="/figures/desktop-applications/software/v1.0/image.png"

Mismatched keys:

❌ Bad:
<Figure figKey="fig-workflow" ... />
...
<FigureReference figKey="fig-workflo" />  // Typo!

✅ Good:
<Figure figKey="fig-workflow" ... />
...
<FigureReference figKey="fig-workflow" />

Troubleshooting​

Component Not Rendering​

Problem: Component doesn't appear on page.

Solutions:

  1. Check import statement is correct
  2. Verify all required props are provided
  3. Check for typos in component name
  4. Look in browser console for error messages (if able; USG machines do not typically allow access to browser console)

Numbers Are Wrong​

Problem: Figure/table/equation numbers are incorrect.

Solutions:

  1. Check for duplicate keys
  2. Verify files are numbered correctly (01-, 02-, etc.)
  3. Restart dev server (Ctrl + C -> npm start) to trigger the counters script during build

Cross-References Broken​

Problem: References show "???" or don't link.

Solutions:

  1. Ensure referenced key exists
  2. Check for typos in keys
  3. Verify component is on a page that's been processed

Images Not Displaying​

Problem: Images show broken icon.

Solutions:

  1. Check path starts with /figures/
  2. Verify image exists at specified path
  3. Check filename matches exactly (case-sensitive)
  4. Ensure image format is supported (PNG, JPG, SVG)

Quick Reference Table​

Need to...Use ComponentImport
Show numbered figure<Figure>@site/src/components/Figure
Reference a figure<FigureReference>@site/src/components/FigureReference
Show numbered table<TableVertical>@site/src/components/TableVertical
Show numbered equation<Equation>@site/src/components/Equation
Add citation<Citation>@site/src/components/Citation
Step-by-step process<ProcessList>@site/src/components/ProcessList
Tabbed content<DocTabs>@site/src/components/DocTabs
Expandable list<CollectionList>@site/src/components/CollectionList
Video with caption<Video>@site/src/components/Video
Navigation button<Button>@site/src/components/Button
Document metadata<DocumentMetadata>@site/src/components/DocumentMetadata

Next Steps​

Now that you understand the available components:

  1. Practice: Try using components in a test MDX file
  2. Explore: Look at existing documentation for real-world examples
  3. Experiment: Test different props and configurations
  4. Reference: Bookmark this page for quick lookup

Related guides:

Need help? See Troubleshooting & FAQ for solutions to common issues.

Last updated on