初始化 Astro + Starlight 项目

初始化 Astro + Starlight 项目

概述

本节逐步演示从零创建 Astro + Starlight 文档站的完整步骤。完成后，你将拥有一个运行中的本地开发服务器和可工作的文档站。

问答

Q：开始之前需要什么？

A：确保已具备：

• Node.js v22+（通过 node --version 检查）
• npm（随 Node.js 安装）
• 代码编辑器（推荐 VS Code，安装 Astro 扩展）

Q：如何创建项目？

A：使用官方 Astro CLI 脚手架：

# 使用 Starlight 模板创建新 Astro 项目
npm create astro@latest my-docs -- --template starlight

# 进入项目目录
cd my-docs

# 安装依赖
npm install

# 启动开发服务器
npm run dev

CLI 会询问几个问题：

• TypeScript：选择 “Strict” 以获得类型安全
• Install dependencies：Yes
• Git repository：Yes（初始化 Git 仓库）

启动后，打开 http://localhost:4321 查看你的新文档站。

Q：初始项目结构是什么样的？

A：脚手架生成后的项目包含：

my-docs/
├── src/
│   ├── content/
│   │   └── docs/          # 文档内容放在这里
│   │       ├── index.md   # 首页
│   │       └── guide.md   # 示例指南页面
│   └── content.config.ts  # Content Collection 配置
├── public/                 # 静态资源（图片、favicon 等）
├── astro.config.mjs       # Astro + Starlight 配置
├── package.json
└── tsconfig.json

Q：如何配置基本站点设置？

A：编辑 astro.config.mjs：

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

export default defineConfig({
  site: 'https://docs.yourcompany.com',
  integrations: [
    starlight({
      title: '我的产品文档',
      social: [
        { icon: 'github', label: 'GitHub', href: 'https://github.com/yourcompany' },
      ],
      sidebar: [
        {
          label: '指南',
          items: [{ autogenerate: { directory: 'guides' } }],
        },
        {
          label: '参考',
          items: [{ autogenerate: { directory: 'reference' } }],
        },
      ],
    }),
  ],
});

关键设置：

• site：生产环境 URL（用于站点地图和 SEO 元数据）
• title：显示在头部和浏览器标签页
• sidebar：定义导航结构
• autogenerate：从 Markdown 文件目录自动生成侧边栏项

Q：如何添加第一个内容页面？

A：在 src/content/docs/ 中创建 Markdown 文件：

---
title: 快速开始
description: 学习如何安装和配置本产品。
---

## 快速开始

欢迎阅读本文档！本指南将帮助你快速上手。

### 安装

使用 npm 安装软件：

\```bash
npm install my-product
\```

### 配置

创建配置文件 `config.yaml`：

\```yaml
port: 8080
database:
  host: localhost
  port: 5432
\```

### 下一步

- 阅读 [API 参考](/reference/api/)
- 查看 [示例项目](/guides/examples/)

frontmatter 中的 title 是必填项。Starlight 将其用于页面标题、侧边栏标签和 SEO 元数据。

Q：index.md 和其他文件有什么区别？

A：每个目录可以有一个 index.md 作为该目录的着陆页：

src/content/docs/
├── index.md          # 站点首页（带英雄横幅）
├── guides/
│   ├── index.md      # 指南板块着陆页
│   ├── setup.md      # /guides/setup/
│   └── examples.md   # /guides/examples/
└── reference/
    └── api.md        # /reference/api/

根目录的 index.md 可使用 splash 模板创建英雄着陆页：

---
title: 首页
template: splash
hero:
  title: 我的产品文档
  tagline: 使用我的产品构建所需的一切。
  actions:
    - text: 快速开始
      link: /guides/setup/
      variant: primary
    - text: 查看 GitHub
      link: https://github.com/yourcompany
      variant: secondary
---

正在开发商业 IoT 产品？

我们提供 ESP32 ODM 定制设计与制造服务。从原型到量产——编写这套教程的团队，可以和你一起实现。

联系我们 →