Skip to main content

MDX Writing Guide for Documentation

This guide helps you write documentation that's compatible with Docusaurus MDX (Markdown + JSX) compilation.

What is MDX?​

MDX allows you to use JSX (React components) in Markdown files. However, this means certain characters have special meaning and can cause compilation errors if not handled correctly.

Common Issues and Solutions​

1. Comparison Operators (<, >, <=, >=)​

Problem: MDX interprets < and > as JSX tag delimiters, causing compilation errors.

❌ Wrong:

- **High Confidence (>80%)**: Auto-create PR
- **Low Confidence (<60%)**: Create issue only
- Errors (>10/hour) trigger alerts

✅ Correct:

- **High Confidence** (`>80%`): Auto-create PR
- **Low Confidence** (`<60%`): Create issue only
- Errors (`>10/hour`) trigger alerts

Solutions:

  • Wrap in backticks: `>80%`
  • Use HTML entities: &gt;80% or &lt;60%
  • Use code blocks for complex expressions

2. HTML Tags​

Problem: MDX processes HTML/JSX tags, which can break if malformed.

❌ Wrong:

Use <div> for containers
Version < 2.0 is deprecated

✅ Correct:

Use `<div>` for containers
Version `&lt; 2.0` is deprecated
Or: Version `< 2.0` (in code block)

Solution: Escape < and > when they're not meant to be HTML tags.

3. Curly Braces {}​

Problem: MDX interprets {} as JSX expressions, even inside code blocks!

❌ Wrong:

```csharp
var message = $"Error: {analysis.ErrorSummary}";

**✅ Correct:**
```markdown
```csharp
var message = $"Error: {{analysis.ErrorSummary}}";

**Solution:** 
- **Inside code blocks:** Double the curly braces: `{{` becomes `{` and `}}` becomes `}`
- **Outside code blocks:** Wrap in double backticks: `` `{variable}` ``

### 4. JSX Components

**Problem:** If you want to use actual JSX components, you need proper syntax.

**✅ Correct:**
```markdown
import { Admonition } from '@theme/Admonition';

<Admonition type="warning">
  This is a warning!
</Admonition>

5. Code Blocks with Special Characters​

Problem: Code blocks are generally safe, BUT curly braces still need escaping!

❌ Wrong:

```csharp
var msg = $"Error: {analysis.ErrorSummary}";
```

✅ Correct:

```csharp
var msg = $"Error: {{analysis.ErrorSummary}}";
```

Important: Even inside code blocks, MDX parses {} as JSX. Double them: {{ → {, }} → }

6. URLs with Query Parameters​

Problem: URLs with ? and & are usually fine, but be careful with fragments.

✅ Correct:

[Link](https://example.com?param=value&other=123)

7. Email Addresses​

Problem: Email addresses with < and > can cause issues.

❌ Wrong:

Contact <user@example.com>

✅ Correct:

Contact `user@example.com`
Or: Contact user@example.com (without brackets)

Quick Reference: Escaping Characters​

CharacterEscape MethodExample
<Backticks or &lt;`>80%` or &gt;80%
>Backticks or &gt;`<60%` or &lt;60%
{Double backticks`{variable}`
}Double backticks`{variable}`

Best Practices​

  1. Use Code Formatting for Comparisons

    • Wrap comparison operators in backticks: `>80%`
    • Use code blocks for complex expressions

  2. Test Your Documentation

    • Build locally before pushing: npm run build in Documentation repo
    • Check for MDX compilation errors

  3. When in Doubt, Use Code Blocks

    • Code blocks are always safe
    • Use them for any content with special characters

  4. Avoid Raw HTML

    • Prefer Markdown syntax
    • Use Docusaurus components instead of raw HTML

  5. Check Existing Documentation

    • Look at similar patterns in other docs
    • Follow established conventions

Common Patterns​

Percentages and Ranges​

✅ **High** (`>80%`)
✅ **Medium** (`60-80%`)
✅ **Low** (`<60%`)

Version Comparisons​

✅ Version `` `>= 2.0` `` required
✅ Version `&gt;= 2.0` required

Mathematical Expressions​

✅ Use `` `x > 0` `` for positive values
✅ Formula: `` `a < b < c` ``

Code Examples​

✅ ```csharp
   if (value > threshold) { }

## Troubleshooting

### Error: "Unexpected character before name"
- **Cause:** `<` or `>` interpreted as JSX
- **Fix:** Wrap in backticks or use HTML entities

### Error: "Unexpected token"
- **Cause:** Curly braces `{}` interpreted as JSX expression
- **Fix:** Use double backticks or escape

### Error: "Expected a closing tag"
- **Cause:** Malformed HTML/JSX
- **Fix:** Ensure all tags are properly closed or escaped

## Examples from Our Documentation

### ✅ Good Example
```markdown
### Confidence Thresholds

- **High Confidence** (`>80%`): Auto-create PR
- **Medium Confidence** (`60-80%`): Create issue, suggest fix
- **Low Confidence** (`<60%`): Create issue only, manual review

❌ Bad Example (Will Break)​

### Confidence Thresholds

- **High Confidence (>80%)**: Auto-create PR
- **Low Confidence (<60%)**: Create issue only

Additional Resources​

Checklist Before Committing​

  • No bare < or > characters (wrap in backticks)
  • No bare { or } outside code blocks (wrap in backticks)
  • All code examples are in proper code blocks
  • Documentation builds successfully (npm run build)
  • No MDX compilation warnings or errors

Remember: When in doubt, wrap special characters in backticks or use code blocks!