Customization and Advanced Features

Customization and Advanced Features

Overview

Once the basics are in place, you can extend your documentation site with custom themes, interactive components, and advanced features. This section covers common customization scenarios.

Q&A

Q: How do I customize the theme and colors?

A: Starlight uses CSS custom properties for theming. Create src/styles/custom.css:

:root {
  --sl-color-accent-low: #1e1b4b;
  --sl-color-accent: #6366f1;
  --sl-color-accent-high: #c7d2fe;
  --sl-color-white: #ffffff;
  --sl-color-gray-1: #e5e7eb;
  --sl-color-gray-2: #9ca3af;
  --sl-color-gray-3: #6b7280;
  --sl-color-gray-4: #374151;
  --sl-color-gray-5: #1f2937;
  --sl-color-gray-6: #111827;
  --sl-color-black: #030712;
}

Then reference it in astro.config.mjs:

starlight({
  customCss: ['./src/styles/custom.css'],
})

Starlight also supports light and dark mode. The custom properties above apply to both modes; use :root[data-theme='light'] and :root[data-theme='dark'] selectors for mode-specific overrides.

Q: Can I add interactive components to my documentation?

A: Yes. Starlight is built on Astro, which supports components from any framework:

1. Install a UI framework:

   npm install @astrojs/react react react-dom

2. Configure the integration in astro.config.mjs:

   import react from '@astrojs/react';
   
   export default defineConfig({
     integrations: [starlight({ /* ... */ }), react()],
   });

3. Create a component (e.g., src/components/ApiExplorer.astro):

   ---
   const { endpoint } = Astro.props;
   ---
   <div class="api-explorer">
     <h3>Try it: {endpoint}</h3>
     <button id="try-btn">Send Request</button>
     <pre id="response"></pre>
     <script>
       document.getElementById('try-btn')?.addEventListener('click', async () => {
         const res = await fetch('/api/test');
         const data = await res.json();
         document.getElementById('response')!.textContent = JSON.stringify(data, null, 2);
       });
     </script>
   </div>

4. Use in MDX pages:

   import ApiExplorer from '../../components/ApiExplorer.astro';
   
   # API Reference
   
   <ApiExplorer endpoint="/api/devices" />

Q: How do I add tabs for different languages or platforms?

A: Starlight has built-in tab components:

import { Tabs, TabItem } from '@astrojs/starlight/components';

<Tabs>
  <TabItem label="npm">
    ```bash
    npm install my-package
    ```
  </TabItem>
  <TabItem label="yarn">
    ```bash
    yarn add my-package
    ```
  </TabItem>
  <TabItem label="pnpm">
    ```bash
    pnpm add my-package
    ```
  </TabItem>
</Tabs>

Tabs with the same label are synced across the page — if a user selects “yarn” in one section, all tab groups switch to “yarn.”

Q: How do I add a custom 404 page?

A: Create src/content/docs/404.md:

---
title: "404"
template: splash
---

The page you're looking for doesn't exist.

[Go to homepage](/)

Q: How do I add a print-friendly stylesheet?

A: Add print-specific CSS in your custom stylesheet:

@media print {
  .sl-sidebar,
  .sl-header,
  .starlight-toc,
  .sl-flex {
    display: none !important;
  }

  .main-frame {
    padding: 0 !important;
  }

  body {
    font-size: 12pt;
    line-height: 1.5;
  }

  pre {
    border: 1px solid #ccc;
    page-break-inside: avoid;
  }
}

Users can then use their browser’s print function (Ctrl+P) to get a clean, printable version of any page.

Q: What are some useful Starlight plugins and extensions?

A: The Starlight ecosystem includes several useful extensions:

Plugin	Description
starlight-links-validator	Validates all internal links at build time
starlight-openapi	Generates API reference from OpenAPI specs
starlight-blog	Adds a blog section to your documentation
starlight-image-zoom	Click-to-zoom for images
starlight-package-managers	Multi-package-manager code snippets

Install any plugin:

npm install starlight-links-validator

Configure in astro.config.mjs:

import starlightLinksValidator from 'starlight-links-validator';

export default defineConfig({
  integrations: [
    starlight({
      plugins: [starlightLinksValidator()],
    }),
  ],
});

Summary

You now have a complete toolkit for building a professional documentation site:

1. Framework: Astro + Starlight for fast, SEO-friendly, static documentation
2. Content: Markdown with frontmatter, Content Collections for type safety
3. Multilingual: Built-in i18n with locale routing
4. Deployment: Free hosting on Vercel, GitHub Pages, or Cloudflare Pages
5. Search: Pagefind for local, zero-config search
6. Automation: CI/CD with GitHub Actions, content migration scripts
7. Customization: Themes, interactive components, and plugins

Start small, publish early, and iterate. Your documentation will grow alongside your product.

Building a commercial IoT product?

We provide ESP32 ODM design-to-manufacturing services. From prototype to production — the team behind this tutorial can build it with you.

Talk to us →