Starlight Plugins

A comprehensive guide to extending Starlight with official plugins, community plugins, and third-party tools.

Official Plugins

Algolia DocSearch — Replace the default Pagefind search with Algolia DocSearch.

Community Plugins

Content Generation & Import

starlight-typedoc — Generate documentation pages directly from TypeScript using TypeDoc
starlight-openapi — Auto-generate docs pages from OpenAPI/Swagger specifications
starlight-obsidian — Publish your Obsidian vault as a Starlight site
starlight-changelogs — Display project changelogs inline with docs

Content Enhancement & Authoring

starlight-blog — Add a blog section alongside your docs
starlight-markdown-blocks — Extend Markdown with additional block/asides types
starlight-heading-badges — Attach badges to Markdown/MDX headings
starlight-kbd — Render keyboard shortcut references cleanly
starlight-videos — Integrate video tutorials or courses into docs
starlight-github-alerts — Render GitHub repository alerts as doc asides

starlight-sidebar-topics — Organize docs into separate topic-based sidebars
starlight-sidebar-topics-dropdown — Add a dropdown switcher for sidebar topics
starlight-auto-sidebar — Adjust auto-generated sidebar groupings
starlight-view-modes — Provide multiple view modes (e.g., compact/full) for readers
starlight-fullview-mode — Collapse sidebars for a fullscreen doc view
starlight-view-transitions — Enable browser-native view transitions
starlight-contextual-menu — Add contextual menus to docs
star-warp — Accelerate navigation through search results

Interactive Features

starlight-image-zoom — Add zoom functionality to images
starlight-codeblock-fullscreen — Enable fullscreen toggling for code blocks
starlight-scroll-to-top — Add a floating “scroll to top” button
starlight-site-graph — Display an interactive site graph in the sidebar
starlight-giscus — Embed Giscus comments for docs discussions

Site Management & Quality

starlight-links-validator — Check for broken links across all docs pages
starlight-versions — Manage versioned documentation
starlight-auto-drafts — Auto-remove draft pages from production sidebars
starlight-contributor-list — Show contributors to your project
starlight-toc-overview-customizer — Customize the table of contents overview title
starlight-llms-txt — Add an llms.txt policy file to your site

Styling & Credits

starlight-utils — A bundle of common utilities for Starlight
starlight-cooler-credit — Add a styled credit footer for Starlight/Astro

Community Tools and Integrations

Development & Authoring Tools

@hideoo/starlight-plugin — CLI scaffolder to bootstrap new plugins
starlight-i18n — VSCode extension to assist in translating docs
notion-to-astro — Convert Notion exports into Starlight content

Interactive Components & Features

astro-live-code — Render MDX code blocks as interactive, runnable snippets
starlight-package-managers — Show install commands for npm, pnpm, yarn, etc
starlight-showcases — Components to build showcase/gallery pages
FeelBack — Collect quick user feedback on doc pages

Diagram & Export Tools

astro-plantuml — Render PlantUML diagrams inside Markdown
astro-mermaid — Render Mermaid diagrams client-side in Markdown
astro-d2 — Transform d2 code blocks into diagrams
starlight-to-pdf — Export an entire Starlight site as a PDF

Plugin Deep Dives

starlight-obsidian

Publish an Obsidian vault into Starlight

What it does (in practice)

Publishes your Obsidian vault to a Starlight site: converts notes to MDX under src/content/docs/<o>, copies images to src/assets/<o>, and ships other assets (audio/video/PDF) to public/<o>. It preserves Obsidian semantics (wikilinks, embeds, callouts, tags/aliases, math) with a clear support matrix. Starlight Obsidian Docs Configuration Features Project Structure.

Key options you’ll actually touch

