Starlight 0.32 | Astro 框架

Starlight 0.32 已发布！在向 v1 版本迈进的过程中，让我们一起来看看有哪些新功能。

🧘 我们一直在努力让 Starlight 更具可扩展性。以下是我们最新的、更灵活的流程

路由数据中间件
插件的新 i18n API
更新的插件钩子
多站点搜索支持

要升级现有的 Starlight 站点，请使用自动化的 @astrojs/upgrade CLI 工具。这将更新 Starlight、Astro 和您正在使用的任何其他集成。

npx @astrojs/upgrade

一种新的路由数据范式

Starlight 的组件覆盖系统允许用户使用自己的组件来自定义网站的外观。这对于扩展 Starlight 的 UI 非常有用，但随着时间的推移，我们发现了一种模式：人们也使用覆盖来修改组件数据，同时仍然重用 Starlight 的内置组件。

为了简化此用例，v0.32 引入了**一种新的路由中间件系统**，该系统提供对 Starlight 数据模型的完全访问，而无需覆盖任何组件。这对于插件特别有用，因为它避免了多个插件尝试覆盖同一组件的常见冲突。

与 Astro 的中间件系统类似，路由中间件会在每次 Starlight 页面渲染时被调用，让您有机会在数据渲染之前对其进行修改。这是一种强大的方式，可以实现仅通过配置目前无法实现的自定义逻辑。

在以下示例中，我们尝试通过在每个页面标题末尾添加感叹号来使我们的文档更令人兴奋！！！

import { defineRouteMiddleware } from '@astrojs/starlight/route-data';

export const onRequest = defineRouteMiddleware((context) => {
  // Get the content collection entry for this page.
  const { entry } = context.locals.starlightRoute;
  // Update the title to add exclamation marks.
  entry.data.title = entry.data.title + '!!!';
});

有关如何编写路由中间件的完整详细信息，请参阅“路由数据”指南。

破坏性变更

为了更好地支持路由中间件，我们更新了 Starlight 默认组件接收路由数据的方式。

此前，所有 Starlight 的模板组件，包括用户或插件覆盖，都可以通过 Astro.props 访问当前路由的数据对象。现在，此数据改为通过 Astro.locals.starlightRoute 提供。

有关如何迁移到此新方法的完整详细信息，请参阅Starlight 更新日志。

插件的新 i18n API

此版本使插件能够完全访问 Starlight 强大且内置的国际化系统。

插件现在可以在 config:setup 钩子中调用useTranslations() 来访问 Starlight 的任何 UI 字符串。这为本地化日志、在 Markdown 插件中使用翻译等提供了可能性。

此示例插件会记录 Starlight 默认的“由 Starlight 构建”文本字符串，并在可用时使用与用户区域设置匹配的翻译。

export default {
  name: 'localizedPlugin',
  hooks: {
    'config:setup'({ useTranslations, logger }) {
      // Detect the current user’s preferred locale.
      const userLocale = Intl.DateTimeFormat().resolvedOptions().locale;
      // Get a `t()` function for the locale.
      const t = useTranslations(userLocale);
      // Log the localized string.
      logger.info(t('builtWithStarlight.label'));
    },
  },
};

更新的插件钩子

作为支持插件中使用翻译的重构的一部分，我们已将旧的 setup 钩子拆分为两个：i18n:setup 和config:setup。setup 钩子的使用已被弃用，插件应迁移到使用 config:setup。

  export default {
    name: 'starlight-plugin',
    hooks: {
      'setup'({ config }) {
      'config:setup'({ config }) {
        // Your plugin configuration setup code
      },
    },
  };

使用 injectTranslations() 工具的插件需要将其移至专用的 i18n:setup 钩子。

  export default {
    name: 'plugin-with-translations',
    hooks: {
      'config:setup'({ injectTranslations }) {
      'i18n:setup'({ injectTranslations }) {
        injectTranslations({
          en: { 'myPlugin.doThing': 'Do the thing' },
          fr: { 'myPlugin.doThing': 'Faire le truc' },
        });
      },
    },
  };

多站点搜索支持

Starlight 使用 Pagefind 开箱即用地提供站点搜索。此版本公开了 Pagefind 的多站点搜索配置，因此您可以支持跨多个站点的搜索。

例如，如果您有一个在 example.com 上的主站点已用 Pagefind 索引，并且您的 Starlight 站点部署到 docs.example.com 子域名，您可以使用 mergeIndex 配置选项在您的文档中显示来自主站点的搜索结果。

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
  site: 'https://docs.example.com/',
  integrations: [
    starlight({
      title: 'Docs with multisite search',
      pagefind: {
        mergeIndex: [{ bundlePath: 'https://example.com/pagefind' }],
      },
    }),
  ],
});

有关可用配置选项的完整详细信息，请参阅 Pagefind 的“搜索多个站点”指南。

错误修复及更多内容

一如既往，自 v0.31 版本发布以来，我们也一直在努力修复问题。有关所有详细信息，包括详细的迁移指南，请参阅Starlight 更新日志。

鸣谢

感谢所有为此版本贡献 PR 和评论的人，包括 HiDeoo、Emilien Guilmineau、trueberryless、Sarah Rainsberger、Lorenzo Lewis 和 Yan Thomas。

我们期待看到您使用 Starlight 0.32 构建的作品！如果您有任何问题、意见或只是想打个招呼，请访问 Astro Discord。