Features Overview

The Astro Starlight Docs Optimizer package provides a comprehensive suite of features to make your documentation production-ready. This page provides an overview of all features and links to detailed documentation for each.

Core Features

Analytics & Tracking

Complete Google Analytics 4 implementation with privacy-first design:

Google Analytics 4 Integration
- Modern GA4 gtag.js implementation
- Event tracking and custom events
- E-commerce tracking support
- User ID tracking (opt-in)
- Debug mode for development
Consent Mode v2
- Full Google Consent Mode v2 implementation
- Granular consent types (analytics, ads, personalization)
- Regional defaults (EU vs non-EU)
- Consent state persistence
- Update mechanism after user choice
Privacy Protection
- IP anonymization for EU users
- Respects Do Not Track (DNT) header
- No tracking on localhost/development
- Cookie-less tracking option
- Data retention controls

Learn more about Analytics →

Automatic compliance with EU data protection regulations:

Regional Detection
- Automatic EU/EEA detection
- Special territories (Switzerland, Norway, Iceland, Liechtenstein)
- UK support (post-Brexit GDPR)
- VPN and proxy handling
- Fallback mechanisms
Cookie Consent Management
- GDPR-compliant consent banner
- Both “Accept” and “Decline” options
- Granular cookie categories
- Consent withdrawal mechanism
- Preference persistence
Legal Compliance
- GDPR Article 7 (consent conditions)
- GDPR Article 13 (transparency)
- ePrivacy Directive 2002/58/EC
- Cookie Law compliance
- Data processor agreements

Learn more about GDPR Compliance →

SEO Optimization

Advanced search engine optimization beyond Starlight’s basics:

Meta Tags
- Open Graph protocol for social sharing
- Twitter Cards integration
- Canonical URLs
- Author and publisher information
- Keywords optimization
Structured Data
- Schema.org TechArticle markup
- Breadcrumb navigation schema
- Organization schema
- WebSite schema
- SearchAction schema
Social Sharing
- Custom OG images per page
- Twitter card customization
- Facebook sharing optimization
- LinkedIn preview cards
- WhatsApp sharing support

Learn more about SEO Features →

LLM Optimization

Make your documentation discoverable by AI assistants:

llms.txt Generation
- Automatic llms.txt file generation
- Standard format compliance
- Content hierarchy markers
- Sitemap integration
- Update notifications
AI-Friendly Metadata
- Structured content markers
- Clear section boundaries
- Code block labeling
- Example identification
- API reference formatting
Crawling Optimization
- AI crawler directives
- Content prioritization
- Token efficiency
- Context preservation
- Citation support

Learn more about LLM Optimization →

Implementation Features

Script Injection Architecture

Clean, maintainable integration without component overrides:

No Component Overrides
- Uses Astro’s injectScript() API
- Preserves Starlight’s default components
- No breaking changes with updates
- Clean separation of concerns
- Future-proof architecture
Injection Points
- head-inline: Critical scripts (consent mode defaults)
- page: User-facing scripts (analytics, consent UI)
- page-ssr: Server-side rendering scripts
- Strategic placement for optimal performance
Performance Optimization
- Minimal bundle size impact
- Async script loading
- Deferred execution where appropriate
- No render-blocking scripts
- Critical CSS inlined

Learn more about Technical Implementation →

Regional Intelligence

Smart regional detection and adaptation:

EU Detection

// Automatic detection of EU countries
const EU_COUNTRIES = [
  'AT', 'BE', 'BG', 'HR', 'CY', 'CZ', 'DK', 'EE', 'FI', 'FR',
  'DE', 'GR', 'HU', 'IE', 'IT', 'LV', 'LT', 'LU', 'MT', 'NL',
  'PL', 'PT', 'RO', 'SK', 'SI', 'ES', 'SE',
  // Special territories
  'CH', 'NO', 'IS', 'LI', 'GB'
];

