如何使用Astro与Starlight搭建多版本文档站点？

1. 规划版本化内容目录结构 #

按版本划分文档目录，方便区分复用内容与版本独有内容：

src/
├── content/
│   ├── docs/
│   │   ├── v1.0/          # 1.0版本完整内容
│   │   │   ├── get-started.md
│   │   │   └── how-to.md
│   │   ├── v2.0/          # 2.0版本内容
│   │   │   ├── get-started.md  # 复用1.0内容
│   │   │   └── how-to.md       # 2.0独有内容
│   │   └── latest/        # 软链指向最新版本（如v2.0）

跨版本页面复用方式 #

• 完全一致的页面：用符号链接复用，在目标版本目录执行命令：

  ln -s ../v1.0/get-started.md get-started.md
  

• 部分内容一致的页面：抽离公共内容到Astro组件，比如创建src/components/CommonGetStarted.astro，再在各版本的get-started.md中引用：

  ---
  title: 快速开始
  ---
  <CommonGetStarted />
  
  <!-- 当前版本特有内容（可选） -->
  

2. 配置Starlight多版本支持 #

修改astro.config.mjs，添加版本配置并设置latest为默认版本：

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      title: '你的文档站点',
      versions: {
        latest: {
          label: 'Latest (v2.0)',
          path: '/',  // 根路径映射到latest版本
        },
        'v2.0': {
          label: 'v2.0',
          path: '/v2.0/',
        },
        'v1.0': {
          label: 'v1.0',
          path: '/v1.0/',
        },
      },
      defaultVersion: 'latest',  // 默认加载latest版本
    }),
  ],
});

3. 自定义版本选择器组件 #

Starlight未内置版本选择器时，手动实现一个：

1. 创建版本选择器组件 #

在src/components/VersionSelector.astro中编写：

---
import { useSite } from '@astrojs/starlight/utils';

const site = useSite();
// 解析当前页面所属版本
const currentVersion = Astro.url.pathname.split('/')[1] || 'latest';
---
<div class="version-selector">
  <span>选择版本：</span>
  <select 
    value={currentVersion}
    onChange={(e) => {
      const targetVersion = e.target.value;
      // 生成目标版本的页面路径
      const cleanPath = Astro.url.pathname.replace(/^\/(v\d+\.|)/, '');
      const targetPath = targetVersion === 'latest' ? `/${cleanPath}` : `/${targetVersion}/${cleanPath}`;
      window.location.href = targetPath;
    }}
  >
    {Object.entries(site.config.versions).map(([key, config]) => (
      <option key={key} value={key}>{config.label}</option>
    ))}
  </select>
</div>

<style>
.version-selector {
  margin: 1rem 2rem;
  display: flex;
  gap: 0.5rem;
  align-items: center;
}
select {
  padding: 0.3rem 0.5rem;
  border-radius: 4px;
  border: 1px solid #e2e8f0;
}
</style>

2. 集成到Starlight布局 #

创建自定义布局文件src/layouts/BaseLayout.astro，将选择器加入侧边栏：

---
import Base from '@astrojs/starlight/layouts/Base.astro';
import VersionSelector from '../components/VersionSelector.astro';
---
<Base>
  <slot />
  <!-- 将选择器放在侧边栏底部 -->
  <VersionSelector slot="sidebar-footer" />
</Base>

3. 配置使用自定义布局 #

在astro.config.mjs中指定自定义布局：

starlight({
  // ...其他配置
  components: {
    Layout: './src/layouts/BaseLayout.astro',
  },
})

4. 测试验证 #

• 访问根路径/，默认加载latest版本内容
• 切换版本选择器，能正确跳转到对应版本的页面
• 复用页面（如get-started.md）在不同版本内容一致，独有页面（如how-to.md）内容不同

内容的提问来源于stack exchange，提问作者Jay