Writing Content in Specra

Specra uses MDX (Markdown + JSX) for documentation, giving you the simplicity of Markdown with the power of React components. This guide covers everything you need to write great documentation.

MDX Basics

MDX files look like regular Markdown but let you use React components anywhere in your content.

Standard Markdown

All standard Markdown syntax works as expected:

Headings:

Code

markdown

1# Heading 1
2## Heading 2
3### Heading 3

Text formatting:

Code

markdown

1**Bold text**
2*Italic text*
3~~Strikethrough~~
4`Inline code`

Lists:

Code

markdown

1- Unordered list
2- Another item
3  - Nested item
4 
51. Ordered list
62. Second item
7   1. Nested ordered item

Links and images:

Code

markdown

1[Link text](https://example.com)
2![Alt text](/images/photo.png)

Code blocks:

Code

markdown

1```javascript
2function hello() {
3  console.log("Hello, world!")
4}
5```

Tables:

Code

markdown

1| Column 1 | Column 2 | Column 3 |
2|----------|----------|----------|
3| Data 1   | Data 2   | Data 3   |
4| More     | Info     | Here     |

Blockquotes:

Code

markdown

1> This is a quote.
2> It can span multiple lines.

Horizontal rules:

Code

markdown

1---

Using Components

Components are used with JSX syntax directly in your MDX:

Code

mdx

1<Callout type="info">
2This is a callout component!
3</Callout>

All components are automatically available - no imports needed.

Component Examples

Alert readers to important information:

Code

mdx

1<Callout type="warning">
2Make sure to backup your data before proceeding.
3</Callout>

Create tabbed content:

Code

mdx

1<Tabs defaultValue="option1">
2<Tab label="Option 1">
3Content for the first tab
4</Tab>
5<Tab label="Option 2">
6Content for the second tab
7</Tab>
8</Tabs>

Guide users through steps:

Code

mdx

1<Steps>
2<Step title="Install dependencies">
3Run `npm install` to get started.
4</Step>
5<Step title="Configure your app">
6Edit the config file with your settings.
7</Step>
8</Steps>

See the Components section for all available components.

Content Organization

File Structure Best Practices

Organize files logically to make content easy to find:

Code

txt

1docs/v1.0.0/
2├── getting-started.mdx         # Top level: essential pages
3├── installation.mdx
4├── guides/                     # Group related content
5│   ├── _category_.json
6│   ├── basics.mdx
7│   ├── advanced.mdx
8│   └── examples/              # Further nesting for sub-topics
9│       ├── _category_.json
10│       ├── example-1.mdx
11│       └── example-2.mdx
12└── api/
13    ├── _category_.json
14    └── reference.mdx

Tips:

Keep the top level for critical pages users need first
Use folders to group related content
Limit nesting to 2-3 levels max
Name files descriptively (authentication.mdx not auth.mdx)

Controlling Page Order

Use sidebar_position in frontmatter to control ordering:

Code

mdx

1---
2title: Installation
3sidebar_position: 1
4---

Lower numbers appear first. Pages without a position are sorted alphabetically.

For folders, use _category_.json:

Code

json

1{
2  "label": "Getting Started",
3  "position": 1
4}

Working with Images

Adding Images

Place images in the public/ folder:

Code

txt

1public/
2├── images/
3│   ├── screenshot.png
4│   └── diagram.svg

Reference them in MDX:

Code

mdx

1![Dashboard screenshot](/images/screenshot.png)

Image Best Practices

Use descriptive alt text:

Code

mdx

1![Login form showing email and password fields](/images/login.png)

Optimize image sizes:

Use WebP format when possible
Compress images before adding to repo
Keep images under 500KB

Use the Image component for advanced features:

Code

mdx

1<Image
2  src="/images/hero.png"
3  alt="Hero image"
4  caption="The main dashboard view"
5  width={800}
6  height={400}
7/>

Code Examples

Syntax Highlighting

Specify the language after the opening backticks:

Code

markdown

1```javascript
2const greeting = "Hello, world!"
3console.log(greeting)
4```
5 
6```python
7def greet():
8    print("Hello, world!")
9```
10 
11```bash
12npm install specra
13```

Supported languages include: javascript, typescript, python, bash, json, yaml, markdown, html, css, and many more.

Highlighting Lines

Highlight specific lines to draw attention:

Code

markdown

1```javascript {2,4-6}
2function calculateTotal(items) {
3  const subtotal = items.reduce((sum, item) => sum + item.price, 0)
4  const tax = subtotal * 0.1
5  const shipping = 5.99
6  const total = subtotal + tax + shipping
7  return total
8}
9```

File Names

Show which file the code belongs to:

Code

markdown

1```javascript title="src/utils.js"
2export function formatDate(date) {
3  return date.toLocaleDateString()
4}
5```

Use the CodeBlock Component

For more control:

Code

mdx

1<CodeBlock
2  language="javascript"
3  title="src/app.js"
4  highlightLines={[3, 5]}
5  showLineNumbers={true}
6>
7{`function app() {
8const config = loadConfig()
9const server = createServer(config)
10server.listen(3000)
11console.log("Server running")
12}`}
13</CodeBlock>

Internal Links

Link to other pages in your docs:

Code

mdx

1See the [Configuration guide](/docs/v1.0.0/configuration/overview) for details.

Use relative paths from the site root, including the version.

External Links

External links open in a new tab automatically:

Code

mdx

1Check out the [SvelteKit documentation](https://svelte.dev/docs/kit).

Anchor Links

Link to headings on the same page:

Code

mdx

1Jump to [Installation](#installation) below.

Heading anchors are auto-generated from the heading text in lowercase with hyphens.

Frontmatter Reference

Every MDX file needs frontmatter. Here's a complete example:

Code

mdx

1---
2title: Advanced Topics
3description: Deep dive into advanced Specra features
4sidebar_position: 10
5tab_group: guides
6icon: zap
7tags: [advanced, configuration, optimization]
8draft: false
9---
10 
11# Your content starts here

Required fields:

title: Page title

Recommended fields:

description: SEO description (150-160 characters)

Optional fields:

sidebar_position: Number for sidebar ordering
tab_group: Assign to a tab group
icon: Lucide icon name
tags: Array of tags
draft: Hide in production if true

Advanced MDX Features

Importing Components

While built-in components work automatically, you can import custom ones:

Code

mdx

1import { MyCustomComponent } from '@/components/custom'
2 
3<MyCustomComponent data="example" />

Using JavaScript Expressions

Embed JavaScript expressions:

Code

mdx

1The current year is {new Date().getFullYear()}.

Conditional Content

Use JavaScript for conditional rendering:

Code

mdx

1{process.env.NODE_ENV === 'development' && (
2  <Callout type="info">
3You're viewing the development version.
4  </Callout>
5)}

Version Management

When you need multiple doc versions:

Code

txt

1docs/
2├── v1.0.0/
3│   └── getting-started.mdx
4├── v2.0.0/
5│   └── getting-started.mdx
6└── next/
7    └── getting-started.mdx

Set the active version in specra.config.json:

Code

json

1{
2  "site": {
3    "activeVersion": "v2.0.0"
4  }
5}

Users can switch versions with the version dropdown in the UI.

Next Steps

Components

Explore all available MDX components

Configuration

Customize your documentation site

Documentation

Writing Content

Writing Content in Specra

MDX Basics

Standard Markdown

Using Components

Component Examples

Content Organization

File Structure Best Practices

Controlling Page Order

Working with Images

Adding Images

Image Best Practices

Code Examples

Syntax Highlighting

Highlighting Lines

File Names

Use the CodeBlock Component

Links and Navigation

Internal Links

External Links

Anchor Links

Frontmatter Reference

Advanced MDX Features

Importing Components

Using JavaScript Expressions

Conditional Content

Version Management

Next Steps

Components

Configuration