Configuration Overview

Specra uses a single configuration file, specra.config.json, located at your project root. This file controls everything from site metadata to navigation, theming, and deployment settings.

Quick Start

Here's a minimal configuration to get started:

Code

json

1{
2  "site": {
3    "title": "My Documentation",
4    "description": "Documentation for my project",
5    "url": "https://docs.example.com"
6  }
7}

That's it! Specra fills in sensible defaults for everything else.

Configuration Structure

The config file is organized into logical sections:

Site Configuration

Basic site metadata, branding, and URLs

Navigation

Sidebar, breadcrumbs, table of contents, and tab groups

Deployment

Platform-specific deployment settings

Advanced Options

Analytics, search, features, and environment variables

Complete Example

Here's a full configuration showing all available options:

Code

json

1{
2  "$schema": "./node_modules/specra/config/specra.config.schema.json",
3  "site": {
4    "title": "My Docs",
5    "description": "Comprehensive documentation",
6    "url": "https://docs.example.com",
7    "baseUrl": "/",
8    "language": "en",
9    "organizationName": "My Company",
10    "projectName": "my-project",
11    "activeVersion": "v1.0.0",
12    "logo": "/logo.svg",
13    "favicon": "/favicon.ico",
14    "hideTitle": false,
15    "hideLogo": false
16  },
17  "theme": {
18    "defaultMode": "system",
19    "respectPrefersColorScheme": true,
20    "primaryColor": "#3b82f6",
21    "customCss": "/custom.css"
22  },
23  "navigation": {
24    "showSidebar": true,
25    "collapsibleSidebar": true,
26    "showBreadcrumbs": true,
27    "showTableOfContents": true,
28    "tocPosition": "right",
29    "tocMaxDepth": 3,
30    "tabGroups": [
31      {
32        "id": "guides",
33        "label": "Guides",
34        "icon": "book-open"
35      },
36      {
37        "id": "api",
38        "label": "API Reference",
39        "icon": "zap"
40      }
41    ]
42  },
43  "social": {
44    "github": "https://github.com/username/repo",
45    "twitter": "https://twitter.com/username",
46    "discord": "https://discord.gg/invite",
47    "linkedin": "https://linkedin.com/company/name",
48    "youtube": "https://youtube.com/@channel",
49    "custom": [
50      {
51        "label": "Website",
52        "url": "https://example.com",
53        "icon": "globe"
54      }
55    ]
56  },
57  "search": {
58    "enabled": true,
59    "placeholder": "Search documentation...",
60    "provider": "meilisearch",
61    "meilisearch": {
62      "host": "https://search.example.com",
63      "apiKey": "search-key",
64      "indexName": "docs"
65    }
66  },
67  "analytics": {
68    "googleAnalytics": "G-XXXXXXXXXX",
69    "googleTagManager": "GTM-XXXXXXX",
70    "plausible": "docs.example.com"
71  },
72  "footer": {
73    "copyright": "© 2024 My Company. All rights reserved.",
74    "customContent": "<p>Custom HTML here</p>",
75    "links": [
76      {
77        "title": "Product",
78        "items": [
79          { "label": "Features", "href": "/features" },
80          { "label": "Pricing", "href": "/pricing" }
81        ]
82      }
83    ],
84    "branding": {
85      "showBranding": true,
86      "logo": "/brand-logo.svg",
87      "title": "Powered by Specra",
88      "url": "https://specra-docs.com"
89    }
90  },
91  "banner": {
92    "enabled": true,
93    "message": "📢 Version 2.0 is coming soon!",
94    "type": "info",
95    "dismissible": true
96  },
97  "features": {
98    "editUrl": "https://github.com/username/repo/edit/main/docs",
99    "showLastUpdated": true,
100    "showReadingTime": true,
101    "showAuthors": false,
102    "showTags": true,
103    "versioning": true,
104    "i18n": false
105  },
106  "env": {
107    "API_BASE_URL": "https://api.example.com",
108    "API_VERSION": "v1",
109    "CDN_URL": "https://cdn.example.com"
110  },
111  "deployment": {
112    "target": "vercel",
113    "basePath": "",
114    "customDomain": false
115  }
116}

TypeScript Support

For TypeScript projects, you can use .ts or .mts config files:

Code

typescript

1// specra.config.ts
2import type { SpecraConfig } from 'specra'
3 
4const config: SpecraConfig = {
5  site: {
6    title: 'My Documentation',
7    description: 'Built with Specra',
8  },
9  // ... rest of config
10}
11 
12export default config

IDE Autocomplete

The config file includes a $schema property that enables autocomplete in VS Code and other editors:

Code

json

1{
2  "$schema": "./node_modules/specra/config/specra.config.schema.json",
3  "site": {
4    // Autocomplete works here!
5  }
6}

When you type, your editor will suggest available options and show descriptions.

Environment Variables

You can use environment variables in your config:

Code

json

1{
2  "search": {
3    "meilisearch": {
4      "host": "${MEILISEARCH_HOST}",
5      "apiKey": "${MEILISEARCH_API_KEY}"
6    }
7  }
8}

Then set them:

Code

bash

1# .env.local
2MEILISEARCH_HOST=https://search.example.com
3MEILISEARCH_API_KEY=your-key

Warning

Never commit sensitive API keys to version control. Use environment variables instead.

Configuration Validation

Specra validates your config on startup and shows helpful errors if something's wrong:

❌ Configuration error in specra.config.json:
   - site.url must be a valid URL
   - navigation.tocMaxDepth must be between 1 and 6

Fix the errors and restart your dev server.

Default Values

If you omit optional fields, Specra uses these defaults:

Field	Default Value
`site.baseUrl`	`"/"`
`site.language`	`"en"`
`theme.defaultMode`	`"system"`
`theme.respectPrefersColorScheme`	`true`
`navigation.showSidebar`	`true`
`navigation.collapsibleSidebar`	`true`
`navigation.showBreadcrumbs`	`true`
`navigation.showTableOfContents`	`true`
`navigation.tocPosition`	`"right"`
`navigation.tocMaxDepth`	`3`
`search.enabled`	`false`
`features.showLastUpdated`	`true`
`features.showReadingTime`	`true`
`features.versioning`	`true`
`deployment.target`	`"vercel"`

Multiple Environments

Create environment-specific configs:

Code

txt

1├── specra.config.json          # Base config
2├── specra.config.development.json
3├── specra.config.staging.json
4└── specra.config.production.json

Load the right one based on NODE_ENV:

Code

javascript

1// Load config based on environment
2const config = require(`./specra.config.${process.env.NODE_ENV}.json`)

Next Steps

Dive into specific configuration sections:

Site Configuration

Configure site metadata and branding

Navigation

Set up navigation and tab groups

Deployment

Configure deployment settings

Advanced

Analytics, search, and more