Starlight 0.28

作者
Chris Swithinbank
HiDeoo

Starlight v0.28 现已发布！Astro 官方一体化文档站点构建器的最新版本刚刚发布。让我们来看看近期 Starlight 版本的一些亮点。

要升级现有项目，请从终端运行自动化 @astrojs/upgrade CLI

npx @astrojs/upgrade

升级的本地化支持

Starlight 从一开始就支持多语言，v0.28 将这一功能提升到了新的水平。Starlight 内置的本地化系统现在由一流的 i18next 库提供支持，可在您站点的任何地方使用。

从任何 Astro 组件中使用新的 Astro.locals.t() 方法来渲染 Starlight 内置的 UI 标签或您自己的自定义字符串，包括支持插值和复数形式

<p>{Astro.locals.t('404.text')}</p>
<!-- <p>Page not found. Check the URL or try using the search bar.</p> -->


<p>{Astro.locals.t('componentCount', { count: 99 })}</p>
<!-- <p>I have 99 components 🎉</p> -->

此次更新使 Starlight 成为开箱即用的国际化功能的无与伦比的选择。今天就从单一语言开始，并充满信心地构建，因为您知道在需要时随时可以翻译您的文档。

按需渲染支持

自 v0.27 起，Starlight 支持完全动态的服务器端渲染（如果需要）。在 Starlight 选项中将 prerender: false 设置为禁用页面静态生成并切换到 Astro 的按需渲染模式

astro.config.mjs
starlight({
  title: 'Docs on Demand',
  prerender: false,
}),

这解锁了用户身份验证和个性化等功能，使 Starlight 更加灵活。查看我们的 按需文档演示 以了解一些实际可能性。感谢 Fryuni 实现了此功能！

记住您偏好的选项卡

Starlight 的 <Tabs> 组件现在支持在页面导航时记住用户偏好。这使得您的读者可以一次性选择他们偏好的包管理器或操作系统等选项，并在文档的其他地方看到这些偏好得到体现。要启用此功能，请将匹配的 syncKey 属性添加到您的 <Tabs>

src/content/docs/example.mdx
import { Tabs, TabItem } from '@astrojs/starlight/components';


<Tabs syncKey="package-manager">
  <TabItem label="npm">npm install @astrojs/starlight</TabItem>
  <TabItem label="pnpm">pnpm add @astrojs/starlight</TabItem>
  <TabItem label="yarn">yarn add @astrojs/starlight</TabItem>
</Tabs>

Starlight 基于经过验证的 Web 技术构建，提供简单的静态 HTML，并使用最少的 JavaScript 以实现最佳性能。我们收到了用户反馈，全页面导航可能会造成干扰，因为每次页面加载时侧边栏状态都会丢失。

从 v0.26 开始，Starlight 借助一个轻量级自定义元素，在导航时保留并恢复侧边栏状态，从而提供更流畅的浏览体验。这是一种渐进式增强——如果用户的设备上没有 JavaScript，侧边栏会照常渲染，确保所有用户都能获得稳定的体验。

更简单的侧边栏配置

在早期版本的 Starlight 中，设置您的 侧边栏配置 可能会有点冗长。

astro.config.mjs
starlight({
  title: 'Old Skool Starlight',
  sidebar: [
    { label: 'Page one', link: '/one' },
    { label: 'Page two', link: '/two' },
    // ...
  ],
}),

使用 Starlight v0.25，内部链接的配置变得简单得多。您现在只需指定要链接页面的 slug，Starlight 将自动使用页面标题作为链接标签。

astro.config.mjs
starlight({
  title: 'Cutting Edge Starlight',
  sidebar: [
    'one', 'two', // ...
  ],
}),

此外，使用这种语法，您可以免费获得链接检查——不再有意外的 404 错误！感谢 Lorenzo 添加了此功能。

焕然一新的文档

我们也一直在努力更新我们自己的文档！我们彻底修改了 Starlight 内置组件的文档。现在每个组件都有一个专门的页面，包括常见用法示例和完整的 prop 参考。

访问新的 “使用组件”指南，探索可用组件。

当然，如果没有翻译，这些就不是 Astro 文档。向 @dreyfus92、@jsparkdev、@dragomano、@liruifengv、@zhoushengdao、@Nin3lee、@casungo、@at-the-vr 和 @thomasbnt 致敬，感谢他们让我们的西班牙语、韩语、俄语、简体中文、意大利语、印地语和法语文档保持更新！

为勇于探索者准备的 Markdoc 预设

对 Markdoc 感兴趣的 Starlight 用户可以使用新的 @astrojs/starlight-markdoc 包，快速配置所有 Starlight 内置组件以在 Markdoc 文件中使用。有关更多详细信息，请参阅我们的 Markdoc 设置指南。

立即试用 Starlight！

看到 Cloudflare、Crowdin、StackBlitz、Sentry、Font Awesome 和 SST 等公司在构建文档时采用 Starlight，我们感到非常兴奋。加入他们和 FreeCodeCamp、RealWorld Apps、Biome、Jimp、Shepherd、Bloc 和 Knip 等开源项目——仅举几例！——今天就开始使用吧。

访问 Starlight 文档 或直接从终端创建一个新站点

npm create astro@latest -- --template starlight