Creating and Editing Pages

This comprehensive guide covers everything you need to know about creating and editing documentation pages using MDX (Markdown + JSX). Whether you're a complete beginner or have some experience, this guide will help you master the fundamentals of writing documentation for the RMC Software Documentation project.

---

What is MDX?

MDX is a file format that combines:

• Markdown - A simple, human-readable syntax for formatting text
• JSX - React component syntax that lets you embed interactive elements

Why MDX?

• Write most content in simple Markdown (headings, lists, bold, italic)
• Insert React components when you need advanced features (figures, tables, equations)
• Best of both worlds: simplicity + power

File Extension: All documentation pages use the .mdx extension

---

Creating Your First MDX File

Step 1: Determine Location

First, figure out where your new file should go in the docs/ folder. See Project Structure for guidance on folder organization.

Example path for a new chapter:

docs/desktop-applications/lifesim/users-guide/v1.0/05-new-chapter.mdx

Step 2: Create the File

In Visual Studio Code:

1. Navigate to the appropriate folder in the Explorer sidebar
2. Right-click on the folder
3. Select "New File"
4. Name it following the convention: ##-chapter-name.mdx
   • ## - Two-digit number for ordering (e.g., 05)
   • chapter-name - Lowercase with hyphens (e.g., new-chapter)
   • .mdx - File extension

Step 3: Add Front Matter

Every MDX file should start with front matter - metadata wrapped in triple dashes:

---
title: Chapter Title
---

The title appears in:

• Browser tab
• Search results
• Page metadata

Step 4: Add Content

Start writing your content using Markdown and JSX:

---
title: Methodology
---

# Methodology

This chapter describes the analytical methodology used in the assessment.

## Overview

The analysis follows a three-step process...

Step 5: Import Components (As Needed)

If you'll use React components, import them at the top (after front matter):

---
title: Results
---

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

# Results

Content goes here...

---

Front Matter Reference

Front matter is YAML-formatted metadata at the beginning of your MDX file.

Basic Front Matter

Most pages only need a title:

---
title: Preface
---

Extended Front Matter (Document Info Pages)

The 00-document-info.mdx file uses extended front matter for the <DocumentMetadata> component:

---
reportDate: November 2023
reportType: Computer Program Document
reportTitle: RMC Backward Erosion Piping (Progression) Toolbox
reportSubTitle: RMC Internal Erosion Suite
reportAuthors: ["Tim O'Leary, Risk Management Center"]
reportAbstract: The spreadsheet tools contained in this toolbox deterministically and probabilistically assess the likelihood of backward erosion piping progression using the adjusted Schmertmann (2000) method and the adjusted calculation rule of Sellmeijer et al. (2011).
reportSubjectTerms: ['Internal erosion', 'backward erosion piping', 'Schmertmann', 'Sellmeijer']
responsiblePersonName: Tim O'Leary
responsiblePersonNumber: 502-315-6599
---

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

<DocumentMetadata />

Available Front Matter Fields

Field	Type	Description	Example
title	String	Page title (required)	"Methodology"
sidebar_label	String	Override sidebar text	"Method"
reportDate	String	Document date	"November 2023"
reportType	String	Document type	"User's Guide"
reportTitle	String	Full document title	"LifeSim User's Guide"
reportSubTitle	String	Subtitle	"Version 1.0"
reportAuthors	Array	List of authors	["Author Name"]
reportAbstract	String	Document summary	"This guide..."
reportSubjectTerms	Array	Keywords	["topic1", "topic2"]

---

Markdown Syntax Guide

Markdown is the foundation of your content. Here's a comprehensive reference.

Headings

Use # symbols to create headings. More # means lower level:

# Heading 1 (H1)

## Heading 2 (H2)

### Heading 3 (H3)

#### Heading 4 (H4)

##### Heading 5 (H5)

###### Heading 6 (H6)

Best Practices:

