---
title: Writing Content
description: Master MDX syntax and write effective documentation.
icon: pencil
---

# Writing Content

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)

> Blockquote for callouts

`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](https://shiki.style/languages).

### 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

| Field | Description |
|-------|-------------|
| `title` | Page title, shown in navigation and browser tab |

### Optional Fields

| Field | Type | Description |
|-------|------|-------------|
| `description` | string | Meta description for SEO |
| `icon` | string | Icon shown in navigation |
| `draft` | boolean | Hide from production (visible in dev) |
| `layout` | string | Page layout: `default`, `centered`, `full-width` |
| `sidebar` | boolean | Show/hide sidebar |
| `toc` | boolean | Show/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](/components/overview) for all available components.

## Tables

Standard Markdown tables:

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

Renders as:

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

## Math (LaTeX)

Inline math with single dollar signs:

```markdown
The formula is $E = mc^2$.
```

Block math with double dollar signs:

```markdown
$$
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$
```

## 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]
```
````

## 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

\`\`\`typescript
const user = await client.users.create({
  email: "alice@example.com",
  name: "Alice"
});
\`\`\`

The `create` method accepts a `CreateUserInput` object with...
```

### Use Callouts Sparingly

Too many callouts create noise. Reserve them for:

- **Note** — Important context
- **Warning** — Potential pitfalls
- **Tip** — Helpful suggestions

### Link Liberally

Connect related concepts:

```markdown
See [Authentication](/api-reference/authentication) for details on API keys.
```