Astro content loader for Sphinx JSON builder output - render RST docs in Starlight
npm install starlight-sphinx-loaderAn Astro content loader that consumes Sphinx JSON builder output, enabling Sphinx-based RST documentation to be rendered in Starlight without migrating away from reStructuredText.
- No RST Migration Required: Keep your existing Sphinx/RST documentation
- Automatic Build Integration: Optionally runs sphinx-build when source files change
- Link Rewriting: Transforms .html links to clean Starlight routes
- Admonition Mapping: Converts Sphinx admonitions to Starlight asides
- Sidebar Generation: Builds Starlight sidebar from Sphinx toctree
- Code Highlighting: Preserves Pygments syntax highlighting classes
``bash`
pnpm add starlight-sphinx-loaderor
npm install starlight-sphinx-loader
- Astro 5.0+
- Node.js 18+
- Python 3.7+ with Sphinx installed
`ts
// src/content.config.ts
import { defineCollection } from "astro:content";
import { sphinxLoader } from "starlight-sphinx-loader";
export const collections = {
docs: defineCollection({
loader: sphinxLoader({
// Path to your Sphinx source directory (contains conf.py)
srcDir: "../path/to/sphinx/source",
// Optional: custom output directory for JSON build
outDir: "../path/to/sphinx/_build/json",
// Optional: skip automatic sphinx-build (use existing JSON)
skipBuild: false,
// Optional: base path for generated routes
basePath: "docs",
}),
}),
};
`
The loader can automatically run sphinx-build when source files change, or you can build manually:
`bashUsing uv (recommended)
cd /path/to/sphinx/source
uv run sphinx-build -b json . ../_build/json
$3
astro
---
// src/pages/docs/[...slug].astro
import { getCollection } from "astro:content";export async function getStaticPaths() {
const docs = await getCollection("docs");
return docs.map((entry) => ({
params: { slug: entry.id },
props: { entry },
}));
}
const { entry } = Astro.props;
---
`Loader Options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
|
| string | required | Path to Sphinx source directory |
| outDir | string | {srcDir}/_build/json | JSON output directory |
| force | boolean | false | Force rebuild even if fresh |
| skipBuild | boolean | false | Skip sphinx-build, use existing JSON |
| basePath | string | "" | Base path for route generation |
| pythonPath | string | "python3" | Python executable path |
| sphinxArgs | string[] | [] | Extra sphinx-build arguments |Schema
Each loaded entry has the following data:
`ts
{
title: string; // Page title
body: string; // Transformed HTML content
description?: string; // First paragraph excerpt
toc?: string; // Page table of contents HTML
prev?: { link, title }; // Previous page navigation
next?: { link, title }; // Next page navigation
parents: { link, title }[]; // Breadcrumb trail
sourcename?: string; // Original RST filename
sphinxProject?: string; // Project name from conf.py
sphinxVersion?: string; // Sphinx version used
}
`Sidebar Generation
The loader exports a helper to generate Starlight sidebar configuration:
ts
import { getSphinxSidebar } from "starlight-sphinx-loader";const sidebar = await getSphinxSidebar({
srcDir: "../path/to/sphinx/source",
basePath: "docs",
});
// Use in astro.config.mjs
export default defineConfig({
integrations: [
starlight({
sidebar: [
{ label: "Documentation", items: sidebar },
],
}),
],
});
`HTML Transformations
The loader applies several transformations to Sphinx HTML output:
1. Link Rewriting:
extensions removed, paths adjusted for Starlight
2. Admonition Conversion: Sphinx note/warning/tip → Starlight aside components
3. Code Block Enhancement: Pygments classes mapped to standard language identifiers
4. Sphinx Markup Cleanup: Removes paragraph markers (¶), viewcode links, etc.Custom Styles
Include custom CSS to style Sphinx-specific elements:
`css
/ Autodoc signatures /
.sig-name { font-weight: 600; }/ Version badges /
.version-added { background: green; }
.version-deprecated { background: red; }
/ API documentation /
dl.py.function { border-left: 3px solid blue; }
`See
for a complete stylesheet.Example
See the
example/ directory for a complete working example using Reticulum's documentation.`bash
cd example
pnpm install
pnpm dev
``MIT