MDX Validation

MDX Validation

This guide explains how to validate MDX files in your project to prevent build errors before deployment.

Overview

We’ve implemented a comprehensive validation system to catch MDX syntax errors before they cause build failures on Vercel. The system includes:

1. Custom MDX Validator - Catches common syntax errors
2. Build Validation - Ensures files actually build correctly
3. Agent Self-Validation - tribe-content-builder agent validates its own output

Validation Commands

Quick Validation

npm run validate:mdx

Runs syntax checks on all MDX files in the project.

Complete Validation (Recommended)

npm run validate:all

Runs MDX validation AND attempts to build the project. This is the most thorough check as it catches both syntax errors and build-time issues.

Common Issues Detected

1. Unclosed or Mismatched Tags

The validator checks for:

• Unclosed HTML/JSX tags
• Mismatched opening/closing tags
• Duplicate wrapper elements

Example of error:

🚫 Error: Line 25: Unclosed tag: <div>

2. JSX Syntax Issues

• Using class instead of className
• Unescaped braces in JSX
• Invalid JSX expressions

Example of warning:

⚠️ Warning: Line 15: Found 'class=' attribute - use 'className=' for JSX

3. Style Block Issues

When using <style> blocks in MDX, they must be properly escaped:

{/* ❌ This will cause build errors */}
<style>
  .my-class { color: red; }
</style>

{/* ✅ Correct way */}
<style>{`
  .my-class { color: red; }
`}</style>

Tribe Content Builder Agent

The tribe-content-builder agent has been updated with self-validation capabilities. It will:

1. Check for proper tag matching
2. Verify no duplicate wrapper elements
3. Validate frontmatter syntax
4. Ensure proper JSX usage

The agent includes a built-in checklist that runs before returning any MDX content.

Pre-commit Validation (Optional)

To automatically run validation before each commit, you can add a pre-commit hook:

# Install husky (optional)
npm install --save-dev husky

# Add pre-commit hook
npx husky add .husky/pre-commit "npm run validate:mdx"

Fixing Common Issues

Duplicate Wrapper Elements

When using wrapper divs, ensure they’re only opened once:

{/* ❌ Wrong - duplicate wrapper */}
<div className="survey-page">
  {/* content */}
</div>

<div className="survey-page">
  {/* more content */}
</div>

{/* ✅ Correct - single wrapper */}
<div className="survey-page">
  {/* all content */}
</div>

Frontmatter Validation

Ensure frontmatter is valid YAML:

---
title: "My Page"
description: "Page description"
# ❌ Missing quote after description
title: "Unclosed string

# ✅ Correct YAML
title: "My Page"
description: "Page description"
---

Best Practices

1. Always run npm run validate:all before deploying
2. Fix warnings to improve code quality
3. Use the tribe-content-builder agent for new MDX files - it has built-in validation
4. Test style blocks carefully - they often cause build issues

Validation Output

The validator provides clear feedback:

🔍 Validating MDX files...

📄 /path/to/file.mdx
  ✅ No issues found

📄 /path/to/problem.mdx
  ❌ Issues found:
    🚫 Error: Line 15: Unclosed tag <div>
    ⚠️ Warning: Line 20: Found 'class=' attribute

📊 Validation Summary:
  Errors: 1
  Warnings: 1

❌ Validation failed with errors!

• ✅ = No issues
• 🚫 = Error (must fix)
• ⚠️ = Warning (recommended to fix)

Troubleshooting

Build Passes but Validator Shows Errors

The custom validator may have false positives. If the build succeeds, the file is likely fine.

Validator Misses an Error

The validator catches common issues but may not catch everything. Always run the full build with npm run validate:all.

Style Block Errors

Style blocks in MDX can be tricky. The safest approach is to use template literals:

<style>{`
  .class { property: value; }
`}</style>

Integration with CI/CD

To add validation to your CI/CD pipeline:

# Example GitHub Actions
- name: Validate MDX
  run: npm run validate:all

This ensures no broken MDX files reach production.

Technical Details

Validation Script Location

The custom validation script is located at: /scripts/validate-mdx.js

It checks for:

• Tag matching and nesting
• Duplicate wrapper elements
• Proper JSX syntax
• Style block formatting
• Frontmatter validation

Configuration Files

• eslint.config.js - ESLint configuration for MDX
• .markdownlint-cli2.jsonc - Markdown linting rules
• package.json - Contains validation scripts

Real-World Example

The client survey page (/protected/member/client-survey.mdx) demonstrates the importance of validation. It initially failed due to:

1. Unclosed <div> tags
2. Improperly formatted style blocks

These issues were caught and fixed before deployment, preventing build failures on Vercel.

Pro Tip: Always run npm run validate:all before pushing changes. This catches both syntax errors and build-time issues that might only appear during the actual build process.