Starlight April Update

🌸 Blossoms all around me and Starlight is growing too. Let’s take a look and see what’s new!

We’ve been working through our roadmap towards releasing v1 later this year. Here are some highlights from our latest releases:

Built-in heading anchor links
Tailwind v4 support
CSS cascade layers
Improved <head> APIs

To upgrade an existing Starlight site, use the automated @astrojs/upgrade CLI tool. This will update Starlight, Astro, and any other integrations you are using:

npx @astrojs/upgrade

Heading anchor links

Starlight v0.34 adds built-in support for automatically rendering clickable anchor links next to headings in your Markdown, MDX, and Markdoc content.

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

We built on accessibility research by Amber Wilson to design an anchor link approach that aims to be helpful for all users.

Starlight places the link element below the heading in the HTML output and automatically generates an accessible label from your Markdown content. For example, the following Markdown:

## Get started

will generate HTML a bit like this:

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

This ensures that headings in the document structure are not cluttered by anchor links and that the links themselves still have a clear label available for assistive technology. We’ve been using this approach in the Astro docs for some time now and are excited to make it available to all sites built with Starlight!

Tailwind v4 support

Starlight has supported authoring styles with Tailwind CSS since shortly after our first release via a custom Tailwind plugin. We’ve now updated our support for compatibility with Tailwind v4!

Tailwind v4 comes with some big changes. Support is now provided via a Vite plugin and configuration has moved to a CSS file instead of a JS module. Starlight’s Tailwind compatibility styles must now be imported directly in your CSS and customized using the @theme directive:

/* 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. */
}

For detailed guidance on updating see the @astrojs/starlight-tailwind changelog. You might also want to keep the official Tailwind v4 upgrade guide and Starlight’s Tailwind set-up guide handy.

CSS cascade layers

It’s important that Starlight users can easily customize their sites. Historically, clashes between Starlight’s built-in styles and a user’s CSS made the customization experience less smooth than it could have been:

/* 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 solves conflicts by moving all built-in styles into a dedicated starlight CSS cascade layer. This means that user styles will always take precedence over default styles and we can wave goodbye to specificity battles. 👋

/* 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! */
}

This change also means you can enjoy the benefits of using @layer to organize your own CSS without Starlight’s styles always overriding it.

Learn more about using cascade layers in Starlight’s “CSS & Styling” guide.

Improved <head> APIs

In Starlight v0.33, we added a new head property to our route data object. This unlocks full control over Starlight’s <head> tags in route middleware, including for plugins, allowing you to add tags and filter default tags more easily.

For example, this middleware uses Railway’s demo Open Graph image API to add og:image meta tags to every Starlight page:

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 },
  });
});

Bug fixes and more

As always, we’ve also been working to fix issues and extend existing features. See the Starlight changelog for all the details including migration guidance for breaking changes.

Thanks

Thanks to everyone who contributed to our recent releases with PRs and reviews, including 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, and Sarah Rainsberger.

We look forward to seeing what you build with Starlight! If you have questions, comments, or just want to say hi, drop by the Astro Discord.

Previously…

Starlight 0.32

The latest Starlight features unlock new possibilities on our path to v1. Let’s meet route middleware, plugin i18n APIs, and multisite search.

Starlight 0.28

Meet the latest Starlight features: i18next, on-demand rendering support, sidebar persistence, smart tabs, and more for your docs.