> ## Documentation Index
> Fetch the complete documentation index at: https://docs.holydocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MDX Basics

Learn the MDX syntax, frontmatter fields, and content authoring patterns supported by HolyDocs.

## 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 Title
description: 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
```javascript
const 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 item

1. First ordered item
2. Second ordered item
3. 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](/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.