Starlight 配置指南

概述

本文档介绍如何配置 Starlight 文档站点的多语言支持、侧边栏（sidebar）和导航栏（navbar）。

多语言配置

基本配置

在 astro.config.mjs 中配置多语言支持：

export default defineConfig({
  integrations: [
    starlight({
      title: '我的文档',
      defaultLocale: 'root',  // 默认语言
      locales: {
        root: { label: '简体中文', lang: 'zh-CN' },
        en: { label: 'English', lang: 'en' },
        ja: { label: '日本語', lang: 'ja' },
      },
    }),
  ],
});

语言路由规则

root locale → / 路径
其他 locale（如 en）→ /en/ 路径
文件放在对应语言目录下

目录结构示例

src/content/docs/
├── index.mdx           # 中文首页 → /
├── guides/
│   └── getting-started.md
├── en/                 # 英文版本
│   ├── index.mdx       # 英文首页 → /en/
│   └── guides/
│       └── getting-started.md
└── ja/                 # 日文版本
    ├── index.mdx
    └── guides/
        └── getting-started.md

侧边栏配置

自动生成侧边栏

使用 autogenerate 自动从目录生成：

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

手动配置侧边栏

sidebar: [
  {
    label: '指南',
    translations: { 'en': 'Guides' },
    items: [
      { label: '快速开始', link: '/guides/getting-started/' },
      { label: '安装', link: '/guides/installation/' },
    ],
  },
  {
    label: '参考',
    translations: { 'en': 'Reference' },
    items: [
      { label: 'API', link: '/reference/api/' },
      { label: '配置', link: '/reference/config/' },
    ],
  },
],

嵌套侧边栏

sidebar: [
  {
    label: '指南',
    items: [
      {
        label: '开始使用',
        items: [
          { label: '快速开始', link: '/guides/quick-start/' },
          { label: '安装', link: '/guides/installation/' },
        ],
      },
      {
        label: '进阶',
        items: [
          { label: '自定义主题', link: '/guides/theming/' },
          { label: '插件', link: '/guides/plugins/' },
        ],
      },
    ],
  },
],

导航栏配置

顶部导航

在 frontmatter 中配置单页导航栏：

---
title: 我的页面
head:
  - tag: title
    content: 我的页面标题
---

社交链接

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/...' },
],

搜索配置

Starlight 内置 Pagefind 搜索，默认启用。可以在配置中自定义：

starlight({
  title: '我的文档',
  // 自定义搜索配置
  lastUpdated: true,  // 显示最后更新时间
  editLink: {
    baseUrl: 'https://github.com/your-repo/edit/main/',
  },
}),

页面配置

Frontmatter 选项

选项	类型	描述
`title`	string	页面标题
`description`	string	页面描述（SEO）
`template`	string	页面模板（`doc` 或 `splash`）
`hero`	object	首页英雄区域配置
`sidebar`	object	侧边栏配置
`draft`	boolean	草稿状态，不发布

首页模板

---
title: 我的首页
template: splash
hero:
  tagline: 这是首页标语
  image:
    file: ./hero.png
  actions:
    - text: 开始阅读
      link: /guides/getting-started/
      icon: right-arrow
      variant: primary
    - text: 查看文档
      link: /reference/
      icon: open-book
---

国际化字符串

Starlight 使用 JSON 文件管理界面字符串：

中文翻译示例

创建 src/content/i18n/zh-CN.json：

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

注意事项

root locale 映射到根路径 /
其他 locale 会添加路径前缀（如 /en/）
侧边栏的 translations 用于不同语言显示不同标签
建议保持中英文目录结构一致