用 Starlight 搭建可检索的知识库

Starlight 是 Astro 官方文档主题，默认自带侧边栏、全文搜索（Pagefind）、深色模式和 SEO 配置，适合做知识库而不是营销站。

本文记录 Starlight 的使用方式。本站后来切换到了 Devosfera 主题，文章保留作为技术笔记。

初始化

npm create astro@latest . -- --template starlight
npm install
npm run dev

模板会生成 src/content/docs/ 作为内容目录，所有 .md / .mdx 文件按路径自动成为路由。

src/content/docs/
├── index.mdx      # 首页（template: splash）
├── about.md
├── tech/
│   ├── index.md
│   └── example.md
└── reading/

侧边栏可以显式列出，也可以按目录自动生成：

sidebar: [
  { label: '开始', items: [{ label: '关于本站', slug: 'about' }] },
  { label: '技术', items: [{ autogenerate: { directory: 'tech' } }] },
]

autogenerate 会读取目录内页面的 title，并用 frontmatter 里的 sidebar.order 排序。

Starlight 在构建时用 Pagefind 生成静态索引，不需要额外服务。快捷键是 Ctrl + K（macOS 上是 Cmd + K），搜索框会索引页面正文。

首页 frontmatter 加 template: splash，再用 hero 和 CardGrid 组成入口页：

---
title: 首页
template: splash
hero:
  title: Notebook
  tagline: 把零散的知识，整理成可检索、可复用的体系。
---

纯静态站点不需要 @astrojs/cloudflare 适配器，astro build 产物直接托管即可。具体步骤见 Cloudflare Workers 静态部署。