Skip to content
Tuist

Starlight Configuration Guide

Overview

Section titled “Overview”

This guide explains how to configure multilingual support, sidebar, and navbar for your Starlight documentation site.

i18n Configuration

Section titled “i18n Configuration”

Basic Configuration

Section titled “Basic Configuration”

Configure i18n support in astro.config.mjs:

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      defaultLocale: 'root',  // Default language
      locales: {
        root: { label: '简体中文', lang: 'zh-CN' },
        en: { label: 'English', lang: 'en' },
        ja: { label: '日本語', lang: 'ja' },
      },
    }),
  ],
});

Routing Rules

Section titled “Routing Rules”
  • root locale → / path
  • Other locales (e.g., en) → /en/ path
  • Place files in corresponding language directories

Directory Structure Example

Section titled “Directory Structure Example”
src/content/docs/
├── index.mdx           # Chinese home → /
├── guides/
│   └── getting-started.md
├── en/                 # English version
│   ├── index.mdx       # English home → /en/
│   └── guides/
│       └── getting-started.md
└── ja/                 # Japanese version
    ├── index.mdx
    └── guides/
        └── getting-started.md
Section titled “Sidebar Configuration”

Auto-generated Sidebar

Section titled “Auto-generated Sidebar”

Use autogenerate to automatically generate from directories:

sidebar: [
  {
    label: 'Guides',
    translations: { 'zh-CN': '指南', 'ja': 'ガイド' },
    autogenerate: { directory: 'guides' },
  },
  {
    label: 'Best Practices',
    translations: { 'zh-CN': '最佳实践', 'ja': 'ベストプラクティス' },
    autogenerate: { directory: 'best-practices' },
  },
],

Manual Sidebar Configuration

Section titled “Manual Sidebar Configuration”
sidebar: [
  {
    label: 'Guides',
    translations: { 'zh-CN': '指南' },
    items: [
      { label: 'Getting Started', link: '/guides/getting-started/' },
      { label: 'Installation', link: '/guides/installation/' },
    ],
  },
  {
    label: 'Reference',
    translations: { 'zh-CN': '参考' },
    items: [
      { label: 'API', link: '/reference/api/' },
      { label: 'Configuration', link: '/reference/config/' },
    ],
  },
],

Nested Sidebar

Section titled “Nested Sidebar”
sidebar: [
  {
    label: 'Guides',
    items: [
      {
        label: 'Getting Started',
        items: [
          { label: 'Quick Start', link: '/guides/quick-start/' },
          { label: 'Installation', link: '/guides/installation/' },
        ],
      },
      {
        label: 'Advanced',
        items: [
          { label: 'Theming', link: '/guides/theming/' },
          { label: 'Plugins', link: '/guides/plugins/' },
        ],
      },
    ],
  },
],
Section titled “Navbar Configuration”

Top Navigation

Section titled “Top Navigation”

Configure single page navbar in frontmatter:

---
title: My Page
head:
  - tag: title
    content: My Page Title
---
Section titled “Social Links”
social: [
  { icon: 'github', label: 'GitHub', href: 'https://github.com/...' },
  { icon: 'twitter', label: 'Twitter', href: 'https://twitter.com/...' },
  { icon: 'discord', label: 'Discord', href: 'https://discord.com/...' },
],

Search Configuration

Section titled “Search Configuration”

Starlight includes Pagefind search, enabled by default. Customize in config:

starlight({
  title: 'My Docs',
  // Custom search config
  lastUpdated: true,  // Show last updated time
  editLink: {
    baseUrl: 'https://github.com/your-repo/edit/main/',
  },
}),

Page Configuration

Section titled “Page Configuration”

Frontmatter Options

Section titled “Frontmatter Options”
OptionTypeDescription
titlestringPage title
descriptionstringPage description (SEO)
templatestringPage template (doc or splash)
heroobjectHero section config for splash template
sidebarobjectSidebar config
draftbooleanDraft status, won’t be published

Splash Template

Section titled “Splash Template”
---
title: My Home
template: splash
hero:
  tagline: This is my homepage tagline
  image:
    ./hero.png
  actions:
    - text: Get Started
      link: /guides/getting-started/
      icon: right-arrow
      variant: primary
    - text: View Docs
      link: /reference/
      icon: open-book
---

i18n Strings

Section titled “i18n Strings”

Starlight uses JSON files for UI strings:

Translation Example

Section titled “Translation Example”

Create src/content/i18n/zh-CN.json:

{
  "skipLink.label": "跳转到内容",
  "search.label": "搜索",
  "sidebarNav.accessibleLabel": "主导航",
  "tableOfContents.onThisPage": "本页内容"
}

Notes

Section titled “Notes”
  • root locale maps to root path /
  • Other locales add path prefix (e.g., /en/)
  • Sidebar translations shows different labels for different languages
  • Keep Chinese and English directory structures consistent
Section titled “Related Links”