MDX Beyond Markdown

MDX lets you embed React components inside Markdown. For documentation, that opens up possibilities plain Markdown can’t match.

What MDX Unlocks

Interactive examples. Wrap code in a component that runs it live. Users can tweak and see results without leaving the page.

Custom blocks. Create <APIEndpoint>, <CLICommand>, or <Warning> components that render consistently across all docs. HermesDocs includes several out of the box.

Imports. Reuse shared content, callouts, or diagrams by importing them. No copy-pasting.

How HermesDocs Uses MDX

Our docs collection supports both .md and .mdx files. Use MDX when you need components; stick to Markdown when you don’t. The frontmatter and rendering pipeline are identical.

---
title: API Reference
description: REST endpoints
---

import APIEndpoint from '@components/mdx/APIEndpoint.astro';

## Users

<APIEndpoint method="GET" path="/api/users" description="List all users" />

When to Use MDX

• API reference pages with structured method/path/description
• Tutorials with runnable code samples
• Pages that need tabs, accordions, or custom callouts

When to stick to Markdown: simple prose, changelogs, and content that doesn’t need interactivity.