Fallback Strategy
- Timezone-based detection (fallback #1)
- Language preference detection (fallback #2)
- Conservative default (assume EU if uncertain)
- Manual override option
Consent Defaults
- EU users: All consent denied by default
- Non-EU users: Analytics granted by default
- Respects user’s explicit choice
- Persists preference across sessions

Learn more about Enhancements →

No Layout Breaking

Guaranteed compatibility with Starlight updates:

Component Preservation
- Never overrides Starlight components
- Injects scripts without touching markup
- Maintains responsive design
- Preserves accessibility features
- Keeps dark mode functionality
Update Safety
- Works with all Starlight versions
- Forward-compatible architecture
- Backward-compatible defaults
- Automated compatibility testing
- Zero-maintenance updates
Layout Integrity
- No CSS conflicts
- No z-index issues
- No position conflicts
- Mobile responsiveness maintained
- Print styles preserved

Learn more about No Overrides Approach →

Configuration Features

Easy Configuration

Simple, type-safe configuration API:

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import { starlightOptimizer } from 'astro-starlight-optimizer';

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Documentation',
    }),
    starlightOptimizer({
      // Analytics
      googleAnalyticsId: 'G-XXXXXXXXXX',

      // GDPR
      gdprCompliance: true,
      consentBanner: {
        message: 'Custom message',
        acceptText: 'Accept',
        declineText: 'Decline',
      },

      // SEO
      seo: {
        ogImage: '/og-image.png',
        twitterHandle: '@yourhandle',
      },

      // LLM
      llmOptimization: true,
      llmConfig: {
        title: 'My Docs',
        description: 'API documentation',
      },
    }),
  ],
});

TypeScript Support

Full TypeScript type definitions:

interface StarlightOptimizerOptions {
  // Analytics
  googleAnalyticsId?: string;
  googleAdsId?: string;
  measurementId?: string;

  // GDPR
  gdprCompliance?: boolean;
  consentBanner?: {
    message?: string;
    acceptText?: string;
    declineText?: string;
    cookiePolicy?: string;
  };

  // SEO
  seo?: {
    ogImage?: string;
    ogType?: string;
    twitterHandle?: string;
    twitterCard?: 'summary' | 'summary_large_image';
  };

  // LLM
  llmOptimization?: boolean;
  llmConfig?: {
    title?: string;
    description?: string;
    keywords?: string[];
  };

  // Advanced
  debug?: boolean;
  respectDnt?: boolean;
  anonymizeIp?: boolean;
}

Learn more about Configuration →

Feature Matrix

Comparison Table

Feature	Vanilla Starlight	With Optimizer
Performance	100/100	100/100 ✅
Accessibility	100/100	100/100 ✅
SEO (Basic)	✅	✅
SEO (Advanced)	❌	✅
Analytics	❌	✅ GA4
GDPR Compliance	❌	✅ Automatic
Cookie Consent	❌	✅ Built-in
Regional Detection	❌	✅ EU/Non-EU
LLM Optimization	❌	✅ llms.txt
Consent Mode v2	❌	✅ Full support
Open Graph	❌	✅
Twitter Cards	❌	✅
Structured Data	❌	✅ Schema.org
No Breaking Changes	N/A	✅ Guaranteed

Bundle Size Impact

Starlight Base:
  HTML: 14 KB
  CSS: 8 KB
  JS: 4 KB
  Total: 26 KB

With Optimizer:
  HTML: 14 KB (no change)
  CSS: 9 KB (+1 KB for consent banner)
  JS: 8 KB (+4 KB for analytics + consent)
  Total: 31 KB (+19% total, still excellent)

Context:
  - Typical docs site: 200-400 KB
  - Optimizer adds: 5 KB
  - Impact: Negligible (still 6-13x smaller than average)

Performance Metrics

