Writing Content
Master MDX syntax and write effective documentation.
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:
Code Blocks
Syntax Highlighting
Use fenced code blocks with a language identifier:
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:
Line Highlighting
Highlight specific lines:
Line Numbers
Show line numbers:
Frontmatter
Every page starts with YAML frontmatter:
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 | Drop the page from the sidebar and mark it noindex. The URL still serves |
layout | string | Page layout: default, full-width, wide, and on doc engine v1 centered and landing. See Layout options |
sidebar | boolean | Show/hide sidebar (doc engine v1) |
toc | boolean | Show/hide table of contents |
MDX Components
MDX lets you use React components in Markdown:
See the Components Reference for all available components.
Tables
Standard Markdown tables:
Renders as:
| Name | Type | Required |
|---|---|---|
id | string | Yes |
email | string | Yes |
name | string | No |
Diagrams (Mermaid)
Create diagrams with Mermaid:
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.
Code Before Prose
Lead with working code examples, then explain:
Use Callouts Sparingly
Too many callouts create noise. Reserve them for:
See Callouts for all five.
Link Liberally
Connect related concepts: