项目结构与内容管理

概述

良好的项目结构让文档易于维护和扩展。本节介绍如何组织内容、管理静态资源，以及使用 Astro 的 Content Collections 实现类型安全的文档。

问答

Q：如何组织文档内容？

A：Starlight 采用基于目录的路由系统。src/content/docs/ 中的每个 .md 文件对应一个页面：

src/content/docs/
├── index.md                    # 首页 (/)
├── getting-started/
│   ├── index.md               # /getting-started/
│   ├── installation.md        # /getting-started/installation/
│   └── configuration.md       # /getting-started/configuration/
├── guides/
│   ├── index.md               # /guides/
│   ├── first-project.md       # /guides/first-project/
│   └── deployment.md          # /guides/deployment/
└── reference/
    ├── index.md               # /reference/
    ├── api.md                 # /reference/api/
    └── cli.md                 # /reference/cli/

组织原则：

将相关页面分组到目录中（章节、主题、分类）
每个目录有一个 index.md 作为着陆页，包含子页面链接
在源文件中使用数字前缀排序，但让侧边栏配置控制显示顺序
文件名保持简短且描述性强（它们会成为 URL 路径）

Q：frontmatter schema 是什么？

A：每个 Markdown 文件顶部需要 YAML frontmatter。Starlight 内置的 schema 要求：

---
title: 页面标题              # 必填：页面标题
description: 简要描述          # 可选：SEO meta 描述
---

额外的 frontmatter 选项：

---
title: 页面标题
description: 简要描述
tableOfContents: false          # 禁用目录
head:                           # 自定义 <head> 标签
  - tag: meta
    attrs:
      name: robots
      content: noindex
---

Q：如何包含图片和其他资源？

A：静态资源放在 public/ 目录中：

public/
├── images/
│   ├── architecture-diagram.png
│   └── screenshot-setup.png
├── favicon.svg
└── logo.svg

在 Markdown 中使用绝对路径引用：

![安装截图](/images/screenshot-setup.png)

对于需要优化（响应式、懒加载）的图片，在 MDX 文件中使用 Astro 的 <Image> 组件。

Q：Content Collections 如何工作？

A：Content Collections 提供类型安全的内容加载。配置在 src/content.config.ts 中：

import { defineCollection } from 'astro:content';
import { glob } from 'astro/loaders';
import { docsSchema } from '@astrojs/starlight/schema';

export const collections = {
  docs: defineCollection({
    loader: glob({
      base: 'src/content/docs',
      pattern: '**/[^_]*.md',
    }),
    schema: docsSchema(),
  }),
};

优势：

类型检查：frontmatter 不符合 schema 时构建失败
自动生成类型：TypeScript 获得内容字段的自动补全
结构一致：所有页面遵循相同的 schema

Q：如何添加带语法高亮的代码块？

A：Starlight 内置 Shiki 语法高亮。使用三反引号加语言标识符：

```javascript
const response = await fetch('/api/devices');
const devices = await response.json();
```

```yaml
mqtt:
  broker: mqtt://localhost:1883
  topic: sensors/temperature
```

```bash
npm run build
```

支持的功能：

行高亮：在语言后添加 {1,3} 高亮特定行
差异高亮：使用 diff 语言配合 + 和 - 前缀
文件名：添加 title="filename.js" 显示文件名标题
行号：Starlight 默认启用

Q：如何添加提示框（提示、警告、注意）？

A：Starlight 支持 GitHub 风格的提示框：

> [!NOTE]
> 这是补充说明的注释。

> [!TIP]
> 这是一个有用的提示。

> [!CAUTION]
> 这是一个关键警告。

> [!DANGER]
> 此操作不可逆。

这些在文档中渲染为带样式的提示框。

正在开发商业 IoT 产品？

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

联系我们 →