使用 Astro 搭建文档网站

Astro 是构建文档网站的理想选择，原因如下：

性能优先：Astro 的零 JavaScript 默认策略确保文档网站加载迅速
Markdown 支持：原生支持 Markdown 和 MDX，让文档编写更轻松
内容集合：强大的内容管理系统，适合处理大量文档
SEO 友好：静态生成确保搜索引擎能够有效索引内容

创建文档项目

1. 初始化项目

使用以下命令创建新的 Astro 项目：

npm create astro@latest my-docs

在配置过程中：

选择 “Empty” 模板开始
根据需要选择是否使用 TypeScript
安装依赖项

2. 添加文档主题

Astro 提供了多个优秀的文档主题，我们以官方的 docs 主题为例：

npx astro add @astrojs/starlight

3. 配置文档结构

在 astro.config.mjs 中配置文档主题：

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

export default defineConfig({
  integrations: [
    starlight({
      title: '我的文档',
      description: '项目文档网站',
      defaultLocale: 'zh-cn',
      locales: {
        'zh-cn': {
          label: '简体中文',
          lang: 'zh-CN',
        },
      },
      sidebar: [
        {
          label: '开始使用',
          items: [
            { label: '简介', link: '/' },
            { label: '快速开始', link: '/getting-started' },
          ],
        },
      ],
    }),
  ],
});

组织文档内容

1. 创建文档页面

在 src/content/docs 目录下创建 Markdown 文件：

---
title: 快速开始
description: 开始使用我们的产品
---

# 快速开始

欢迎使用我们的产品...

2. 设置导航结构

使用 frontmatter 配置页面元数据
在 sidebar 配置中组织文档层级
添加自动生成的目录

3. 添加基础样式

创建 src/styles/custom.css 文件：

:root {
  --sl-color-accent: #00539F;
  --sl-color-accent-low: #E1E6F6;
}

增强文档功能

1. 搜索功能

Starlight 主题默认包含搜索功能，可以通过配置优化：

starlight({
  // ...
  search: {
    indexLocales: true,
    searchOptions: {
      includeFuzzy: true,
    },
  },
});

2. 版本控制

为不同版本的文档创建独立的分支或目录：

src/content/docs/
  ├── v1/
  │   └── guide.md
  └── v2/
      └── guide.md

3. 自定义组件

创建可重用的文档组件：

<div class="tutorial">
  <slot />
</div>

<style>
.tutorial {
  padding: 1rem;
  border: 1px solid var(--sl-color-gray-5);
  border-radius: 0.5rem;
}
</style>

最佳实践

文档结构
- 使用清晰的目录结构
- 保持导航层级简洁
- 为每个页面添加适当的元数据
内容编写
- 使用一致的写作风格
- 添加适当的代码示例
- 包含实用的图片和图表
性能优化
- 优化图片资源
- 合理使用客户端组件
- 确保快速的页面加载时间

下一步

完成基础文档站点的搭建后，你可以：

添加更多自定义样式
集成评论系统
添加多语言支持
配置自动部署

通过这些步骤，你已经可以使用 Astro 搭建一个功能完整的文档网站。在接下来的章节中，我们将深入探讨内容管理和主题定制的更多细节。