GitHub 8.2K Star!这个文档框架让你5分钟搭出高颜值技术文档站

不知道你有没有这种经历？花了几天写了个超棒的开源项目，结果文档站搭得稀烂，用户进来就迷路。或者是公司技术文档用传统的 Wiki，搜索功能跟没有一样，找个 API 说明要翻半天。

我最近发现一个特别香的项目，叫 Starlight。这是 Astro 团队官方出品的文档站框架，在 GitHub 上已经拿了 8.2K 的 Star，而且增长势头很猛。说白了，它就是为了解决”技术文档长得丑、难用、加载慢”这些痛点而生的。

第一眼看到 Starlight 的演示站，我就被惊艳到了。暗黑模式支持得特别自然，不是那种硬切黑白，而是整套配色都做了适配。而且你注意到没有，它的搜索功能是开箱即用的，不需要你去接 Algolia 或者配置什么复杂的搜索服务，部署完就能直接用。

更爽的是，Starlight 基于 Astro 构建，天生就带了性能优势。页面加载速度贼快，Lighthouse 跑分基本都能到 95+。StackBlitz 团队都说这是他们用过 DX（开发体验）最好的文档工具 。

动手试试，真的只要5分钟

别光看我吹，咱们直接上手搞一个。你需要先装好 Node.js（建议 18 版本以上），然后打开终端：

npm create astro@latest -- --template starlight

这时候会问你项目叫什么名字、要不要装依赖之类的，按提示选就行。我一般是选 TypeScript 严格模式，毕竟文档站后面大概率会加一些自定义组件，类型安全还是很重要的。

装完之后进目录：

cd 你的项目名npm run dev

打开浏览器访问 http://localhost:4321，你就能看到一个像模像样的文档站了。默认就已经有了首页、搜索框、侧边栏导航，甚至还带了”编辑此页”的链接。这开箱体验，比某些要配置半天导航栏的工具强太多了 。

怎么往里加内容？

Starlight 的内容都放在 src/content/docs/ 这个目录下。你每创建一个 Markdown 文件，就会自动生成一个对应的页面。

比如你想加个”快速开始”的页面，就新建 src/content/docs/getting-started.md：

---title: 快速开始description: 5分钟上手我们的项目---# 快速开始欢迎使用！按照下面的步骤，几分钟就能跑起来...

看到上面那两个 --- 包裹的东西没？那是 frontmatter，用来配置页面标题、描述这些元信息的。Starlight 会读取这些信息自动生成页面标题、SEO 标签，还有右侧的目录导航。

如果你想搞个多级结构，直接建文件夹就行。比如 src/content/docs/guides/installation.md 会自动对应到 /guides/installation 这个路径。这种基于文件的路由方式特别直观，不用去配置文件里写一堆路由规则 。

而且 Starlight 不只是支持 Markdown，它还原生支持 MDX 和 Markdoc。这意味着你想在文档里插 React 组件、Vue 组件都行，灵活性拉满。之前用其他文档工具，想加个交互式 Demo 得折腾半天，现在直接写个组件导入就完事了 。

侧边栏和导航，配置起来超简单

很多文档工具最让人头疼的就是配置侧边栏，动不动就要写一大堆 JSON。Starlight 这方面做得挺人性化的，打开 astro.config.mjs 文件，找到 starlight 的配置项：

import { defineConfig } from'astro/config';import starlight from'@astrojs/starlight';exportdefault defineConfig({integrations: [    starlight({title: '我的项目文档',sidebar: [        {label: '指南',items: [            { label: '简介', slug: 'index' },            { label: '安装', slug: 'getting-started' },          ],        },        {label: '参考',autogenerate: { directory: 'reference' },        },      ],    }),  ],});

看到那个 autogenerate 没？这是 Starlight 的懒人福音。你只要告诉它目录名，它会自动扫描 src/content/docs/reference/ 下的所有文件，按文件名排序生成侧边栏链接。这样你新增文档的时候，侧边栏会自动更新，不用每次都去改配置 。

如果你想让某个分组默认折叠起来，加个 collapsed: true 就行：

{label: '高级用法',collapsed: true,items: ['advanced/config', 'advanced/deploy'],}

多语言支持，做国际化没压力

要是你的项目需要支持多语言，Starlight 也帮你想好了。在配置里加上 locales：

starlight({title: 'My Docs',locales: {root: {label: '中文',lang: 'zh-CN',    },en: {label: 'English',lang: 'en',    },  },});

这样它就会自动处理语言切换，而且 SEO 也帮你做好了，会自动生成正确的 hreflang 标签。内容文件放在 src/content/docs/en/ 下对应英文版，放根目录就是中文。翻译的时候还可以给侧边栏标签单独配多语言版本，用户体验很完整 。

搜索、SEO、暗黑模式，全都内置了

说说搜索这个功能，真的太省心了。Starlight 内置了 Pagefind 搜索，这是一个纯前端的搜索方案，构建时会自动索引所有内容。部署之后用户就能全文搜索，支持中文分词，响应速度也很快。而且它是完全免费的，不像有些方案还要配搜索服务或者买商业授权 。

SEO 方面也是开箱即用，自动生成 sitemap，每个页面都有规范的 meta 标签。如果你想加 Google Analytics 或者百度统计，直接在 head 配置里插脚本就行：

starlight({head: [    {tag: 'script',attrs: {src: 'https://your-analytics.js',defer: true,      },    },  ],});

暗黑模式更是不用你操心，右上角自动有个主题切换按钮，而且会记住用户的选择。代码高亮也是自动适配主题，浅色模式下用一种高亮方案，切到深色模式就自动换另一套配色，读起来眼睛特别舒服 。

部署到哪儿都方便

因为 Starlight 生成的是静态 HTML，部署特别灵活。你可以丢到 Vercel、Netlify、Cloudflare Pages，或者国内的阿里云 OSS、腾讯云 COS 都行。甚至可以直接用 GitHub Pages 托管。

如果是部署到子目录（比如 https://example.com/docs/），记得在 astro.config.mjs 里加个 base 配置：

exportdefault defineConfig({base: '/docs',integrations: [starlight({ title: 'My Docs' })],});

有团队把整个文档站从 Docusaurus 迁到 Starlight 后，构建产物从 8.2MB 缩减到 1.5MB，移动端访问量直接涨了 47% 。这性能提升，对于一些网络环境不太好的用户来说，体验差距非常明显。

总结一下

Starlight 这项目最让我喜欢的地方，是它不折腾。你不需要为了好看的样式去调半天 CSS，不需要为了搜索功能去申请 API Key，也不需要为了 SEO 去手动生成 sitemap。这些东西它都内置了，而且做得相当专业。

当然，如果你需要深度定制，它也不会拦着你。毕竟是基于 Astro 的，你可以写自己的组件，可以扩展主题，甚至可以把 Starlight 集成到已有的 Astro 项目里当文档模块用 。

如果你正准备给项目搭文档站，或者现在的文档站用得不太爽，真的可以试试 Starlight。5 分钟搭个雏形，半小时就能上线 production-ready 的文档站，这效率提升可不是一点半点。

开源地址：https://github.com/withastro/starlight