Getting Started with Specra

This guide will get you from zero to a fully functional documentation site in under 5 minutes. We'll cover installation, basic configuration, and writing your first page.

Prerequisites

Before you begin, make sure you have:

Node.js 18 or higher (check with node --version)
A package manager: npm (comes with Node.js), yarn, or pnpm
A code editor (VS Code recommended for MDX support)

Installation

The fastest way to get started is using create-specra, our scaffolding tool that sets up everything for you.

Create Your Project

Run the create command with your project name:

<Tabs defaultValue="npm">
  <Tab label="npm">

Code

bash

1npx create-specra@latest my-docs

  </Tab>
  <Tab label="yarn">

Code

bash

1yarn create specra my-docs

  </Tab>
  <Tab label="pnpm">

Code

bash

1pnpm create specra my-docs

  </Tab>
</Tabs>

This creates a new directory called `my-docs` with all the files you need to get started.

Navigate and Install

Move into your new project and install dependencies:

<Tabs defaultValue="npm">
  <Tab label="npm">

Code

bash

1cd my-docs
2npm install

  </Tab>
  <Tab label="yarn">

Code

bash

1cd my-docs
2yarn install

  </Tab>
  <Tab label="pnpm">

Code

bash

1cd my-docs
2pnpm install

  </Tab>
</Tabs>

Installation typically takes 30-60 seconds depending on your internet connection.

Start the Dev Server

Fire up the development server:

<Tabs defaultValue="npm">
  <Tab label="npm">

Code

bash

1npm run dev

  </Tab>
  <Tab label="yarn">

Code

bash

1yarn dev

  </Tab>
  <Tab label="pnpm">

Code

bash

1pnpm dev

  </Tab>
</Tabs>

