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">
2  This 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">
2  Make sure to backup your data before proceeding.
3</Callout>

Create tabbed content:

Code

mdx

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

Guide users through steps:

Code

mdx

1<Steps>
2  <Step title="Install dependencies">
3    Run `npm install` to get started.
4  </Step>
5  <Step title="Configure your app">
6    Edit 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}

Writing Style Tips

Good documentation is clear, concise, and helpful. Here are some tips:

Be Clear and Direct

Good:

Click the "Save" button to save your changes.

Bad:

You might want to consider clicking on the button labeled "Save" if you would like to persist your modifications to storage.

Use Active Voice

Good:

The system validates your input.

Bad:

Your input is validated by the system.

Show, Don't Just Tell

Include examples with every concept:

Code

mdx

1## Using Environment Variables
2 
3Access environment variables in your config:
4 
5```json
6{
7  "env": {
8    "API_URL": "https://api.example.com"
9  }
10}

Then reference them in your MDX:

Code

mdx

1The API is available at {process.env.API_URL}


### Break Up Long Content

Use headings, lists, callouts, and components to create visual breaks:

```mdx
## Configuration Options

There are several ways to configure authentication:

### API Keys

API keys are simple but less secure.

<Callout type="warning">
  Never commit API keys to version control.
</Callout>

### OAuth 2.0

OAuth provides better security for user-facing apps.

<Steps>
  <Step title="Register your app">
    Create an app in the provider dashboard.
  </Step>
  <Step title="Configure callback URL">
    Set your redirect URI in the app settings.
  </Step>
</Steps>

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() {
8  const config = loadConfig()
9  const server = createServer(config)
10  server.listen(3000)
11  console.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">
3    You'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.

SEO Best Practices

Page Titles and Descriptions

Always include both in frontmatter:

Code

mdx

1---
2title: Getting Started with Specra
3description: Learn how to install and configure Specra for your documentation needs
4---

Descriptive Headings

Use clear, descriptive headings that include keywords:

Good:

Code

markdown

1## Installing Specra with npm

Bad:

Code

markdown

1## Installation

Structured Content

Use proper heading hierarchy (h1 → h2 → h3). Never skip levels.

Common Patterns

Prerequisites Section

Start tutorials with prerequisites:

Code

mdx

1## Prerequisites
2 
3Before you begin, ensure you have:
4 
5- Node.js 18 or higher
6- A text editor
7- Basic knowledge of Markdown

Step-by-Step Tutorials

Use the Steps component:

Code

mdx

1<Steps>
2  <Step title="Install the package">
3    Run npm install specra
4  </Step>
5  <Step title="Configure">
6    Create a specra.config.json file
7  </Step>
8  <Step title="Start the server">
9    Run npm run dev
10  </Step>
11</Steps>

Code with Explanation

Pair code examples with explanations:

Code

mdx

1Configure your site title and description:
2 
3```json
4{
5  "site": {
6    "title": "My Docs",
7    "description": "Documentation for my project"
8  }
9}

The title appears in the browser tab and navigation. The description is used for SEO meta tags.


### Quick Reference Cards

Use CardGrid for scannable reference sections:

```mdx
<CardGrid cols={3}>
  <Card icon="terminal" title="CLI" description="Command line tools" href="/cli" />
  <Card icon="book" title="Guides" description="Step-by-step tutorials" href="/guides" />
  <Card icon="code" title="API" description="API reference docs" href="/api" />
</CardGrid>

Documentation

Writing Content

Writing Content in Specra

MDX Basics

Standard Markdown

Using Components

Component Examples

Content Organization

File Structure Best Practices

Controlling Page Order

Writing Style Tips

Be Clear and Direct

Use Active Voice

Show, Don't Just Tell

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

SEO Best Practices

Page Titles and Descriptions

Descriptive Headings

Structured Content

Common Patterns

Prerequisites Section

Step-by-Step Tutorials

Code with Explanation

Next Steps

Components

Configuration