Guides
View as Markdown Open in ChatGPT Open in Claude

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:

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

```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:

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

Line Highlighting

Highlight specific lines:

```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:

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

Frontmatter

Every page starts with YAML frontmatter:

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

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

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

The formula is $E = mc^2$.

Block math with double dollar signs:

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

Diagrams (Mermaid)

Create diagrams with Mermaid:

```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.

# Authentication

## API Keys
## OAuth 2.0
## JWT Tokens

Code Before Prose

Lead with working code examples, then explain:

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

Connect related concepts:

See [Authentication](/api-reference/authentication) for details on API keys.
Was this page helpful?