logo
简体中文

导航菜单

Astro 介绍

使用 Astro 搭建文档网站

项目结构推荐

  • src/pages：文档页面（Markdown/MDX）。
  • src/layouts：文档布局（导航、侧栏、页脚、版本切换）。
  • src/content：内容集合配置，校验 frontmatter。
  • src/components：复用的 UI（导航、目录、提示、卡片）。

侧边栏与导航

  • 用数据驱动：const nav = [{ title, slug, items: [...] }]。
  • 布局中渲染侧栏，当前路径高亮。
  • 顶部导航放搜索、主题切换、版本切换。

Markdown/MDX 组合

  • Markdown 书写正文，MDX 引入交互组件（如 Demo、提示框、代码切换）。
  • 在 MDX 顶部导入组件，并通过 export const components 映射 h2 等标签。
  • 使用提示组件（info/success/warning）强调注意事项。

代码示例与高亮

  • 使用代码块 ```js/ts 等，必要时开启行号/高亮。
  • 提供可复制按钮或 Demo 链接。
  • 多版本代码可用 Tab 切换（React/Vue/Svelte）。

搜索与目录

  • 构建时生成静态索引 JSON，前端用 Fuse.js/Lunr 搜索。
  • 页面内目录（TOC）可根据标题生成，放在侧栏或右侧浮动。

部署与预览

  • pnpm build 输出静态站点，部署到静态托管（CF Pages/Netlify/Vercel）。
  • 预览环境用于审校文档与链接检查。

常见问题

  • 链接 404：检查路由大小写、路径前缀、站点 base。
  • 代码高亮缺失：确认高亮主题或 Shiki/Prism 配置。
  • TOC 不更新：确保标题层级规范，避免跳级。***

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

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

创建文档项目

1. 初始化项目

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

npm create astro@latest my-docs

在配置过程中：

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

2. 添加文档主题

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

npx astro add @astrojs/starlight

3. 配置文档结构

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

import HeadingWithIconH2 from '@/components/mdx/HeadingWithIconH2.astro';

export const components = {
  h2: HeadingWithIconH2,
};
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. 自定义组件

创建可重用的文档组件：

---
// src/components/Tutorial.astro
---
<div class="tutorial">
  <slot />
</div>

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

最佳实践

  1. 文档结构

    • 使用清晰的目录结构
    • 保持导航层级简洁
    • 为每个页面添加适当的元数据

  2. 内容编写

    • 使用一致的写作风格
    • 添加适当的代码示例
    • 包含实用的图片和图表

  3. 性能优化

    • 优化图片资源
    • 合理使用客户端组件
    • 确保快速的页面加载时间

下一步

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

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

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

上一章节组件和页面开发深入理解 Astro 的组件系统和页面构建 下一章节文档内容管理和主题定制深入了解 Astro 文档站点的内容管理和主题定制方法

搜索