Customization

Homepage Hero

The theme provides a branded Hero component for splash pages. Configure it through standard Starlight frontmatter in your index.mdx:

---
title: My Docs Site
template: splash
hero:
    tagline: A description of your project
    image:
        file: ../../assets/logo.png
    actions:
        - text: Get Started
          link: /getting-started/
          icon: right-arrow
          variant: primary
        - text: GitHub
          link: https://github.com/your-org/your-repo
          icon: github
          variant: minimal
---

Any content below the frontmatter in index.mdx renders normally after the hero.

Layout Options

The hero supports two layouts, configured through the theme key:

// Centered (default) — image above title, everything centered
defineNorthwesternConfig({
    starlight: { title: "My Docs" },
    theme: { homepage: { layout: "centered" } },
})

// Split — text and buttons on the left, image on the right (60/40)
defineNorthwesternConfig({
    starlight: { title: "My Docs" },
    theme: { homepage: { layout: "split" } },
})

When no image is provided in frontmatter, the hero renders the title, tagline, and buttons in a centered layout regardless of the layout setting.

Hiding the Title

If your hero image is a lockup that already contains the project name, hide the title to avoid redundancy:

defineNorthwesternConfig({
    starlight: { title: "My Docs" },
    theme: {
        homepage: {
            layout: "centered",
            showTitle: false,
        },
    },
})

Image Width

By default, hero images are capped at 500px wide. For wider lockup images, increase it:

defineNorthwesternConfig({
    starlight: { title: "My Docs" },
    theme: {
        homepage: {
            showTitle: false,
            imageWidth: "750px",
        },
    },
})

The value must be in pixels (e.g., "500px", "750px", "1000px").

Favicon

The theme ships Northwestern’s official favicon and applies it automatically. Remove any manual favicon entry from your Starlight config and delete the favicon from public/ if present.

To use your own favicon instead, set favicon in your Starlight config as usual:

defineNorthwesternConfig({
    starlight: {
        favicon: "/my-custom-favicon.png",
        title: "My Docs",
    },
})

Dark/Light Image Variants

Use separate images for each theme:

hero:
    image:
        dark: ../../assets/logo-dark.png
        light: ../../assets/logo-light.png
        alt: Project logo

Custom Hero Override

If you need a completely custom hero, override it in your Starlight config. The theme will not replace it:

defineNorthwesternConfig({
    starlight: {
        components: {
            Hero: "./src/components/MyHero.astro",
        },
        title: "My Docs",
    },
})

Component Overrides

The theme overrides three Starlight components by default:

#Hero Centered layout + wide image Branded splash page

#EditLink ConditionalEditLink Hides edit link on homepage

#ThemeSelect ThemeToggle Animated sun/moon toggle

All three respect existing overrides. If you set Hero, EditLink, or ThemeSelect in your Starlight components config, the theme keeps your version.

Mermaid Diagrams

Mermaid support is opt-in. When installed, the theme applies Northwestern colors to all diagram types and adds a fullscreen viewer with pan/zoom, SVG download, source copying, and touch support.

To customize the Mermaid integration (toolbar, theme overrides):

defineNorthwesternConfig({
    starlight: { title: "My Docs" },
    mermaid: {
        toolbar: false,
        mermaidConfig: {
            themeVariables: { fontSize: "16px" },
        },
    },
})

Open Graph Images

Each page gets a 1200x630 PNG at build time: favicon logo, page title, and description on Northwestern purple with a light purple accent border. Set site in your config for absolute URLs. See Getting Started for setup.

To disable OG images:

defineNorthwesternConfig({
    starlight: { title: "My Docs" },
    theme: { ogImage: false },
})

Expressive Code

With defineNorthwesternConfig, the theme configures GitHub syntax highlighting (github-dark / github-light) and the line-numbers plugin.

Use showLineNumbers on individual code blocks:

```ts showLineNumbers title="example.ts"
const x = 1;
```

Overriding Themes

Pass expressiveCode in your starlight config to replace the defaults. Properties you set override the theme’s; pluginLineNumbers and defaultProps are preserved.

defineNorthwesternConfig({
    starlight: {
        title: "My Docs",
        expressiveCode: {
            themes: ["dracula", "github-light"],
        },
    },
})

Manual Setup

If you use northwesternTheme() directly instead of defineNorthwesternConfig, line numbers require an ec.config.mjs at your project root:

import { defineEcConfig } from "@astrojs/starlight/expressive-code";
import { northwesternExpressiveCode } from "@nu-appdev/northwestern-starlight-theme/expressive-code";

export default defineEcConfig(northwesternExpressiveCode());

Integration Escape Hatch

If you need to add integrations before or after the managed ones, use the integrations key:

import sentry from "@sentry/astro";

defineNorthwesternConfig({
    starlight: { title: "My Docs" },
    integrations: {
        before: [],           // before mermaid + starlight
        after: [sentry()],    // after starlight
    },
})

Custom CSS

The theme loads its CSS before your project’s customCss, so you can override any token or style in your own CSS files.

defineNorthwesternConfig({
    starlight: {
        title: "My Docs",
        customCss: ["./src/styles/overrides.css"],
    },
})

Available CSS Variables

The theme defines Northwestern design tokens as CSS custom properties. You can reference or override these in your own styles:

Purple Scale

#--nu-purple-100 #4e2a84 Brand primary

#--nu-purple-120 #401f68 Navigation background

#--nu-purple-40 #a495c3 Dark mode accent

See src/styles/variables.css in the theme package for the full token list.

Typography

#--nu-font-body Akkurat Pro, system fallbacks

#--nu-font-heading Poppins, Akkurat Pro, system fallbacks

Semantic Colors

#--nu-color-success #008656 Success states

#--nu-color-info #5091cd Info states

#--nu-color-warning #ffc520 Warning states

#--nu-color-danger #ef553f Danger states