DEV Community

Alex Spinov
Alex Spinov

Posted on

Starlight Has a Free API — Build Beautiful Documentation Sites with Astro

#starlight #astro #documentation #webdev

TL;DR

Starlight is an Astro-powered documentation framework that creates fast, accessible docs sites from Markdown. Built-in search, i18n, syntax highlighting, and sidebar generation — zero config needed.

What Is Starlight?

Starlight by the Astro team:

  • Astro-powered — fast static sites with island architecture
  • Markdown/MDX — write docs in Markdown
  • Built-in search — Pagefind search, zero config
  • i18n — multi-language support built-in
  • Auto sidebar — generated from file structure
  • Dark/light mode — automatic theme switching
  • Free — MIT license

Quick Start 

npm create astro@latest -- --template starlight
cd my-docs
npm run dev
Enter fullscreen mode Exit fullscreen mode

Configuration 

// astro.config.mjs
import { defineConfig } from "astro/config";
import starlight from "@astrojs/starlight";

export default defineConfig({
  integrations: [
    starlight({
      title: "My API Docs",
      social: {
        github: "https://github.com/myorg/myproject",
      },
      sidebar: [
        {
          label: "Getting Started",
          items: [
            { label: "Introduction", slug: "getting-started/intro" },
            { label: "Installation", slug: "getting-started/install" },
          ],
        },
        {
          label: "API Reference",
          autogenerate: { directory: "api" },
        },
        {
          label: "Guides",
          autogenerate: { directory: "guides" },
        },
      ],
    }),
  ],
});
Enter fullscreen mode Exit fullscreen mode

Write Documentation 

---
title: "Getting Started"
description: "Learn how to use our API"
---

## Installation
Enter fullscreen mode Exit fullscreen mode


bash
npm install my-sdk


## Quick Example
Enter fullscreen mode Exit fullscreen mode


javascript
import { Client } from "my-sdk";

const client = new Client({ apiKey: "your-key" });
const result = await client.query("Hello");
console.log(result);


:::note
You need an API key to get started. [Get one here](/auth).
:::

:::tip
Use the `--verbose` flag for detailed logging.
:::

:::caution
Never expose your API key in client-side code.
:::
Enter fullscreen mode Exit fullscreen mode


markdown

Custom Components in MDX 

---
title: Interactive Demo
---
import { Card, CardGrid } from '@astrojs/starlight/components';

<CardGrid>
  <Card title="Fast" icon="rocket">
    Built on Astro for lightning performance.
  </Card>
  <Card title="Accessible" icon="accessibility">
    WCAG 2.1 AA compliant out of the box.
  </Card>
</CardGrid>
Enter fullscreen mode Exit fullscreen mode

i18n (Multi-Language) 

starlight({
  title: "My Docs",
  defaultLocale: "en",
  locales: {
    en: { label: "English" },
    es: { label: "Espanol" },
    ja: { label: "Japanese" },
  },
})
Enter fullscreen mode Exit fullscreen mode

Starlight vs Docusaurus vs VitePress

Feature Starlight Docusaurus VitePress
Framework Astro React Vue
Build speed Very fast Slow Fast
Bundle size Tiny (0 JS default) Large Small
Search Pagefind (built-in) Algolia (external) MiniSearch
i18n Built-in Built-in Manual
MDX Yes Yes No (Vue in MD)
Custom components Astro/React/Vue React Vue
Performance 100/100 Lighthouse 85-95 95-100

Resources

Documenting your data APIs? My Apify tools extract web data via REST APIs — document them beautifully with Starlight. Questions? Email spinov001@gmail.com

Top comments (0)