Open [http://localhost:3000](http://localhost:3000) in your browser. You should see your documentation site with sample content!

<Callout type="success">
The dev server includes hot reload. Edit any MDX file and watch your changes appear instantly.
</Callout>

Project Structure

After running create-specra, here's what you get:

Code

txt

1my-docs/
2├── src/routes/              # SvelteKit routes
3│   ├── layout.tsx           # Root layout with Specra providers
4│   ├── page.tsx             # Home page
5│   └── docs/                # Documentation routes
6│       └── [...slug]/       # Dynamic catch-all route
7│           └── page.tsx     # Doc page renderer
8├── docs/                    # Your documentation content
9│   └── v1.0.0/             # Version folder
10│       ├── about.mdx
11│       ├── getting-started.mdx
12│       └── guides/         # Folder grouping
13│           ├── _category_.json
14│           └── writing.mdx
15├── public/                  # Static assets (images, icons)
16├── specra.config.json      # Specra configuration
17├── package.json
18├── svelte.config.js         # SvelteKit config (auto-managed)
19└── tailwind.config.ts      # Tailwind configuration

Info

Important: All documentation files must use the .mdx extension, not .md. MDX lets you use React components alongside Markdown.

Your First Documentation Page

Let's create your first custom documentation page.

Create a New File

Inside `docs/v1.0.0/`, create a file called `hello.mdx`:

Code

mdx

1---
2title: Hello Specra
3description: My first documentation page
4sidebar_position: 3
5---
6 
7# Hello Specra!
8 
9This is my first documentation page. I can use **bold text**,
10*italic text*, and even [links](https://specra-docs.com).
11 
12## Features I Love
13 
14- Fast hot reload
15- Beautiful components
16- Simple file structure
17- Zero configuration needed

View Your Page

Save the file and visit http://localhost:3000/docs/v1.0.0/hello

You should see your new page in the sidebar and rendered beautifully in the main content area.

Add a Component

Let's make it more interesting with a Callout component:

Code

mdx

1---
2title: Hello Specra
3description: My first documentation page
4sidebar_position: 3
5---
6 
7# Hello Specra!
8 
9This is my first documentation page.
10 
11<Callout type="success">
12  I just added an interactive component to my Markdown! No imports needed.
13</Callout>
14 
15## Next Steps
16 
17Ready to learn more? Check out the [Components](/docs/v1.0.0/components) section.

Save and watch it update instantly. Notice how you didn't need to import the Callout component - it's automatically available in all your MDX files.

Understanding Frontmatter

Frontmatter is the metadata at the top of each MDX file, wrapped in triple dashes (---). It controls how your page appears and behaves.

Available Fields

Field	Type	Required	Description
`title`	string	✅ Yes	Page title shown in sidebar, browser tab, and breadcrumbs
`description`	string	Recommended	Brief description for SEO and social media previews
`sidebar_position`	number	No	Controls sidebar order (lower numbers appear first)
`tab_group`	string	No	Assigns page to a tab group (like "guides", "api", "components")
`icon`	string	No	Lucide icon name to display next to title in sidebar
`tags`	array	No	Tags for categorization and filtering
`draft`	boolean	No	Set to `true` to hide page in production builds
`last_updated`	string	No	Override auto-detected last updated date

Example Frontmatter

Code

mdx

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

Tip

Pages without `sidebar_position` are sorted alphabetically. Use this field to create a specific reading order.

Organizing with Folders

Group related pages into folders for better organization. Specra automatically generates navigation from your folder structure.

Basic Folder Structure

Code

txt

1docs/v1.0.0/
2├── getting-started.mdx
3├── guides/
4│   ├── installation.mdx
5│   ├── configuration.mdx
6│   └── deployment.mdx
7└── api/
8    ├── overview.mdx
9    └── endpoints.mdx

Each folder becomes a collapsible section in the sidebar.

Category Configuration

Create a _category_.json file inside any folder to customize how it appears:

Code

json

1{
2  "label": "User Guides",
3  "position": 2,
4  "collapsible": true,
5  "collapsed": false,
6  "tab_group": "guides",
7  "icon": "book-open"
8}

Options:

label: Display name in sidebar (defaults to folder name)
position: Order among other folders/pages
collapsible: Whether users can collapse the section
collapsed: Initial collapsed state
tab_group: Assign entire folder to a tab group
icon: Lucide icon name

Index Pages

Create an index.mdx file in a folder to provide a landing page when users click the folder name:

Code

txt

1guides/
2├── _category_.json
3├── index.mdx          ← Landing page for /docs/v1.0.0/guides
4├── installation.mdx
5└── deployment.mdx

Using Components

Specra comes with a rich library of components that are automatically available in all MDX files. No imports needed.

Quick Examples

Callouts for important information:

Code

mdx

1<Callout type="info">
2  This is helpful information for your readers.
3</Callout>
4 
5<Callout type="warning">
6  Be careful with this setting!
7</Callout>

Tabs for multiple options:

Code

mdx

1<Tabs defaultValue="npm">
2  <Tab label="npm">
3    npm install specra
4  </Tab>
5  <Tab label="yarn">
6    yarn add specra
7  </Tab>
8</Tabs>

Steps for tutorials:

Code

mdx

1<Steps>
2  <Step title="First Step">
3    Do this first.
4  </Step>
5  <Step title="Second Step">
6    Then do this.
7  </Step>
8</Steps>

Cards for visual navigation:

Code

mdx

1<CardGrid cols={2}>
2  <Card
3    icon="zap"
4    title="Quick Start"
5    description="Get up and running fast"
6    href="/docs/v1.0.0/getting-started"
7  />
8  <Card
9    icon="book"
10    title="Full Guide"
11    description="Complete documentation"
12    href="/docs/v1.0.0/guides"
13  />
14</CardGrid>

Explore all available components in the Components section.

Markdown Support

Specra supports all standard Markdown syntax plus GitHub Flavored Markdown extensions.

Headings: # for H1, ## for H2, etc. Bold: **text** or __text__ Italic: *text* or _text_ Links: [text](url) Images: ![alt](url) Code: `inline code` Code blocks: Triple backticks with language

Tables:

Code

markdown

1| Column 1 | Column 2 |
2|----------|----------|
3| Data 1   | Data 2   |

Task lists:

Code

markdown

1- [x] Completed task
2- [ ] Pending task

Blockquotes:

Code

markdown

1> This is a quote

What's Next?

You now have a working Specra site and know the basics of creating pages. Here's where to go from here:

Configure Your Site

Customize branding, navigation, and features

Explore Components

Learn about all available UI components

Deploy Your Docs

Ship your documentation to production

Advanced Features

Versioning, search, API docs, and more