Getting Started

Installation

pnpm

pnpm add @nu-appdev/northwestern-starlight-theme

npm

npm i @nu-appdev/northwestern-starlight-theme

yarn

yarn add @nu-appdev/northwestern-starlight-theme

bun

bun add @nu-appdev/northwestern-starlight-theme

Configuration

Add the plugin to your Starlight config:

astro.config.ts

import northwesternTheme from "@nu-appdev/northwestern-starlight-theme";

export default defineConfig({
    integrations: [
        starlight({
            plugins: [northwesternTheme()],
            title: "My Docs",
        }),
    ],
});

Colors, typography, navigation, and component styling apply automatically. See the Style Guide for a preview of every styled element.

Mermaid Diagrams (Optional)

Install astro-mermaid and mermaid, then add the Northwestern mermaid integration before starlight():

pnpm

pnpm add astro-mermaid mermaid

npm

npm i astro-mermaid mermaid

yarn

yarn add astro-mermaid mermaid

bun

bun add astro-mermaid mermaid

astro.config.ts

import { northwesternMermaid } from "@nu-appdev/northwestern-starlight-theme/mermaid";
import northwesternTheme from "@nu-appdev/northwestern-starlight-theme";

export default defineConfig({
    integrations: [
        northwesternMermaid(),
        starlight({
            plugins: [northwesternTheme()],
        }),
    ],
});

The theme does not bundle either package. Without them installed, mermaid code blocks render as plain text.

Expressive Code Line Numbers (Optional)

The theme configures GitHub syntax highlighting by default. For opt-in line numbers, add an ec.config.mjs at your docs project root:

ec.config.mjs

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

export default defineEcConfig(northwesternExpressiveCode());

Authors can then use showLineNumbers on individual code blocks.

Migrating an Existing Site

If your project already has manual Northwestern branding, remove the overrides that the theme now replaces.

Astro Config

Replace any hand-written mermaid config:

astro.config.ts

import mermaid from "astro-mermaid";
import { northwesternMermaid } from "@nu-appdev/northwestern-starlight-theme/mermaid";

export default defineConfig({
    integrations: [
        mermaid(),
        northwesternMermaid(),
        starlight({

Remove component overrides the theme now provides:

astro.config.ts

components: {
    EditLink: "./src/components/ConditionalEditLink.astro",
    Hero: "./src/components/Hero.astro",
},

Remove redundant font imports, favicon, and theme CSS:

astro.config.ts

favicon: "/favicon.ico",
customCss: [
    "./src/styles/custom.css",
    "./src/styles/layout.css",
    "@fontsource/poppins/400.css",
    "@fontsource/poppins/600.css",
],

The theme ships Northwestern’s official favicon by default. To use your own instead, set favicon in your Starlight config as usual.

Files to Delete

Remove these if they exist only for Northwestern branding:

• public/favicon.ico (or public/favicon.svg) — the theme provides this automatically
• src/components/ConditionalEditLink.astro
• src/components/Hero.astro
• src/styles/custom.css
• src/styles/layout.css

Dependencies

You no longer need @fontsource/poppins. Keep astro-mermaid and mermaid if your site uses diagrams.