@bogoware/starlight-theme

Bogoware brand identity theme for Astro Starlight documentation sites.

Features

• Dual typography system: Architect mode (Space Grotesk + DM Sans) for technical docs, Florentine mode (Cormorant Garamond + Crimson Pro) for blogs — both coexist on the same site
• Route-based style switching: Assign typography modes to URL patterns (e.g., blog/** → Florentine)
• Per-page and inline overrides: Override via frontmatter or the <Style> component within MDX content
• Complete brand identity: Bogoliubov Vertex logo, color palette, spacing system
• SEO optimized: Font preconnect, favicon, Open Graph meta support
• Google Analytics: Optional GA4 with DNT respect and cookieless mode
• Sitemap: Automatic sitemap generation via @astrojs/sitemap
• Self-hosted fonts: WOFF2 font files for offline/air-gapped builds

Live Demo

Explore the theme in action at Pasta Protocol — a fictional Neapolitan-flavored distributed systems framework that showcases every feature of the Bogoware Starlight theme, including both typography modes, all custom components, and the complete Starlight component catalog.

Installation

pnpm add @bogoware/starlight-theme

Usage

// astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import bogowareTheme from '@bogoware/starlight-theme';

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Project',
      plugins: [
        bogowareTheme({
          mode: 'architect',           // default typography for the site
          styleRoutes: [
            { pattern: 'blog/**', style: 'florentine' },
          ],
          logoVariant: 'simplified',   // 'full' | 'simplified' | 'monochrome'
          fieldLines: true,
          analytics: {
            googleAnalyticsId: 'G-XXXXXXXXXX', // optional
          },
        }),
      ],
    }),
  ],
});

Typography Modes

Mode	Display	Body	Code	Best For
Architect	Space Grotesk	DM Sans	Space Mono	Technical docs, APIs
Florentine	Cormorant Garamond	Crimson Pro	Fira Code	Blogs, essays

Both modes are always available. The mode option sets the site-wide default; styleRoutes assigns modes to URL patterns.

Dual Style Support

Style Resolution Order

The theme resolves the typography style for each page in this order (highest priority first):

1. Frontmatter themeStyle field on the page
2. Route patterns matching styleRoutes configuration
3. Global default mode setting

Route-Based Styles

Use styleRoutes to assign a typography mode to URL patterns:

bogowareTheme({
  mode: 'architect',
  styleRoutes: [
    { pattern: 'blog/**', style: 'florentine' },     // all blog pages
    { pattern: 'philosophy/*', style: 'florentine' }, // direct children only
  ],
})

Supported patterns:

• blog/** — matches recursively (e.g., blog/foo, blog/foo/bar)
• blog/* — matches single level only (e.g., blog/foo but not blog/foo/bar)
• blog/my-post — exact match

Per-Page Style Override

Override the style for a specific page using frontmatter:

---
title: My Literary Post
themeStyle: 'florentine'
---

This page uses Florentine typography regardless of route patterns.

To enable the themeStyle frontmatter field, extend Starlight's content schema:

// src/content.config.ts
import { defineCollection } from 'astro:content';
import { docsSchema } from '@astrojs/starlight/schema';
import { themeStyleSchema } from '@bogoware/starlight-theme/schema';

export const collections = {
  docs: defineCollection({ schema: docsSchema({ extend: themeStyleSchema }) }),
};

Inline Style Switching

Switch typography within a page using the <Style> component in MDX:

import Style from '@bogoware/starlight-theme/components/Style.astro';

This paragraph uses the page's default style.

<Style mode="florentine">

This section uses Florentine typography — classical serif fonts
for a literary feel within a technical page.

</Style>

Back to the page's default style.

License

MIT