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: >80% or <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}";

**⚠️ Sometimes Works (but can fail with complex patterns):**
```markdown
```csharp
var message = $"Error: {{analysis.ErrorSummary}}";

**✅ Best Solution (when double braces fail):**
```markdown
```csharp
var message = $"Error: {analysis.ErrorSummary}";

**Solutions (in order of preference):**
1. **Double braces** (works for simple cases): `{{` becomes `{` and `}}` becomes `}`
2. **HTML entities** (use when double braces cause parsing errors): 
   - `{` = `{`
   - `}` = `}`
   - Example: `{{variable}}` renders as `{{variable}}`
3. **Outside code blocks:** Wrap in double backticks: `` `{variable}` ``

**When to use HTML entities:**
- When you have nested braces like `{{{{variable}}}}` that MDX tries to parse
- When MDX reports "variable is not defined" errors
- When double-brace escaping still causes acorn parsing errors
- When you have many string interpolations in code examples

### 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

Character	Escape Method	Example
<	Backticks or &lt;	`>80%` or &gt;80%
>	Backticks or &gt;	`<60%` or &lt;60%
{	Double braces {{ or HTML &lbrace;	{{variable}} or &lbrace;variable&rbrace;
}	Double braces }} or HTML &rbrace;	{{variable}} or &lbrace;variable&rbrace;

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 `>= 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" or "variable is not defined"
- **Cause:** Curly braces `{}` interpreted as JSX expression, even in code blocks
- **Fix:** 
  1. Try double braces first: `{{variable}}`
  2. If that fails, use HTML entities: `&lbrace;variable&rbrace;`
  3. For nested patterns, always use HTML entities: `&lbrace;&lbrace;variable&rbrace;&rbrace;`

### 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

• MDX Documentation
• Docusaurus Markdown Features
• Docusaurus MDX and React

Checklist Before Committing

• No bare < or > characters (wrap in backticks)
• No bare { or } outside code blocks (wrap in backticks)
• Curly braces in code blocks are escaped (double braces {{}} or HTML entities {})
• If you get "variable is not defined" errors, use HTML entities instead of double braces
• All code examples are in proper code blocks
• Documentation builds successfully (npm run build)
• No MDX compilation warnings or errors

Real-World Example: C# String Interpolation

Problem: C# string interpolation uses {variable} syntax, which conflicts with MDX JSX parsing. When you have nested braces or complex patterns, double-brace escaping can fail.

❌ Wrong (causes "variable is not defined" error):

```csharp
var confidencePercent = analysis.Confidence + "%";
return $@"Confidence: {{confidencePercent}}";

**⚠️ Sometimes Works (but can fail with nested patterns):**
```markdown
```csharp
return $@"Confidence: {{analysis.Confidence}}%";

**✅ Correct (use HTML entities when double braces fail):**
```markdown
```csharp
var confidenceWithPercent = confidenceValue + "%";
return $@"Confidence: {{confidenceWithPercent}}";

This renders as: `Confidence: {{confidenceWithPercent}}` in the final output, which is correct C# syntax. MDX won't try to parse it as JSX because HTML entities are treated as literal text.

---

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