/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
Guides Writing Content

Writing Content

Master MDX syntax and write effective documentation.

3 min read

Syntext uses MDX — Markdown with embedded React components. This guide covers the syntax and best practices for writing great documentation.

Basic Markdown

Standard Markdown syntax works as expected:

markdown
# Heading 1
## Heading 2
### Heading 3
**Bold text** and *italic text*
- Bullet point
- Another point
- Nested point
1. Numbered list
2. Second item
[Link text](https://example.com)
![Image alt text](/images/screenshot.png)
> **Note:** a labelled blockquote becomes a callout
`inline code` for commands or values

Code Blocks

Syntax Highlighting

Use fenced code blocks with a language identifier:

markdown
```typescript
const greeting = "Hello, World!";
console.log(greeting);
```

Supported languages include: javascript, typescript, python, go, rust, java, ruby, php, bash, json, yaml, sql, graphql, and 50+ more.

Code Block Titles

Add a title to provide context:

markdown
```typescript title="src/index.ts"
export function hello(name: string): string {
return `Hello, ${name}!`;
}
```

Line Highlighting

Highlight specific lines:

markdown
```typescript {2,4-5}
function process(data: Data) {
const validated = validate(data); // highlighted
const result = transform(validated); // highlighted
return result; // highlighted
}
```

Line Numbers

Show line numbers:

markdown
```typescript showLineNumbers
const a = 1;
const b = 2;
const c = a + b;
```

Frontmatter

Every page starts with YAML frontmatter:

yaml
---
title: Page Title
description: A brief description for SEO and previews
icon: rocket
---

Required Fields

FieldDescription
titlePage title, shown in navigation and browser tab

Optional Fields

FieldTypeDescription
descriptionstringMeta description for SEO
iconstringIcon shown in navigation
draftbooleanDrop the page from the sidebar and mark it noindex. The URL still serves
layoutstringPage layout: default, full-width, wide, and on doc engine v1 centered and landing. See Layout options
sidebarbooleanShow/hide sidebar (doc engine v1)
tocbooleanShow/hide table of contents

MDX Components

MDX lets you use React components in Markdown:

mdx
# Welcome
This is regular markdown.
<Note>
This is a custom component for callouts.
</Note>
Back to regular markdown.

See the Components Reference for all available components.

Tables

Standard Markdown tables:

markdown
| Name | Type | Required |
|------|------|----------|
| `id` | string | Yes |
| `email` | string | Yes |
| `name` | string | No |

Renders as:

NameTypeRequired
idstringYes
emailstringYes
namestringNo

Diagrams (Mermaid)

Create diagrams with Mermaid:

markdown
```mermaid
graph LR
A[Request] --> B{Auth?}
B -->|Yes| C[Process]
B -->|No| D[401 Error]
C --> E[Response]
```

A ```mermaid block renders as a diagram on doc engine v1 and v2 sites. On v2 it follows the site's light or dark mode, and redraws when the reader toggles it. If a diagram fails to render, its source stays visible instead.

Best Practices

Keep Pages Focused

One topic per page. If a page is getting long, split it into multiple pages.

Use Descriptive Headings

Headings should be scannable. Users often jump directly to a heading from the table of contents.

markdown
# Authentication
## API Keys
## OAuth 2.0
## JWT Tokens

Code Before Prose

Lead with working code examples, then explain:

mdx
## Create a User
\`\`\`bash
curl -X POST https://api.example.com/v1/users \
-d '{"email": "alice@example.com", "name": "Alice"}'
\`\`\`
The endpoint accepts a JSON body with...

Use Callouts Sparingly

Too many callouts create noise. Reserve them for:

•
Note / Info — Important context
•
Warning — Potential pitfalls
•
Danger — Destructive or irreversible actions
•
Tip — Helpful suggestions

See Callouts for all five.

Connect related concepts:

markdown
See [Authentication](/api-reference/authentication) for details on API keys.
Was this page helpful? Yes No
Product
Resources
Company
© 2026 SyntextBuilt with Syntext