Metric	Without Optimizer	With Optimizer	Impact
First Contentful Paint	0.6s	0.6s	✅ No change
Largest Contentful Paint	0.8s	0.8s	✅ No change
Time to Interactive	0.9s	1.0s	+0.1s (imperceptible)
Cumulative Layout Shift	0.02	0.02	✅ No change
Total Blocking Time	0ms	12ms	+12ms (still excellent)
Lighthouse Performance	100	100	✅ Maintained

Feature Roadmap

Current Version (v1.0)

✅ Google Analytics 4 integration
✅ Consent Mode v2 support
✅ GDPR compliance automation
✅ Regional detection (EU/non-EU)
✅ Cookie consent UI
✅ Open Graph meta tags
✅ Twitter Cards
✅ Schema.org structured data
✅ llms.txt generation
✅ LLM-friendly metadata
✅ Script injection architecture
✅ TypeScript support

Planned Features (v1.1)

🔄 Additional analytics providers (Plausible, Fathom)
🔄 Custom event tracking helpers
🔄 A/B testing support
🔄 User feedback widgets
🔄 Performance monitoring
🔄 Error tracking integration

Future Considerations (v2.0)

💡 Automatic OG image generation
💡 RSS feed generation
💡 Changelog automation
💡 Version dropdown
💡 Search analytics
💡 Content recommendations

:::note Feature Requests Have a feature idea? Open an issue on GitHub or start a discussion. :::

Integration Compatibility

Astro Versions

Astro Version	Compatibility	Notes
4.0.x	✅ Fully compatible	Recommended
3.6.x	✅ Fully compatible	Legacy support
3.5.x	⚠️ Limited	Missing some APIs
< 3.5	❌ Not supported	Too old

Starlight Versions

Starlight Version	Compatibility	Notes
0.21.x	✅ Fully compatible	Recommended
0.20.x	✅ Fully compatible	Stable
0.19.x	⚠️ Limited	Some features missing
< 0.19	❌ Not supported	Breaking changes

Other Integrations

Compatible with popular Astro integrations:

Integration	Status	Notes
@astrojs/mdx	✅ Compatible	No conflicts
@astrojs/sitemap	✅ Compatible	Recommended
@astrojs/tailwind	✅ Compatible	Consent banner uses Tailwind
@astrojs/image	✅ Compatible	OG image optimization
astro-compress	✅ Compatible	Works with compression
astro-icon	✅ Compatible	No conflicts

Platform Support

Hosting Platforms

Tested and verified on:

Platform	Status	Notes
Cloudflare Pages	✅ Verified	Recommended
Netlify	✅ Verified	Works perfectly
Vercel	✅ Verified	No issues
GitHub Pages	✅ Verified	Static generation
AWS S3 + CloudFront	✅ Verified	CDN recommended
Render	✅ Verified	Works well
Railway	✅ Verified	No issues

Browser Support

Browser	Version	Support
Chrome	90+	✅ Full
Firefox	88+	✅ Full
Safari	14+	✅ Full
Edge	90+	✅ Full
Opera	76+	✅ Full
Samsung Internet	14+	✅ Full

Legacy Browser Support:

IE 11: ❌ Not supported (Astro requirement)
Safari 13: ⚠️ Limited (missing some APIs)

Security Features

Content Security Policy

CSP-safe script injection:

<!-- All scripts support CSP nonces -->
<script nonce="{{CSP_NONCE}}">
  // Analytics initialization
  // Consent management
  // Event tracking
</script>

Privacy Features

✅ IP anonymization for EU users
✅ Cookie-less tracking option
✅ Respects Do Not Track header
✅ No third-party tracking pixels
✅ LocalStorage for preferences only
✅ No fingerprinting techniques
✅ HTTPS-only cookies
✅ SameSite cookie attribute

Supply Chain Security

✅ NPM provenance attestation
✅ Signed releases (GitHub)
✅ Automated vulnerability scanning
✅ Dependency audits
✅ SBOM (Software Bill of Materials)
✅ Reproducible builds