Starlight 四月更新

作者
Chris Swithinbank

🌸 周围繁花盛开，Starlight 也在成长。让我们一起来看看有什么新功能吧！

我们一直在按路线图推进，争取在今年晚些时候发布 v1 版本。以下是我们最新版本的一些亮点：

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

npx @astrojs/upgrade

Starlight v0.34 新增了内置支持，可自动在 Markdown、MDX 和 Markdoc 内容的标题旁边渲染可点击的锚点链接。

A subheading in the Starlight docs showing a pointer cursor hovering over an anchor link icon.

我们基于 Amber Wilson 的可访问性研究，设计了一种旨在对所有用户都有帮助的锚点链接方法。

Starlight 在 HTML 输出中将链接元素放置在标题下方，并自动从您的 Markdown 内容生成一个可访问的标签。例如，以下 Markdown 内容：

## Get started

将生成如下所示的 HTML：

<h2 id="get-started">Get started</h2>
<a href="#get-started">Section titled “Get started”</a>

这确保了文档结构中的标题不会被锚点链接弄得杂乱，并且链接本身仍然为辅助技术提供了清晰的标签。我们已在 Astro 文档中使用了这种方法一段时间，现在很高兴能将其提供给所有使用 Starlight 构建的网站！

支持 Tailwind v4

自首次发布后不久，Starlight 就通过自定义 Tailwind 插件支持使用 Tailwind CSS 编写样式。现在，我们已更新支持以兼容 Tailwind v4！

Tailwind v4 带来了一些重大变化。现在，支持通过 Vite 插件提供，并且配置已从 JS 模块移至 CSS 文件。Starlight 的 Tailwind 兼容样式现在必须直接导入到您的 CSS 中，并使用 @theme 指令进行自定义。

src/styles/global.css
/* Include the "starlight" layer alongside Tailwind’s default layers. */
@layer base, starlight, theme, components, utilities;


/* Import Starlight’s compatibility styles. */
@import '@astrojs/starlight-tailwind';
@import 'tailwindcss/theme.css' layer(theme);
@import 'tailwindcss/utilities.css' layer(utilities);


@theme {
  /* Configure Starlight theme variables. */
}

有关更新的详细指导，请参阅 @astrojs/starlight-tailwind 变更日志。您可能还需要准备好 官方 Tailwind v4 升级指南 和 Starlight 的 Tailwind 设置指南。

CSS 层叠层

Starlight 用户能够轻松自定义其网站非常重要。过去，Starlight 的内置样式与用户 CSS 之间的冲突使得自定义体验不如预期流畅。

/* Starlight built-in styles (simplified) */
:not(h1, h2, h3, h4, h5, h6) + h2 {
  margin-top: 1.5em;
}


/* User styles */
h2 {
  margin-top: 1em; /* ❌ Doesn’t apply because `h2` is a lower specificity! */
}

Starlight v0.34 通过将所有内置样式移动到一个专用的 starlight CSS 层叠层中来解决冲突。这意味着 用户样式将始终优先 于默认样式，我们可以告别特异性冲突了。👋

/* Starlight built-in styles (simplified) */
@layer starlight.content {
  :not(h1, h2, h3, h4, h5, h6) + h2 {
    margin-top: 1.5em;
  }
}


/* User styles */
h2 {
  margin-top: 1em; /* ✅ Applies because it’s in the top layer! */
}

这一变化还意味着您可以享受使用 @layer 组织您自己的 CSS 的好处，而不会被 Starlight 的样式始终覆盖。

在 Starlight 的“CSS & 样式”指南中了解更多关于使用层叠层的信息。

改进的 <head> API

在 Starlight v0.33 中，我们在路由数据对象中添加了一个新的 head 属性。这使得您可以在 路由中间件 中完全控制 Starlight 的 <head> 标签，包括对插件的支持，让您更轻松地添加标签和过滤默认标签。

例如，此中间件使用 Railway 的演示 Open Graph 图像 API 为每个 Starlight 页面添加 og:image 元标签。

src/routeData.ts
import { defineRouteMiddleware } from '@astrojs/starlight/route-data';


export const onRequest = defineRouteMiddleware((context) => {
  const { entry, head } = context.locals.starlightRoute;


  // Create an Open Graph image URL using the current page’s title.
  const ogImageUrl = new URL(
    'https://og.railway.com/api/image?fileType=png&layoutName=simple',
  );
  ogImageUrl.searchParams.set('text', entry.data.title);


  // Add a `<meta property="og:image">` tag to the current page’s `<head>`.
  head.push({
    tag: 'meta',
    attrs: { property: 'og:image', content: ogImageUrl.href },
  });
});

错误修复及更多内容

一如既往，我们也在致力于修复问题并扩展现有功能。有关所有详细信息，包括破坏性更改的迁移指南，请参阅 Starlight 变更日志。

鸣谢

感谢所有通过 PR 和评论为我们近期版本做出贡献的人，包括 HiDeoo、Dhruv Bhanushali、Hippo、mayank99、Mark Gaze、Matthew Justice、Ariel K、techfg、jsparkdev、trueberryless、Juan Diaz、dragomano、Armand Philippot、Ayo Ayco、Oluwatobi Sofela、liruifengv、Lars Kappert、Emilien Guilmineau、Florian Lefebvre、Emanuele Stoppa、Ervins Strauhmanis、Pejyuu 和 Sarah Rainsberger。

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