vault (required): path to the vault. Configuration.
output: folder name under src/content/docs/ (defaults notes). Project Structure Configuration.
ignore: glob patterns to exclude files/folders; also respects the Obsidian publish: false property. Ignoring Content.
copyFrontmatter: 'none' | 'starlight' | 'all' to lift frontmatter from notes into Starlight pages. Configuration.
math: singleDollarTextMath to avoid $ collisions in prose. Configuration.
skipGeneration: skip vault processing on hosts without vault access; prebuild & commit MDX. Deployment.
sidebar: inject generated group (with obsidianSidebarGroup) and control collapse behavior. Configuration.

Install & minimal config

Starlight Obsidian Docs.

import {defineConfig} from 'astro/config'
import starlight from '@astrojs/starlight'
import starlightObsidian, { obsidianSidebarGroup } from 'starlight-obsidian'

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      plugins: [
        starlightObsidian({ vault: '../path/to/vault' }),
      ],
      sidebar: [
        { label: 'Guides', items: ['guides/example'] },
        obsidianSidebarGroup, // adds generated vault tree
      ],
    }),
  ],
})

Ignore & publish controls (two levers)

Use either the Obsidian publish: false property or ignore: [] globs in the plugin config (great for private folders like private/**). Ignoring Content.

// Exclude sensitive notes and temp content
starlightObsidian({
  vault: '../vault',
  ignore: ['private/**/*', '**/*secret*'],
})

Multiple vaults

Spin up multiple instances via createStarlightObsidianPlugin() and add each sidebar group. Multiple Instances.

import { createStarlightObsidianPlugin } from 'starlight-obsidian'

const [astroObsidian, astroGroup] = createStarlightObsidianPlugin()
const [bioObsidian, bioGroup] = createStarlightObsidianPlugin()

starlight({
  plugins: [
    astroObsidian({ vault: '../astro', output: 'notes-astro', sidebar: {label:'Astro'} }),
    bioObsidian({ vault: '../bio',   output: 'notes-bio',   sidebar: {label:'Biology'} }),
  ],
  sidebar: [astroGroup, bioGroup],
})

Mermaid & rendering note

If your vault contains Mermaid diagrams, the docs recommend installing Playwright with Chromium so diagrams render correctly during processing. Getting Started Features.

# One-time on your build host
npx playwright install --with-deps chromium

Gotchas

If deploying where the vault isn’t present (e.g., remote CI with secrets), set skipGeneration and commit generated MDX. Deployment.
$ in prose? Set math.singleDollarTextMath: false. Configuration.
Verify output before publishing (sanity check for private notes). Getting Started.

starlight-markdown-blocks

Define custom :::blocks beyond native callouts

Why it exists

Starlight ships :::note|tip|caution|danger asides; this plugin lets you author new block types with the same ::: syntax, plus a built-in “Draft” block that vanishes in production. Starlight Markdown Blocks (Getting Started) Starlight asides baseline.

Install & wire-up

Add the plugin and declare named blocks under blocks: { … }. Getting Started.

import {defineConfig} from 'astro/config'
import starlight from '@astrojs/starlight'
import starlightMarkdownBlocks, { Aside, Draft } from 'starlight-markdown-blocks'

export default defineConfig({
  integrations: [starlight({
    title: 'Docs',
    plugins: [starlightMarkdownBlocks({
      blocks: {
        idea: Aside({ label: 'Idea', color: 'green' }), // custom aside variant
        draft: Draft(),                                 // hidden on prod builds
      },
    })],
  })],
})

Authoring

Use :::idea[Optional label] / :::draft in Markdown; Aside supports label, color, icon (emoji/SVG), and wrapper element. Aside Draft.

:::idea[Hot take]
Ship fewer features; polish more.
:::

:::draft
This section is WIP and won't appear in production.
:::

Styling hooks

Each custom aside gets a .starlight-custom-aside--BLOCK class for targeted CSS. Aside.

When to reach for it

You need domain-specific callouts (e.g., “Pitfall”, “Legal”, “Breaking Change”) without writing raw HTML. Getting Started.
You want a safe “in-doc TODO” that hides on deploy (Draft). Draft.

astro-mermaid

Client-side Mermaid integration for Astro/Starlight

What it provides

A lightweight Astro integration that transforms ```mermaid code blocks and renders them client-side with automatic theme switching; supports custom Mermaid config and optional Iconify icon packs. Place it before Starlight in your integrations array. astro-mermaid (npm).

Install & minimal usage

astro-mermaid (npm)

npm i astro-mermaid mermaid

import { defineConfig } from 'astro/config'
import mermaid from 'astro-mermaid'
import starlight from '@astrojs/starlight'

export default defineConfig({
  integrations: [
    mermaid({ autoTheme: true }), // must come BEFORE starlight
    starlight({ title: 'My Docs' }),
  ],
})

Authoring

Use standard Mermaid code fences in Markdown/MDX; rendering is local (privacy-friendly, offline-capable, zero network round-trips). astro-mermaid (npm)

Theme & icons

Configure theme, enable autoTheme, and optionally register Iconify icon packs for diagram nodes. astro-mermaid (npm).

mermaid({
  theme: 'forest',
  autoTheme: true,
  mermaidConfig: { flowchart: { curve: 'basis' } },
  iconPacks: [{ name: 'logos', loader: () => fetch('https://unpkg.com/@iconify-json/logos@1/icons.json').then(r=>r.json()) }],
})

Context & alternatives

Astro 5.5 made diagramming integrations easier (e.g., by excluding mermaid from syntax highlighting when using rehype/SSR approaches). If you prefer SSR or Playwright-based rendering, see community guides/components.

Choosing between astro-mermaid vs. SSR approaches

Pick astro-mermaid if you want fast, zero-server dependencies and dynamic theming with minimal config (especially for Starlight).
Pick rehype-mermaid/Playwright or SSR components if you require build-time SVG generation (e.g., strict no-JS frontends, PDF export pipelines).

Practical Combinations & Common Issues

Obsidian → Starlight with Mermaid

For Obsidian notes containing Mermaid: either (a) follow the plugin’s Playwright step so vault diagrams render during generation, or (b) disable that and let astro-mermaid render client-side after import; ensure the integration order (mermaid() before starlight()).

Frontmatter fidelity

If you rely on custom YAML fields in Obsidian notes, set copyFrontmatter: ‘starlight’ | ‘all’ and validate downstream usage in Starlight (no schema validation is performed by the plugin).

Access & CI

On hosts without vault access, pre-generate and commit the MDX; flip skipGeneration via env (example: VERCEL).

Understanding Starlight’s Plugin System

Mental Model

A Starlight plugin is a plain object with a unique name and a hooks map. Starlight calls those hooks during initialization so the plugin can read or update Starlight config, add Astro integrations, inject translations, or register route middleware. You enable plugins by listing them in starlight({ plugins: [...] }) inside astro.config.mjs. Starlight Plugins Reference.

Minimal Shape and Lifecycle

The typed shape is StarlightPlugin { name: string; hooks: { 'i18n:setup'?, 'config:setup' } }. config:setup runs at Starlight init and receives helpers like updateConfig, addIntegration, addRouteMiddleware, useTranslations, and a read-only astroConfig. i18n:setup lets you inject UI strings for localization. Starlight Plugins Reference.

// astro.config.mjs — minimal plugin in place
import { defineConfig } from 'astro/config'
import starlight from '@astrojs/starlight'

export default defineConfig({
  integrations: [starlight({
    plugins: [{
      name: 'example-plugin',
      hooks: {
        'i18n:setup'({ injectTranslations }) {
          injectTranslations({ en: { 'example.hello': 'Hello' } })
        },
        'config:setup'({ logger, updateConfig, addIntegration }) {
          logger.info('example-plugin loaded')
          updateConfig({ credits: true })      // tweak Starlight config
          // addIntegration(react())           // optionally add an Astro integration
        }
      }
    }],
    title: 'Docs'
  })]
})

Starlight Plugins Reference.

Ordering and Composition

Plugins run in the order you list them. If multiple plugins add route middleware you can request order: 'pre'|'post' to control execution. Because plugins can read the current config and then call updateConfig, composition becomes “last writer wins” unless a plugin carefully merges existing values. Starlight Plugins Reference.

Internationalization from Plugins

Use i18n:setup to inject translations, then access them in config:setup via useTranslations(lang) or in UI through Astro.locals.t(). Starlight also exposes absolutePathToLang() to help remark/rehype plugins determine the doc language for per-locale behavior. Starlight Plugins Reference.

User Configuration Patterns

Most real plugins export a factory function like myPlugin(userOptions) that returns the plugin object. Validate userOptions with astro/zod and surface helpful errors. This keeps APIs stable and DX predictable. Add user configuration support Anatomy of a plugin.

// Inside a plugin package — options + validation sketch
import { z } from 'astro/zod'
export default function myPlugin(opts) {
  const parsed = z.object({ feature: z.boolean().default(false) }).safeParse(opts)
  if (!parsed.success) throw new Error('Invalid myPlugin options')
  const { feature } = parsed.data
  return {
    name: 'my-plugin',
    hooks: {
      'config:setup'({ updateConfig }) {
        if (feature) updateConfig({ credits: true })
      }
    }
  }
}

Add user configuration support.

Plugin Categories Explained

Official Plugins: Maintained by the Starlight team and documented on the official site. Today this list is small and quality-gated. Example: Algolia DocSearch, which replaces Pagefind as the search provider. You install it and configure it per its guide. Plugins and Integrations.
Community Plugins: Third-party packages that implement the Starlight plugin API above. They are loaded via starlight({ plugins: [communityPlugin()] }), can modify UI or behavior, and often ship sidebar helpers or component overrides. Examples: starlight-obsidian, starlight-markdown-blocks, starlight-versions. Plugins and Integrations.
Community Tools and Integrations: Useful add-ons that are not Starlight plugins. Many are plain Astro integrations, CLIs, component packs, or editor extensions. You install or wire them differently — for instance astro-mermaid goes in integrations: [mermaid(), starlight()] rather than starlight.plugins. Others like starlight-to-pdf are external tools run outside Astro. Plugins and Integrations.

Quick Decision Guide

Do you need to change Starlight behavior, sidebar, i18n, or UI from code that runs at Starlight init? Use a Starlight plugin. Starlight Plugins Reference.
Do you only need a renderer or build capability that is framework-level, like Mermaid, PlantUML, or D2? Install an Astro integration and place it in integrations with Starlight. Plugins and Integrations.
Is it a CLI, VS Code extension, or site-export tool? Treat it as a community tool and follow its own usage docs. Plugins and Integrations.

Real Examples

starlight-obsidian: a Community Plugin that scans an Obsidian vault and writes MD/MDX into your Starlight content tree. It exposes config, sidebar helpers, and respects publish/ignore semantics. Load it via starlight({ plugins: [starlightObsidian({...})] }). Plugins and Integrations.
starlight-markdown-blocks: a Community Plugin that extends the ::: block syntax to define custom asides and a Draft block that hides in production. Load it via starlight.plugins. Plugins and Integrations.
astro-mermaid: a Community Tool — specifically an Astro integration. It renders ```mermaid fences on the client. Place it in integrations before Starlight. Not a Starlight plugin. Plugins and Integrations.

Starlight Plugins

Starlight Plugins

Official Plugins

Community Plugins

Content Generation & Import

Content Enhancement & Authoring

Navigation & User Experience

Interactive Features

Site Management & Quality

Styling & Credits

Community Tools and Integrations

Development & Authoring Tools

Interactive Components & Features

Diagram & Export Tools

Plugin Deep Dives

starlight-obsidian

starlight-markdown-blocks

astro-mermaid

Practical Combinations & Common Issues

Understanding Starlight’s Plugin System

Mental Model

Minimal Shape and Lifecycle

Ordering and Composition

Internationalization from Plugins

User Configuration Patterns

Plugin Categories Explained

Quick Decision Guide

Real Examples