S
Specra Docs
Specra Docs Comprehensive documentation for your project

Documentation

Advanced Configuration

Configure analytics, search, features, footer, banner, and environment variables

Advanced Configuration

Beyond the basics, Specra offers powerful features like analytics, search, custom footers, banners, and environment variables. This guide covers all the advanced configuration options.

Analytics

Track how users interact with your documentation.

Google Analytics

Code
json 
1{
2  "analytics": {
3    "googleAnalytics": "G-XXXXXXXXXX"
4  }
5}

Get your measurement ID from Google Analytics.

Google Tag Manager

Code
json 
1{
2  "analytics": {
3    "googleTagManager": "GTM-XXXXXXX"
4  }
5}

More flexible than Google Analytics, allows custom tracking without code changes.

Plausible Analytics

Privacy-friendly alternative to Google Analytics:

Code
json 
1{
2  "analytics": {
3    "plausible": "docs.example.com"
4  }
5}

Sign up at plausible.io.

Multiple Analytics

Use several providers simultaneously:

Code
json 
1{
2  "analytics": {
3    "googleAnalytics": "G-XXXXXXXXXX",
4    "plausible": "docs.example.com"
5  }
6}

Search Configuration

Enable powerful search for your documentation.

Basic Search Setup

Code
json 
1{
2  "search": {
3    "enabled": true,
4    "placeholder": "Search documentation...",
5    "provider": "meilisearch"
6  }
7}

MeiliSearch

Full-featured search with typo tolerance:

Code
json 
1{
2  "search": {
3    "enabled": true,
4    "provider": "meilisearch",
5    "meilisearch": {
6      "host": "https://search.example.com",
7      "apiKey": "your-search-key",
8      "indexName": "docs"
9    }
10  }
11}

See Search Setup for complete MeiliSearch configuration.

Simple search without external dependencies:

Code
json 
1{
2  "search": {
3    "enabled": true,
4    "provider": "local",
5    "placeholder": "Search..."
6  }
7}

Pros:

  • No setup required
  • Works offline
  • Free

Cons:

  • Less powerful than MeiliSearch
  • No typo tolerance
  • Slower for large sites

Customize your documentation footer.

Code
json 
1{
2  "footer": {
3    "copyright": "© 2024 My Company. All rights reserved."
4  }
5}
Code
json 
1{
2  "footer": {
3    "copyright": "© 2024 Acme Corp. All rights reserved.",
4    "customContent": "<p>Need help? <a href='/support'>Contact support</a></p>",
5    "links": [
6      {
7        "title": "Product",
8        "items": [
9          { "label": "Features", "href": "/features" },
10          { "label": "Pricing", "href": "/pricing" },
11          { "label": "Changelog", "href": "/changelog" }
12        ]
13      },
14      {
15        "title": "Resources",
16        "items": [
17          { "label": "Documentation", "href": "/docs" },
18          { "label": "API Reference", "href": "/api" },
19          { "label": "Examples", "href": "/examples" }
20        ]
21      },
22      {
23        "title": "Company",
24        "items": [
25          { "label": "About", "href": "/about" },
26          { "label": "Blog", "href": "/blog" },
27          { "label": "Careers", "href": "/careers" }
28        ]
29      }
30    ],
31    "branding": {
32      "showBranding": true,
33      "logo": "/brand-logo.svg",
34      "title": "Powered by Specra",
35      "url": "https://specra-docs.com"
36    }
37  }
38}

copyright

  • Copyright notice displayed at bottom
  • Supports HTML

customContent

  • Custom HTML inserted in footer
  • Use for extra messaging or links

links

  • Organized link columns
  • Each column has a title and items
  • Items have label and href

branding

  • Show "Powered by" branding
  • Customize logo, title, and URL
  • Set showBranding: false to hide

Display important messages at the top of your site.

Basic Banner

Code
json 
1{
2  "banner": {
3    "enabled": true,
4    "message": "📢 Version 2.0 is now available!",
5    "type": "info"
6  }
7}
Code
json 
1{
2  "banner": {
3    "enabled": true,
4    "message": "⚠️ Scheduled maintenance on Sunday at 2 AM UTC",
5    "type": "warning",
6    "dismissible": true
7  }
8}

Properties:

PropertyTypeDescription
enabledbooleanShow or hide banner
messagestringBanner text (supports emojis and HTML)
typestringStyle: info, warning, success, error
dismissiblebooleanAllow users to dismiss banner

Info (blue):

Code
json 
1{
2  "banner": {
3    "message": "📢 New feature: Dark mode is here!",
4    "type": "info"
5  }
6}

Warning (yellow):

Code
json 
1{
2  "banner": {
3    "message": "⚠️ API v1 will be deprecated on Jan 1, 2025",
4    "type": "warning"
5  }
6}

Success (green):

Code
json 
1{
2  "banner": {
3    "message": "✅ All systems operational",
4    "type": "success"
5  }
6}

Error (red):

Code
json 
1{
2  "banner": {
3    "message": "🚨 Critical security update available",
4    "type": "error"
5  }
6}

Features Configuration

Enable or disable various documentation features.

Code
json 
1{
2  "features": {
3    "editUrl": "https://github.com/username/repo/edit/main/docs",
4    "showLastUpdated": true,
5    "showReadingTime": true,
6    "showAuthors": false,
7    "showTags": true,
8    "versioning": true,
9    "i18n": false
10  }
11}

Feature Options

editUrl

  • Link to edit page source
  • Appears at bottom of each page
  • Use GitHub, GitLab, or any Git hosting URL
  • Set to false to disable