• Use only ONE H1 (#) per page - this is your main title
• Use H2 (##) for major sections
• Use H3 (###) for subsections
• Don't skip levels (don't go from H2 to H4)
• Headings automatically appear in the table of contents

Example Structure:

# Main Title (H1)

## Introduction (H2)

### Background (H3)

### Objectives (H3)

## Methodology (H2)

### Data Collection (H3)

### Analysis Approach (H3)

---

Text Formatting

Basic Formatting

**Bold text**
_Italic text_
**_Bold and italic text_**
~~Strikethrough text~~
`Inline code`

Renders as:

• Bold text
• Italic text
• Bold and italic text
• Strikethrough text
• Inline code

HTML Formatting

You can also use HTML tags for additional formatting:

<b>Bold</b>
<strong>Strong (bold)</strong>
<i>Italic</i>
<em>Emphasis (italic)</em>
<u>Underline</u>
<sub>Subscript</sub>
<sup>Superscript</sup>
<mark>Highlighted text</mark>
<small>Small text</small>

When to use HTML instead of Markdown:

• Subscripts and superscripts (H₂O, x²)
• Underlined text
• Combining formats not supported by Markdown

Example:

The chemical formula for water is H<sub>2</sub>O.

Einstein's famous equation is E=mc<sup>2</sup>.

---

Paragraphs and Line Breaks

Paragraphs

Separate paragraphs with a blank line:

This is the first paragraph.

This is the second paragraph.

Line Breaks

Method 1: End a line with two spaces

Line one (followed by two spaces)  
Line two

Method 2: Use <br /> tag

Line one<br />
Line two

Method 3: Use <p> tags

<p>First paragraph</p>
<p>Second paragraph</p>

---

Lists

Unordered (Bullet) Lists

Use -, *, or +:

- Item 1
- Item 2
- Item 3
  - Nested item 3.1
  - Nested item 3.2
    - Deeply nested 3.2.1
- Item 4

Renders as:

• Item 1
• Item 2
• Item 3
  • Nested item 3.1
  • Nested item 3.2
    • Deeply nested 3.2.1
• Item 4

Recommendation: Use Markdown bullets only for short, simple lists. For grouped content that needs consistent styling or collapsible details, use <CollectionList> instead.

Ordered (Numbered) Lists

Use numbers followed by periods:

1. First item
2. Second item
3. Third item
   1. Nested item 3.1
   2. Nested item 3.2
4. Fourth item

Renders as:

1. First item
2. Second item
3. Third item
   1. Nested item 3.1
   2. Nested item 3.2
4. Fourth item

Pro Tip: You can use 1. for all items and Markdown will auto-number:

1. First item
1. Second item
1. Third item

This still renders as 1, 2, 3. Useful if you need to reorder items later!

Limitation

Markdown numbered lists have a critical limitation - if a numbered list is interrupted by a paragraph or other content, the numbering resets to 1. There is no way to continue numbering from where you left off in standard Markdown.

Example of the problem:

1. First step
2. Second step

This is an interrupting paragraph.

3. Third step (This will render as "1. Third step")

Recommendation: For step-by-step procedures (especially with sub-steps or interrupting content), use <ProcessList> instead of Markdown numbering to keep formatting and numbering consistent. The <ProcessList> component maintains proper sequential numbering even when steps are interrupted by paragraphs, notes, or other content.

Mixed Lists

Combine ordered and unordered lists:

1. First step
   - Substep A
   - Substep B
2. Second step
   - Substep A
   - Substep B

Task Lists

Create checkboxes with - [ ] and - [x]:

- [x] Completed task
- [ ] Incomplete task
- [ ] Another incomplete task

Renders as:

• Completed task
• Incomplete task
• Another incomplete task

Recommendation: Avoid task list checkboxes in this project since they are not interactive. Use <ProcessList> or <CollectionList> with clear labels (for example, "Required", "Optional", "Completed") to avoid implying interactivity.

---

Links

External Links

[Link text](https://example.com)
[Link with title](https://example.com 'Hover text')

Example:

Visit the [USACE website](https://www.usace.army.mil/) for more information.

Internal Links (Within Documentation)

Link to other pages in your documentation:

[Project Structure](./03-project-structure.mdx)
[React Components](./07-react-components.mdx)

Relative path rules:

• ./ - Same folder
• ../ - Parent folder
• ../../ - Two levels up

Example paths:

[Sibling page](./02-versioning-system.mdx)
[Parent folder page](../users-guide/v1.0/01-preface.mdx)

Anchor Links (Within Same Page)

Link to headings on the same page:

[Jump to Methodology](#methodology)

Rules:

• Use # followed by heading text
• Convert to lowercase
• Replace spaces with hyphens
• Remove special characters

Examples:

## Data Analysis Results

[Link to section](#data-analysis-results)

## 4.2 Model Validation

[Link to section](#42-model-validation)

Reference-Style Links

Define links once, use multiple times:

[Link 1][ref1]
[Link 2][ref1]

[ref1]: https://example.com 'Link title'

---

Images

Inline Images (Markdown)

Basic image syntax:

![Alt text](path/to/image.png)
![Alt text](path/to/image.png 'Title text')

note

Markdown images are supported, but not recommended. Prefer <Figure> (numbered) or <FigureNoRef> (unnumbered) for consistency, cross-references, and visual clarity across documents.

Images with Figure Component (Recommended)

For numbered figures with captions:

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

<Figure
  figKey="fig-workflow"
  src="/figures/desktop-applications/lifesim/users-guide/v1.0/workflow.png"
  alt="LifeSim workflow diagram"
  caption="Overall workflow for LifeSim analysis"
  width="80%"
/>;

Benefits:

• Automatic figure numbering
• Professional captions
• Cross-references
• Consistent styling

See React Components for full documentation.

---

Blockquotes

Create blockquotes with >:

> This is a blockquote.
> It can span multiple lines.

Renders as:

This is a blockquote. It can span multiple lines.

Nested Blockquotes

> First level
>
> > Second level
> >
> > > Third level

Blockquotes with Other Elements

> ### Heading in Blockquote
>
> - List item 1
> - List item 2
>
> Regular text in blockquote.

---

Horizontal Rules

Create dividers with three or more hyphens, asterisks, or underscores:

---
---

---

All render as:

---

Use horizontal rules to:

• Separate major sections
• Create visual breaks
• Divide content thematically

---

Tables

Markdown table syntax is available, but its use is not recommended. Use the built-in table components for all tables to keep styling and numbering consistent across documents.

Recommended components:

• <TableVertical>
• <TableVericalNoRef>
• <TableHorizontal>

See React Components for usage and examples.

---

Code Blocks

Inline Code

Wrap with single backticks:

Use the `npm start` command to run the development server.

Renders as: Use the npm start command to run the development server.

Fenced Code Blocks

Wrap with triple backticks:

```
function hello() {
  console.log("Hello, world!");
}
```

Syntax Highlighting

Specify language after opening backticks:

```javascript
function hello() {
  console.log('Hello, world!');
}
```

Supported languages:

• javascript / js
• python / py
• java
• cpp / c
• bash / shell
• json
• markdown / md
• html
• css
• sql
• And many more!

Code Block with Title

```javascript title="example.js"
function greet(name) {
  return `Hello, ${name}!`;
}
```

Highlighting Lines

Highlight specific lines with {line-numbers}:

```javascript {2-3}
function hello() {
  console.log('This line is highlighted');
  console.log('This line too');
  console.log('This line is not');
}
```

Line Numbers

Show line numbers with showLineNumbers:

```python showLineNumbers
def calculate_area(radius):
    pi = 3.14159
    return pi * radius ** 2
```

---

Mathematical Equations

This project supports LaTeX math equations through KaTeX.

Inline Math

Wrap with single $:

The equation $E = mc^2$ is Einstein's famous formula.

Renders as: The equation $E = mc^2$ is Einstein's famous formula.

Display Math (Block)

Wrap with double $$:

$$
x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$

Renders as:

$$x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$$

Recommendation: Markdown math is supported, but it is not recommended for standalone equations. Use inline $...$ only for short inline expressions, and use the <Equation> component for standalone equations so numbering and cross-references stay consistent.

Numbered Equations (Use Component)

For automatic equation numbering and cross-references:

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

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

LaTeX Syntax Quick Reference:

Symbol	LaTeX	Symbol	LaTeX
α	\alpha	β	\beta
γ	\gamma	Δ	\Delta
∑	\sum	∫	\int
√	\sqrt{x}	∞	\infty
≤	\leq	≥	\geq
±	\pm	×	\times

For full LaTeX reference, see KaTeX documentation.

---

Admonitions (Callout Boxes)

Docusaurus provides built-in admonitions for important notes:

Types

Note:

:::note
This is a note admonition.
:::

note

This is a note admonition.

Tip:

:::tip
This is a helpful tip!
:::

tip

This is a helpful tip!

Info:

:::info
This is informational content.
:::

info

This is informational content.

Warning:

:::warning
This is a warning - be careful!
:::

warning

This is a warning - be careful!

Danger:

:::danger
This is dangerous - proceed with caution!
:::

danger

This is dangerous - proceed with caution!

Custom Titles

:::tip[Best Practice]
Always test your changes locally before committing!
:::

Best Practice

Always test your changes locally before committing!

Nested Content

:::warning[Important]
This admonition contains:

- Multiple paragraphs
- Lists
- **Formatted text**

And other Markdown elements.
:::

Important

This admonition contains:

• Multiple paragraphs
• Lists
• Formatted text

And other Markdown elements.

---

MDX-Specific Features

MDX extends Markdown with JSX (React) capabilities.

Importing Components

Import React components at the top of your file (after front matter):

---
title: Results
---

import Figure from '@site/src/components/Figure';
import TableVertical from '@site/src/components/TableVertical';
import Equation from '@site/src/components/Equation';
import Citation from '@site/src/components/Citation';

Import syntax:

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

The @site alias refers to the project root, so you don't need relative paths.

Using Components

Once imported, use components with JSX syntax:

<Figure figKey="fig-1" src="/figures/path/to/image.png" alt="Description" caption="Figure caption text" />

Key differences from HTML:

• Self-closing tags must end with />
• Props use camelCase (figKey not fig-key)
• String props use quotes: alt="text"
• Boolean props: autoNumber={true} or just autoNumber

Comments in MDX

Markdown Comments (Don't use)

<!-- This HTML comment is visible in MDX -->

JSX Comments (Use these)

{
  /* This comment is hidden in MDX */
}

When to use comments:

• Leave notes for other contributors
• Temporarily disable content
• Explain complex logic

---

Best Practices

Document Structure

Every document should follow this structure:

---
title: Chapter Title
---

import [Components] from [Paths];

# Chapter Title (H1)

Brief introduction paragraph.

## First Major Section (H2)

Content...

### Subsection (H3)

Content...

## Second Major Section (H2)

Content...

## Summary (H2)

Conclusion...

Naming Conventions

File Names

• Use lowercase letters
• Separate words with hyphens
• Include two-digit prefix
• Use .mdx extension

Examples:

• ✅ 01-preface.mdx
• ✅ 04-methodology.mdx
• ✅ 10-appendix-acronyms.mdx
• ❌ Chapter1.mdx
• ❌ 04_Methodology.mdx

Component Keys

Use descriptive, unique keys:

• Figures: figKey="fig-workflow"
• Tables: tableKey="table-results"
• Equations: equationKey="eq-quadratic"

Format: type-description in kebab-case

Cross-Referencing

Link to Figures

See <FigureReference figKey="fig-workflow" /> for the analysis workflow.

Link to Tables

<TableReference tableKey="table-results" /> shows the final results.

Link to Equations

Using <EquationReference equationKey="eq-quadratic" />, we can solve...

Accessibility

Alt Text for Images

Always provide descriptive alt text:

<Figure
  figKey="fig-1"
  src="/figures/workflow.png"
  alt="Flowchart showing three steps: data input, analysis, and output generation"
  caption="Analysis workflow"
/>

Alt text should:

• Describe the content of the image
• Be concise but complete
• Not include "image of" or "picture of"

Heading Hierarchy

Maintain proper heading levels:

✅ Correct:

# Title (H1)

## Section (H2)

### Subsection (H3)

❌ Incorrect:

# Title (H1)

### Subsection (H3) ← Skipped H2!

Link Text

Use descriptive link text:

✅ Good: [Download the LifeSim User's Guide](link)
❌ Bad: [Click here](link)

Writing Style

Be Concise

✅ Good: The model calculates risk using frequency and consequence data.
❌ Wordy: The model performs calculations that determine the risk by utilizing both frequency information and consequence data.

Use Active Voice

Use third-person active voice. That means the subject performs the action (active), and the subject is a noun like "the software" or "the model" rather than "I" or "we" (third person).

✅ Third-person active: The software calculates risk.
❌ First-person: We calculate risk.
❌ Passive: Risk is calculated by the software.

✅ Active: The software analyzes the data.
❌ Passive: The data is analyzed by the software.

Define Acronyms

First use: Risk Management Center (RMC)
Subsequent: RMC

---

Common Patterns and Examples

Example 1: Creating a New Chapter from Scratch

File: docs/desktop-applications/lifesim/users-guide/v1.0/05-validation.mdx

---
title: Model Validation
---

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

# Model Validation

This chapter presents the validation studies performed to verify the accuracy and reliability of the LifeSim model.

## Overview

Model validation is essential to ensure that simulation results accurately represent real-world conditions <Citation citationKey="Smith2020" />.

## Validation Approach

The validation process followed these steps:

1. **Historical data collection** - Gathered data from past events
2. **Model calibration** - Adjusted parameters to match observations
3. **Sensitivity analysis** - Tested model response to parameter variations

### Historical Data

<TableVertical
  tableKey="table-validation-data"
  alt="Historical validation data"
  headers={[[{ value: 'Event' }, { value: 'Date' }, { value: 'Observed Value' }, { value: 'Modeled Value' }]]}
  columns={[
    [{ value: 'Event A' }, { value: 'Event B' }, { value: 'Event C' }],
    [{ value: '2015' }, { value: '2017' }, { value: '2019' }],
    [{ value: '125' }, { value: '234' }, { value: '189' }],
    [{ value: '122' }, { value: '238' }, { value: '191' }],
  ]}
  caption="Comparison of observed and modeled values"
/>

## Results

<Figure
  figKey="fig-validation"
  src="/figures/desktop-applications/lifesim/users-guide/v1.0/validation-results.png"
  alt="Scatter plot comparing observed versus modeled values with best-fit line"
  caption="Validation results showing strong agreement between observed and modeled values"
  width="80%"
/>

The validation results demonstrate excellent agreement between model predictions and historical observations.

## Summary

The validation studies confirm that LifeSim produces accurate and reliable results across a range of scenarios.

Example 2: Adding Figures with Cross-References

---
title: Results
---

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

# Results

## Workflow Diagram

<Figure figKey="fig-workflow" src="/figures/workflow.png" alt="Flowchart showing analysis steps" caption="Analysis workflow diagram" />

## Output Visualization

<Figure figKey="fig-output" src="/figures/output.png" alt="Graph showing results over time" caption="Model output results" />

## Discussion

The analysis follows the workflow shown in <FigureReference figKey="fig-workflow" />. Results are visualized in <FigureReference figKey="fig-output" />, demonstrating clear trends over the simulation period.

Example 3: Using Equations

---
title: Methodology
---

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

# Methodology

## Risk Calculation

Risk is calculated as the product of probability and consequence, as shown in <EquationReference equationKey="eq-risk" />:

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

Where:

> $R$ = Risk (double space so the next term renders on the next line)
> $P$ = Probability of event (double space so the next term renders on the next line)
> $C$ = Consequence of event (no double space required for final term)

For multiple events, total risk is the sum of individual risks as defined in <EquationReference equationKey="eq-total-risk" />:

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

Example 4: Managing Citations

---
title: Literature Review
---

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

# Literature Review

## Background

The original methodology was developed by Smith <Citation citationKey="Smith2015" />. Subsequent improvements were made by Jones and colleagues <Citation citationKey="Jones2018" /> <Citation citationKey="JonesSmith2020" />.

## Current Approach

The current approach integrates these earlier methods <Citation citationKey="Smith2015" /> <Citation citationKey="Jones2018" /> with modern computational techniques.

<CitationFootnote />

---

Troubleshooting Common Issues

Build Errors

Problem: MDX file causes build to fail

Solutions:

• Check for unclosed components: <Figure /> not <Figure>
• Verify all imports are correct
• Check for unescaped special characters
• Review error message carefully - it usually indicates the line number

Broken Links

Problem: Links don't work or return 404

Solutions:

• Use relative paths: ./file.mdx not just file
• Include .mdx extension
• Check capitalization matches exactly
• Verify file actually exists at that path

Images Not Displaying

Problem: Images don't appear

Solutions:

• Check path starts with /figures/ (note the leading slash)
• Verify image exists in static/figures/ folder
• Check filename matches exactly (case-sensitive)
• Ensure image file format is supported (PNG, JPG, SVG)

Component Import Errors

Problem: "Component is not defined"

Solutions:

• Add import statement at top of file
• Check component name matches exactly (case-sensitive)
• Verify path is correct: @site/src/components/ComponentName
• Check component actually exists

Incorrect Numbering

Problem: Figure/table/equation numbers are wrong

Solutions:

• Stop the dev server (Ctrl+C) and restart it with npm start - numbering scripts run automatically on startup
• Ensure each component has a unique key
• Check that keys don't conflict across pages

Sidebar Not Updating

Problem: New file doesn't appear in sidebar

Solutions:

• Stop the dev server (Ctrl+C) and restart it with npm start - sidebar generation runs automatically on startup
• Check file is in correct location
• Verify filename follows naming convention

---

Next Steps

Now that you understand how to create and edit MDX pages, you're ready to:

1. Explore React Components - See React Components for the complete component library
2. Review Examples - Browse existing documentation in docs/ for real-world examples
3. Convert Documents - Use the DOCX Converter to convert Word files

Ready to start writing? Create your first MDX file and test it locally with npm start!