定制与高级功能

概述

基础搭建完成后，你可以扩展文档站的功能：自定义主题、交互组件和高级特性。本节介绍常见的定制化场景。

问答

Q：如何自定义主题和颜色？

A：Starlight 使用 CSS 自定义属性进行主题定制。创建 src/styles/custom.css：

:root {
  --sl-color-accent-low: #1e1b4b;
  --sl-color-accent: #6366f1;
  --sl-color-accent-high: #c7d2fe;
  --sl-color-white: #ffffff;
  --sl-color-gray-1: #e5e7eb;
  --sl-color-gray-2: #9ca3af;
  --sl-color-gray-3: #6b7280;
  --sl-color-gray-4: #374151;
  --sl-color-gray-5: #1f2937;
  --sl-color-gray-6: #111827;
  --sl-color-black: #030712;
}

然后在 astro.config.mjs 中引用：

starlight({
  customCss: ['./src/styles/custom.css'],
})

Starlight 同时支持亮色和暗色模式。上述自定义属性对两种模式都生效；使用 :root[data-theme='light'] 和 :root[data-theme='dark'] 选择器进行模式特定覆盖。

Q：可以在文档中添加交互组件吗？

A：可以。Starlight 基于 Astro 构建，支持任何框架的组件：

安装 UI 框架：

npm install @astrojs/react react react-dom

在 astro.config.mjs 中配置集成：

import react from '@astrojs/react';

export default defineConfig({
  integrations: [starlight({ /* ... */ }), react()],
});

创建组件（如 src/components/ApiExplorer.astro）：

---
const { endpoint } = Astro.props;
---
<div class="api-explorer">
  <h3>试一试：{endpoint}</h3>
  <button id="try-btn">发送请求</button>
  <pre id="response"></pre>
  <script>
    document.getElementById('try-btn')?.addEventListener('click', async () => {
      const res = await fetch('/api/test');
      const data = await res.json();
      document.getElementById('response')!.textContent = JSON.stringify(data, null, 2);
    });
  </script>
</div>

在 MDX 页面中使用：

import ApiExplorer from '../../components/ApiExplorer.astro';

# API 参考

<ApiExplorer endpoint="/api/devices" />

Q：如何为不同语言或平台添加标签页？

A：Starlight 内置标签页组件：

import { Tabs, TabItem } from '@astrojs/starlight/components';

<Tabs>
  <TabItem label="npm">
    ```bash
    npm install my-package
    ```
  </TabItem>
  <TabItem label="yarn">
    ```bash
    yarn add my-package
    ```
  </TabItem>
  <TabItem label="pnpm">
    ```bash
    pnpm add my-package
    ```
  </TabItem>
</Tabs>

相同标签名的标签页在页面内同步——如果用户在一个区域选择了”yarn”，所有标签组都会切换到”yarn”。

Q：如何添加自定义 404 页面？

A：创建 src/content/docs/404.md：

---
title: "404"
template: splash
---

你访问的页面不存在。

[返回首页](/)

Q：如何添加打印友好的样式表？

A：在自定义样式表中添加打印专用 CSS：

@media print {
  .sl-sidebar,
  .sl-header,
  .starlight-toc,
  .sl-flex {
    display: none !important;
  }

  .main-frame {
    padding: 0 !important;
  }

  body {
    font-size: 12pt;
    line-height: 1.5;
  }

  pre {
    border: 1px solid #ccc;
    page-break-inside: avoid;
  }
}

用户可以使用浏览器的打印功能（Ctrl+P）获取任何页面的干净可打印版本。

Q：有哪些实用的 Starlight 插件和扩展？

A：Starlight 生态包括多个实用扩展：

插件	描述
starlight-links-validator	构建时验证所有内部链接
starlight-openapi	从 OpenAPI 规范生成 API 参考
starlight-blog	为文档站添加博客板块
starlight-image-zoom	点击图片放大查看
starlight-package-managers	多包管理器代码片段

安装任意插件：

npm install starlight-links-validator

在 astro.config.mjs 中配置：

import starlightLinksValidator from 'starlight-links-validator';

export default defineConfig({
  integrations: [
    starlight({
      plugins: [starlightLinksValidator()],
    }),
  ],
});

总结

你现在已经掌握了构建专业文档站的完整工具集：

框架：Astro + Starlight，快速、SEO 友好的静态文档
内容：Markdown + frontmatter，Content Collections 保障类型安全
多语言：内置 i18n 和语言路由
部署：Vercel、GitHub Pages 或 Cloudflare Pages 免费托管
搜索：Pagefind 本地零配置搜索
自动化：GitHub Actions CI/CD，内容迁移脚本
定制：主题、交互组件和插件

从小处开始，尽早发布，持续迭代。你的文档将与产品一起成长。

正在开发商业 IoT 产品？

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

联系我们 →