showLastUpdated

  • Display when page was last modified
  • Uses git commit timestamps
  • Appears at bottom of page

showReadingTime

  • Estimate reading time (words per minute)
  • Shows "5 min read" at top of page

showAuthors

  • Display page authors
  • Requires author info in frontmatter

showTags

  • Show tags on pages
  • Requires tags in frontmatter

versioning

  • Enable documentation versioning
  • Support multiple doc versions (v1.0.0, v2.0.0)

i18n

  • Enable internationalization
  • Support multiple languages

Add social media links to your header.

Code
json 
1{
2  "social": {
3    "github": "https://github.com/username/repo",
4    "twitter": "https://twitter.com/username",
5    "discord": "https://discord.gg/invite",
6    "linkedin": "https://linkedin.com/company/name",
7    "youtube": "https://youtube.com/@channel"
8  }
9}

Add links to platforms not built-in:

Code
json 
1{
2  "social": {
3    "github": "https://github.com/username",
4    "custom": [
5      {
6        "label": "Slack",
7        "url": "https://slack.com/invite",
8        "icon": "slack"
9      },
10      {
11        "label": "Website",
12        "url": "https://example.com",
13        "icon": "globe"
14      }
15    ]
16  }
17}

Environment Variables

Use environment variables in your config and MDX content.

In Configuration

Code
json 
1{
2  "env": {
3    "API_BASE_URL": "https://api.example.com",
4    "API_VERSION": "v1",
5    "CDN_URL": "https://cdn.example.com",
6    "SUPPORT_EMAIL": "support@example.com"
7  }
8}

Access in MDX:

Code
mdx 
1API endpoint: {process.env.API_BASE_URL}
2Current version: {process.env.API_VERSION}

From .env Files

Set values via environment files:

Code
bash 
1# .env.local
2API_BASE_URL=https://api.example.com
3MEILISEARCH_HOST=https://search.example.com
4MEILISEARCH_API_KEY=your-key

Reference in config:

Code
json 
1{
2  "env": {
3    "API_BASE_URL": "${API_BASE_URL}"
4  },
5  "search": {
6    "meilisearch": {
7      "host": "${MEILISEARCH_HOST}",
8      "apiKey": "${MEILISEARCH_API_KEY}"
9    }
10  }
11}
Warning
Never commit sensitive keys to version control. Use environment variables and add `.env.local` to `.gitignore`.

Public vs Private Variables

Private (server-only):

MEILISEARCH_API_KEY=secret-key
DATABASE_URL=postgres://...

Public (exposed to browser):

NEXT_PUBLIC_GA_ID=G-XXXXXXXXXX
NEXT_PUBLIC_API_URL=https://api.example.com

Prefix with NEXT_PUBLIC_ to make variables available in the browser.

Theme Configuration

Customize visual appearance.

Code
json 
1{
2  "theme": {
3    "defaultMode": "system",
4    "respectPrefersColorScheme": true,
5    "primaryColor": "#3b82f6",
6    "customCss": "/custom.css"
7  }
8}

defaultMode

  • "system" - Match OS preference
  • "light" - Always light mode
  • "dark" - Always dark mode

respectPrefersColorScheme

  • Honor OS color scheme preference
  • Set to false to ignore OS settings

primaryColor

  • Main brand color (hex code)
  • Used for links, buttons, accents

customCss

  • Path to custom CSS file
  • Add in public/ folder

See Customization for detailed theming guide.

Complete Example

Here's a fully configured Specra setup:

Code
json 
1{
2  "site": {
3    "title": "Acme Documentation",
4    "description": "Complete docs for Acme Platform",
5    "url": "https://docs.acme.com"
6  },
7  "theme": {
8    "defaultMode": "system",
9    "primaryColor": "#6366f1"
10  },
11  "navigation": {
12    "showSidebar": true,
13    "showTableOfContents": true,
14    "tocPosition": "right",
15    "tabGroups": [
16      { "id": "guides", "label": "Guides", "icon": "book-open" },
17      { "id": "api", "label": "API", "icon": "zap" }
18    ]
19  },
20  "search": {
21    "enabled": true,
22    "provider": "meilisearch",
23    "meilisearch": {
24      "host": "${MEILISEARCH_HOST}",
25      "apiKey": "${MEILISEARCH_API_KEY}",
26      "indexName": "docs"
27    }
28  },
29  "analytics": {
30    "googleAnalytics": "G-XXXXXXXXXX",
31    "plausible": "docs.acme.com"
32  },
33  "social": {
34    "github": "https://github.com/acme/platform",
35    "twitter": "https://twitter.com/acme",
36    "discord": "https://discord.gg/acme"
37  },
38  "footer": {
39    "copyright": "© 2024 Acme Corp. All rights reserved.",
40    "links": [
41      {
42        "title": "Product",
43        "items": [
44          { "label": "Features", "href": "/features" },
45          { "label": "Pricing", "href": "/pricing" }
46        ]
47      }
48    ]
49  },
50  "banner": {
51    "enabled": true,
52    "message": "📢 Version 2.0 is now available!",
53    "type": "info",
54    "dismissible": true
55  },
56  "features": {
57    "editUrl": "https://github.com/acme/platform/edit/main/docs",
58    "showLastUpdated": true,
59    "showReadingTime": true,
60    "showTags": true,
61    "versioning": true
62  },
63  "deployment": {
64    "target": "vercel"
65  }
66}

Next Steps

Search Setup

Configure MeiliSearch for your docs

Customization

Theme and style your documentation

Deployment

Deploy to production

Configuration Overview

Back to configuration overview

Edit this page Report an issue
Previous
Deployment Configuration
Next
Deployment Overview