create-specra

create-specra is the official CLI tool for scaffolding new Specra documentation sites. It sets up everything you need in seconds: project structure, dependencies, configuration, and sample content.

Quick Start

The fastest way to create a new documentation site:

This creates a new directory called my-docs with everything configured and ready to go.

What Gets Created

When you run create-specra, here's what you get:

1my-docs/
2├── src/
3│   ├── app.css                    # Global styles (imports specra/styles)
4│   ├── app.html                   # HTML template
5│   └── routes/
6│       ├── +layout.server.ts      # Load Specra config
7│       ├── +layout.svelte         # Root layout with Specra components
8│       ├── +page.server.ts        # Landing page redirect
9│       └── docs/
10│           └── [version]/
11│               └── [...slug]/
12│                   ├── +page.server.ts   # Load doc data
13│                   └── +page.svelte      # Doc page renderer
14├── docs/
15│   ├── v1.0.0/                    # Version 1 docs (MDX files)
16│   └── v2.0.0/                    # Version 2 docs (MDX files)
17├── public/
18│   └── api-specs/                 # API spec files (OpenAPI, Postman)
19├── specra.config.json             # Specra configuration
20├── package.json                   # Dependencies and scripts
21├── svelte.config.js               # SvelteKit configuration
22├── vite.config.ts                 # Vite configuration
23├── postcss.config.mjs             # PostCSS (for Tailwind)
24├── tsconfig.json                  # TypeScript config
25└── .gitignore

Templates

create-specra offers three templates to choose from:

Minimal (Default)

Clean starting point with basic structure:

• System theme (follows OS preference)
• Card-style sidebar with rounded container
• Table of contents enabled
• Simple docs: about page, getting started guide, component examples

1npx create-specra my-docs --template minimal

Book Docs

Knowledge base style inspired by platforms like GitBook:

• Dark theme by default
• Flush sidebar (attached to screen edge)
• Categorized sidebar with section headers (Content, Customization)
• Site-wide banner
• Version badge in sidebar
• Rich sample content with cards on landing page

1npx create-specra my-docs --template book-docs

JBrains Docs

Reference documentation style with tabbed navigation:

• Light theme by default
• Flush sidebar (attached to screen edge)
• Tab groups for organizing content (Language, Multiplatform)
• Collapsible tree-style sidebar
• No table of contents (right panel)
• Version badge in sidebar

1npx create-specra my-docs --template jbrains-docs

Interactive Setup

When you run create-specra without options, it will prompt you for:

Project name (if not provided as argument)

1npx create-specra@latest
2# Prompts: What is your project named?

Template (if not provided via --template)

1# Will ask: Which template do you want to use?
2# Options: Minimal, Book Docs, JBrains Docs

Package manager preference (if multiple are detected)

1# Will ask: Which package manager do you want to use?
2# Options: npm, yarn, pnpm

The CLI detects what's available on your system and suggests the best option.

Command Options

Basic Usage

1npx create-specra@latest [project-name] [options]

Examples

Create with a specific name:

1npx create-specra@latest my-awesome-docs

Create in current directory:

1npx create-specra@latest .

Use a specific template:

1npx create-specra@latest my-docs --template minimal
2npx create-specra@latest my-docs --template book-docs
3npx create-specra@latest my-docs --template jbrains-docs

Use a specific package manager:

1npx create-specra@latest my-docs --use-npm
2npx create-specra@latest my-docs --use-yarn
3npx create-specra@latest my-docs --use-pnpm

Skip package installation:

1npx create-specra@latest my-docs --skip-install

What Happens Next

After scaffolding completes, follow these steps:

1cd my-docs

Open [http://localhost:5173](http://localhost:5173) to see your site.

Default Configuration

The generated specra.config.json includes sensible defaults:

1{
2  "site": {
3    "title": "My Documentation",
4    "description": "Documentation site built with Specra",
5    "url": "http://localhost:5173",
6    "baseUrl": "/",
7    "activeVersion": "v1.0.0"
8  },
9  "theme": {
10    "defaultMode": "system",
11    "respectPrefersColorScheme": true
12  },
13  "navigation": {
14    "showSidebar": true,
15    "collapsibleSidebar": true,
16    "showBreadcrumbs": true,
17    "showTableOfContents": true,
18    "tocPosition": "right"
19  },
20  "features": {
21    "showLastUpdated": true,
22    "showReadingTime": true,
23    "versioning": true
24  }
25}

You can customize any of these settings. See Configuration for all available options.

Sample Content

Each template includes sample documentation to help you get started. The content varies by template:

Minimal — About page, getting started guide, and component examples Book Docs — Introduction with card grid, quickstart, concepts, and categorized sections (Content, Customization) JBrains Docs — Home page with cards, getting started, and tabbed sections (Basics, Advanced, Tools)

All templates include two doc versions (v1.0.0 and v2.0.0) to demonstrate the versioning system. Feel free to delete or modify any sample pages.

Available Scripts

The generated package.json includes these scripts:

Updating Specra

To update to the latest version of Specra in your project:

Troubleshooting

Command not found

If you get "command not found" errors:

Check Node.js version:

1node --version
2# Should be 18.0.0 or higher

Try with full npx path:

1npx create-specra@latest my-docs

Permission errors

On Linux/macOS, you might need to adjust npm permissions:

1sudo chown -R $USER ~/.npm

Or use a node version manager like nvm.

Installation fails

If dependency installation fails:

1. Delete node_modules and lock file
2. Clear package manager cache
3. Try again

1rm -rf node_modules package-lock.json
2npm cache clean --force
3npm install

Next Steps

Now that you have a Specra site set up: