MDX Basics

What is MDX?

MDX is Markdown with JSX support. It lets you write standard Markdown content while embedding interactive components directly in your documentation. HolyDocs uses a unified remark/rehype pipeline to process MDX files into optimized HTML at build time.

Frontmatter

Every MDX page starts with YAML frontmatter between --- delimiters:

mdx
---title: Page Titledescription: A short description for SEO and search results.icon: book---Your page content starts here.

Supported Frontmatter Fields

Field	Type	Description
title	string	Page title displayed in the heading and browser tab
description	string	Description for SEO meta tags and search results
icon	string	Icon name displayed next to the title in navigation
sidebarTitle	string	Override the title shown in the sidebar
mode	string	Set to "wide" for full-width layout
api	string	API method and path (e.g., "GET /users") for API pages
openapi	string	OpenAPI operation reference (e.g., "GET /pets/{id}")

Markdown Syntax

HolyDocs supports the full GitHub Flavored Markdown (GFM) specification, including:

Headings

markdown
## Second Level Heading### Third Level Heading#### Fourth Level Heading

Headings automatically generate anchor IDs for linking. A table of contents is generated from ## and ### headings on the right sidebar.

Code Blocks

Fenced code blocks with syntax highlighting:

markdown
```javascriptconst holydocs = require('@holydocs/cli');holydocs.deploy({ projectId: 'my-project' });```

Supported languages include JavaScript, TypeScript, Python, Go, Rust, Java, Ruby, PHP, C#, Shell, JSON, YAML, and many more.

Code Block Titles

Add a filename or title to code blocks:

markdown
```typescript docs.json{  "name": "My Docs",  "theme": "holy"}```

Tables

markdown
| Column A | Column B | Column C ||----------|----------|----------|| Cell 1   | Cell 2   | Cell 3   |

Links and Images

markdown
[Link text](https://example.com)[Internal link](/quickstart)![Alt text](/images/screenshot.png)

Internal links use paths relative to the docs root. Image paths starting with / are resolved from your docs directory and served via the /_assets/ endpoint.

Lists

markdown
- Unordered item- Another item  - Nested item1. First ordered item2. Second ordered item3. Third ordered item

Blockquotes

markdown
> This is a blockquote. It can span multiple lines> and supports **formatting** inside.

Using Components

HolyDocs provides built-in JSX components that you can use directly in MDX:

mdx
<Callout type="warning">  This is an important warning message.</Callout><CardGroup cols={2}>  <Card title="First Card" icon="star">    Card content here.  </Card>  <Card title="Second Card" icon="rocket">    Another card.  </Card></CardGroup>

See the Components page for the full list of available components.

Math and LaTeX

Enable LaTeX rendering in your docs.json:

json
{  "styling": {    "latex": true  }}

Then use inline math with $...$ and display math with $$...$$:

markdown
The equation $E = mc^2$ is inline.$$\int_0^{\infty} e^{-x^2} dx = \frac{\sqrt{\pi}}{2}$$

File Organization

MDX files are organized relative to your docs root. The file path determines the URL slug:

File Path	URL
introduction.mdx	/introduction
guides/setup.mdx	/guides/setup
api/users.mdx	/api/users

Only pages listed in the navigation section of docs.json are accessible. Files not referenced in navigation will return a 404.