搜索、自定义域名与数据分析

概述

文档站需要搜索功能、数据分析以及可选的 Google Analytics 集成来追踪使用情况并改进内容。本节介绍如何添加这些核心功能。

问答

Q：Starlight 中的搜索如何工作？

A：Starlight 集成了 Pagefind——一个完全静态的本地搜索引擎。零配置即可使用：

Pagefind 在构建过程中索引所有内容
搜索 UI 自动添加到站点头部
用户可以跨所有页面搜索并获得即时结果

搜索索引在构建时生成并作为静态文件提供——不需要外部 API，不需要服务器。

要自定义搜索行为，可以添加页面级元数据：

---
title: API 参考
pagefind:
  weight: 2          # 在搜索结果中提升此页面权重
  filter:
    type: reference   # 启用按内容类型筛选
---

Q：可以用 Algolia DocSearch 替代 Pagefind 吗？

A：可以，如果你需要更高级的功能如分析、纠错或同义词支持：

申请 Algolia DocSearch（开源项目免费）
安装 Starlight Algolia 插件：

npm install starlight-algolia

在 astro.config.mjs 中配置：

import starlightAlgolia from 'starlight-algolia';

starlight({
  search: starlightAlgolia({
    appId: 'YOUR_APP_ID',
    apiKey: 'YOUR_SEARCH_API_KEY',
    indexName: 'your_index_name',
  }),
})

对于大多数文档站，内置的 Pagefind 搜索已经足够且更易于维护。

Q：如何添加 Google Analytics？

A：通过 Starlight 的 head 配置添加 Google Analytics 追踪脚本：

const gaId = process.env.PUBLIC_GA_ID || 'G-XXXXXXXXXX';

export default defineConfig({
  integrations: [
    starlight({
      head: [
        {
          tag: 'script',
          attrs: { async: true, src: `https://www.googletagmanager.com/gtag/js?id=${gaId}` },
        },
        {
          tag: 'script',
          content: `window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', '${gaId}');`,
        },
      ],
    }),
  ],
});

将 GA ID 存储为环境变量（PUBLIC_GA_ID）以确保安全和按环境配置。

Q：如何添加自定义 favicon 和 logo？

A：将 favicon 文件放在 public/ 目录中：

public/
├── favicon.svg      # SVG favicon（推荐）
├── favicon.ico      # 旧版浏览器降级
└── logo.svg         # 头部 logo

Starlight 自动从 public 目录获取 favicon.svg。自定义头部 logo：

starlight({
  logo: {
    src: './src/assets/logo.svg',
    alt: '我的公司 Logo',
  },
})

Q：如何提升文档站的 SEO？

A：Starlight 开箱即提供多项 SEO 功能：

站点地图：自动生成 sitemap-index.xml
Meta 标签：frontmatter 中的标题和描述用于 SEO
Open Graph：自动生成社交媒体预览卡片
结构化数据：面包屑 schema 供搜索引擎使用

额外 SEO 建议：

为每个页面编写描述性的 frontmatter description
使用语义化标题层级（##、###、####）
为所有图片添加 alt 文本
将站点地图提交到 Google Search Console
在 astro.config.mjs 中将 site 设置为生产环境 URL

Q：如何添加社交链接和编辑按钮？

A：在 Starlight 配置中设置社交链接和编辑按钮：

starlight({
  social: [
    { icon: 'github', label: 'GitHub', href: 'https://github.com/yourcompany/yourproject' },
    { icon: 'twitter', label: 'Twitter', href: 'https://twitter.com/yourcompany' },
    { icon: 'discord', label: 'Discord', href: 'https://discord.gg/yourinvite' },
  ],
  editLink: {
    baseUrl: 'https://github.com/yourcompany/yourproject/edit/main/',
  },
})

编辑链接会在每个页面添加”编辑此页”按钮，鼓励社区贡献。

正在开发商业 IoT 产品？

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

联系我们 →