Site Configuration

The site section in specra.config.json controls your documentation site's identity, branding, and basic metadata. This is where you define your site's title, description, logo, and other fundamental properties.

Basic Configuration

Here's a minimal site configuration:

Code

json

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

That's all you need to get started. Specra fills in sensible defaults for everything else.

All Site Options

Required Fields

Only one field is truly required:

Code

json

1{
2  "site": {
3    "title": "My Documentation"
4  }
5}

Everything else is optional but recommended for a professional docs site.

Complete Configuration

Here's every available option:

Code

json

1{
2  "site": {
3    "title": "Specra Documentation",
4    "description": "Build beautiful documentation with Specra",
5    "url": "https://docs.example.com",
6    "baseUrl": "/",
7    "language": "en",
8    "organizationName": "My Company",
9    "projectName": "specra",
10    "activeVersion": "v1.0.0",
11    "logo": "/logo.svg",
12    "favicon": "/favicon.ico",
13    "hideTitle": false,
14    "hideLogo": false
15  }
16}

Configuration Reference

title

Type: string (Required)

The name of your documentation site. Appears in the browser tab, navigation header, and social media previews.

Code

json

1{
2  "site": {
3    "title": "Specra Docs"
4  }
5}

Tip

Keep it short and clear. This appears in many places, including browser tabs where space is limited.

description

Type: string

Brief description of your documentation. Used in SEO meta tags and social media previews.

Code

json

1{
2  "site": {
3    "description": "Complete guide to building documentation with Specra"
4  }
5}

Best practices:

Keep it under 160 characters
Include relevant keywords
Be descriptive and specific
Focus on what users will learn

url

Type: string

The full URL where your documentation is hosted. Used for generating canonical URLs and social media previews.

Code

json

1{
2  "site": {
3    "url": "https://docs.example.com"
4  }
5}

Warning

Include the protocol (`https://`) but no trailing slash.

baseUrl

Type: string Default: "/"

Base path for your site. Usually only needed for GitHub Pages without a custom domain.

Code

json

1{
2  "site": {
3    "baseUrl": "/"
4  }
5}

For GitHub Pages at username.github.io/repo-name:

Code

json

1{
2  "site": {
3    "baseUrl": "/repo-name/"
4  }
5}

Info

For most deployments (Vercel, Netlify, custom domains), keep this as `"/"`.

language

Type: string Default: "en"

The primary language of your documentation. Used in the HTML lang attribute.

Code

json

1{
2  "site": {
3    "language": "en"
4  }
5}

Common values: en, es, fr, de, ja, zh, pt, ru

organizationName

Type: string

Your company or organization name. Used in footer and metadata.

Code

json

1{
2  "site": {
3    "organizationName": "Acme Corporation"
4  }
5}

projectName

Type: string

The name of your project or product. Used in metadata and can be referenced in content.

Code

json

1{
2  "site": {
3    "projectName": "specra"
4  }
5}

activeVersion

Type: string Default: First version found in docs/ folder

Which documentation version to show by default.

Code

json

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

Users can switch versions using the version dropdown, but this sets the default.

logo

Type: string or object

Path to your logo image. Can be a single logo or separate logos for light and dark modes.

Single logo:

Code

json

1{
2  "site": {
3    "logo": "/logo.svg"
4  }
5}

Separate logos for themes:

Code

json

1{
2  "site": {
3    "logo": {
4      "light": "/logo-light.svg",
5      "dark": "/logo-dark.svg"
6    }
7  }
8}

Best practices:

Use SVG for crisp rendering at any size
Keep dimensions around 150px wide × 40px tall
Optimize files (use SVGO or similar)
Place in public/ folder

favicon

Type: string

Path to your favicon. Appears in browser tabs and bookmarks.

Code

json

1{
2  "site": {
3    "favicon": "/favicon.ico"
4  }
5}

Recommended setup:

public/
├── favicon.ico          # 32×32 ICO for older browsers
├── favicon-16x16.png    # 16×16 PNG
├── favicon-32x32.png    # 32×32 PNG
└── apple-touch-icon.png # 180×180 PNG for iOS

Then reference the main one:

Code

json

1{
2  "site": {
3    "favicon": "/favicon-32x32.png"
4  }
5}

hideTitle

Type: boolean Default: false

Hide the site title in the header navigation.

Code

json

1{
2  "site": {
3    "hideTitle": true
4  }
5}

Useful when your logo includes text and you don't want the title duplicated.

hideLogo

Type: boolean Default: false

Hide the logo in the header navigation.

Code

json

1{
2  "site": {
3    "hideLogo": true
4  }
5}

Use this if you only want to show the text title without a logo.

Examples

Minimal Setup

Perfect for getting started:

Code

json

1{
2  "site": {
3    "title": "My Docs",
4    "description": "Documentation for my project"
5  }
6}

Open Source Project

For an open source project on GitHub:

Code

json

1{
2  "site": {
3    "title": "MyLib Documentation",
4    "description": "A powerful library for building awesome things",
5    "url": "https://mylib.dev",
6    "organizationName": "MyLib Contributors",
7    "projectName": "mylib",
8    "logo": "/logo.svg",
9    "favicon": "/favicon.ico"
10  }
11}

Company Product

For a commercial product:

Code

json

1{
2  "site": {
3    "title": "Acme API Docs",
4    "description": "Complete API reference and guides for Acme Platform",
5    "url": "https://docs.acme.com",
6    "organizationName": "Acme Corporation",
7    "projectName": "acme-platform",
8    "activeVersion": "v2.0.0",
9    "logo": {
10      "light": "/acme-logo-light.svg",
11      "dark": "/acme-logo-dark.svg"
12    },
13    "favicon": "/favicon-32x32.png"
14  }
15}

Multi-Language Site

For documentation in multiple languages:

Code

json

1{
2  "site": {
3    "title": "Documentation",
4    "language": "es",
5    "url": "https://docs.example.com/es",
6    "logo": "/logo.svg"
7  }
8}

Common Patterns

GitHub Pages Setup

For GitHub Pages without custom domain:

Code

json

1{
2  "site": {
3    "title": "My Docs",
4    "url": "https://username.github.io/repo-name",
5    "baseUrl": "/repo-name/"
6  }
7}

Logo Best Practices

For light mode background: Use a dark logo or logo with color

For dark mode background: Use a light/white logo or invert colors

Example setup:

Code

json

1{
2  "site": {
3    "logo": {
4      "light": "/logo-dark.svg",
5      "dark": "/logo-white.svg"
6    }
7  }
8}

Validation

Specra validates your site configuration on startup. Common errors:

Missing title:

❌ Error: site.title is required

Invalid URL:

❌ Error: site.url must be a valid URL (include https://)

Logo file not found:

⚠️ Warning: Logo file not found at /logo.svg

Environment Variables

Use environment variables for different environments:

Code

json

1{
2  "site": {
3    "url": "${SITE_URL}",
4    "logo": "${LOGO_PATH}"
5  }
6}

Then set them:

Code

bash

1# .env.local
2SITE_URL=https://docs.example.com
3LOGO_PATH=/logo.svg

Next Steps

Navigation

Configure sidebar, breadcrumbs, and tab groups

Deployment

Set up deployment configuration

Advanced

Analytics, search, and more

Overview

Back to configuration overview