starlight-theme-mdbook

A Starlight theme that looks and feels like rust-lang's mdBook (live example, used for The Rust Programming Language book) — layout, chrome, and color schemes — while keeping all of Starlight's own functionality (content collections, Markdown/MDX, Pagefind search, i18n, sidebar autogeneration, etc.) untouched underneath.

Install

npm install starlight-theme-mdbook

Usage

Add the plugin to your astro.config.mjs:

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

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

That's it — the theme wires up its component overrides and CSS automatically.

What's included

• Color schemes — Light, Dark (mdBook's Coal), Rust, plus two bonus palettes ported from daisyUI (Valentine, Caramellatte) — selectable from an icon-only paintbrush button in the navbar, matching mdBook's own theme popup.
• Layout — a genuine full-height left sidebar, a navbar confined to the content column with mdBook's exact button layout (hamburger · theme · search — left; print · git repo · edit — right), and a draggable resize handle on the sidebar's edge.
• "On this page" — heading TOC injected directly into the left sidebar under the active chapter link, instead of Starlight's default right sidebar (mdBook doesn't have a separate TOC column).
• Chapter navigation — floating ←/→ arrow buttons pinned to the viewport edges (collapsing to inline buttons on narrow screens), with real Left/Right arrow-key navigation ported from mdBook's book.js.
• Mobile — the sidebar is a true collapsible overlay at any screen width, auto-closes when you tap a real navigating link, and the navbar's icon clusters shrink to fit narrow screens.

This theme does not ship custom webfonts (mdBook uses Open Sans/Source Code Pro) — an npm package can't easily place font files into a consumer's public/ directory, so it uses Starlight's default system-font stack instead.

Configuring your docs

Same as any Starlight site — title, social, editLink, sidebar, etc. all work normally alongside the plugin. One recommendation: list your index page explicitly in sidebar (e.g. { label: 'Introduction', slug: 'index' }) so it participates in prev/next chapter navigation instead of being an orphaned homepage, matching how mdBook treats its own index.md.

Credits

This theme's layout, chrome, and color schemes are visually ported from rust-lang/mdBook (MPL-2.0) — all code here is freshly written for Astro/Starlight, not a fork, but the design and several behaviors (drag-to-resize, arrow-key chapter navigation) are directly adapted from mdBook's own front-end. Full credit to the mdBook maintainers and contributors.

The Valentine and Caramellatte color themes are ported from daisyUI by Pouya Saadeghi. Thanks!

License

MIT