Starlight 配置指南

概述

本指南介绍如何为 Starlight 文档站点配置多语言支持、侧边栏和导航栏。

国际化配置

基础配置

在 astro.config.mjs 中配置国际化支持：

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

路由规则

root 语言环境 → / 路径
其他语言环境（如 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: 'Guides',
    translations: { 'zh-CN': '指南', 'ja': 'ガイド' },
    autogenerate: { directory: 'guides' },
  },
  {
    label: 'Best Practices',
    translations: { 'zh-CN': '最佳实践', 'ja': 'ベストプラクティス' },
    autogenerate: { directory: 'best-practices' },
  },
],

手动侧边栏配置

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

嵌套侧边栏

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

导航栏配置

顶部导航

在 frontmatter 中配置单页导航栏：

---
title: My Page
head:
  - tag: title
    content: My Page Title
---

社交链接

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: 'My Docs',
  // 自定义搜索配置
  lastUpdated: true,  // 显示最后更新时间
  editLink: {
    baseUrl: 'https://github.com/your-repo/edit/main/',
  },
}),

页面配置

Frontmatter 选项

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

Splash 模板

---
title: My Home
template: splash
hero:
  tagline: 这是我的首页标语
  image:
    ./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 语言环境映射到根路径 /
其他语言环境会添加路径前缀（如 /en/）
侧边栏 translations 为不同语言显示不同标签
保持中英文目录结构一致