starlight-sphinx-loader

An Astro content loader that consumes Sphinx JSON builder output, enabling Sphinx-based RST documentation to be rendered in Starlight without migrating away from reStructuredText.

Features

• 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

Installation

pnpm add starlight-sphinx-loader
# or
npm install starlight-sphinx-loader

Requirements

• Astro 5.0+
• Node.js 18+
• Python 3.7+ with Sphinx installed

Usage

1. Configure your content collection

// 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",
    }),
  }),
};

2. Build Sphinx JSON (if not using automatic build)

The loader can automatically run sphinx-build when source files change, or you can build manually:

# Using uv (recommended)
cd /path/to/sphinx/source
uv run sphinx-build -b json . ../_build/json

# Or with pip-installed sphinx
sphinx-build -b json source _build/json

3. Access content in your pages

---
// 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;
---

<article set:html={entry.data.body} />

Loader Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | srcDir | 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:

{
  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:

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: .html 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:

/* 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 example/src/styles/sphinx.css for a complete stylesheet.

Example

See the example/ directory for a complete working example using Reticulum's documentation.

cd example
pnpm install
pnpm dev

License

MIT