[ci] release (#3124)@astrojs/starlight@0.34.0@astrojs/starlight-tailwind@4.0.0@astrojs/starlight-markdoc@0.4.0

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>

18 files changed, 283 insertions, 293 deletions

diff --git a/.changeset/angry-spies-worry.md b/.changeset/angry-spies-worry.md
deleted file mode 100644
index 2934fdc2..00000000
--- a/.changeset/angry-spies-worry.md
+++ /dev/null
@@ -1,9 +0,0 @@
----
-'@astrojs/starlight': minor
----
-
-Groups all of Starlight's CSS declarations into a single `starlight` [cascade layer](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Styling_basics/Cascade_layers).
-
-This change allows for easier customization of Starlight's CSS as any custom unlayered CSS will override the default styles. If you are using cascade layers in your custom CSS, you can use the [`@layer`](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer) CSS at-rule to define the order of precedence for different layers including the ones used by Starlight.
-
-We recommend checking your site’s appearance when upgrading to make sure there are no style regressions caused by this change.
diff --git a/.changeset/chilly-dolphins-clap.md b/.changeset/chilly-dolphins-clap.md
deleted file mode 100644
index 35418ec5..00000000
--- a/.changeset/chilly-dolphins-clap.md
+++ /dev/null
@@ -1,24 +0,0 @@
----
-'@astrojs/starlight': minor
----
-
-Removes default `attrs` and `content` values from head entries parsed using Starlight’s schema.
-
-Previously when adding `head` metadata via frontmatter or user config, Starlight would automatically add values for `attrs` and `content` if not provided. Now, these properties are left `undefined`.
-
-This makes it simpler to add tags in route middleware for example as you no longer need to provide empty values for `attrs` and `content`:
-
-```diff
-head.push({
-  tag: 'style',
-  content: 'div { color: red }'
-- attrs: {},
-});
-head.push({
-  tag: 'link',
-- content: ''
-  attrs: { rel: 'me', href: 'https://example.com' },
-});
-```
-
-This is mostly an internal API but if you are overriding Starlight’s `Head` component or processing head entries in some way, you may wish to double check your handling of `Astro.locals.starlightRoute.head` is compatible with `attrs` and `content` potentially being `undefined`.
diff --git a/.changeset/great-eels-carry.md b/.changeset/great-eels-carry.md
deleted file mode 100644
index 6883ac18..00000000
--- a/.changeset/great-eels-carry.md
+++ /dev/null
@@ -1,11 +0,0 @@
----
-'@astrojs/starlight-tailwind': major
----
-
-⚠️ **BREAKING CHANGE:** The minimum supported version of Starlight is now 0.34.0
-
-Please use the `@astrojs/upgrade` command to upgrade your project:
-
-```sh
-npx @astrojs/upgrade
-```
diff --git a/.changeset/late-onions-sparkle.md b/.changeset/late-onions-sparkle.md
deleted file mode 100644
index a70a0ef0..00000000
--- a/.changeset/late-onions-sparkle.md
+++ /dev/null
@@ -1,26 +0,0 @@
----
-'@astrojs/starlight': minor
----
-
-Adds support for generating clickable anchor links for headings.
-
-By default, Starlight now renders an anchor link beside headings in Markdown and MDX content. A new `<AnchorHeading>` component is available to achieve the same thing in custom pages built using `<StarlightPage>`.
-
-If you want to disable this new Markdown processing set the `markdown.headingLinks` option in your Starlight config to `false`:
-
-```js
-starlight({
-  title: 'My docs',
-  markdown: {
-    headingLinks: false,
-  },
-}),
-```
-
-⚠️ **BREAKING CHANGE:** The minimum supported version of Astro is now v5.5.0.
-
-Please update Starlight and Astro together:
-
-```sh
-npx @astrojs/upgrade
-```
diff --git a/.changeset/old-toes-flow.md b/.changeset/old-toes-flow.md
deleted file mode 100644
index 6f7c7702..00000000
--- a/.changeset/old-toes-flow.md
+++ /dev/null
@@ -1,138 +0,0 @@
----
-'@astrojs/starlight-tailwind': major
----
-
-Adds support for Tailwind v4, drops support for Tailwind v3.
-
-⚠️ **BREAKING CHANGE:** Tailwind v3 is no longer supported. Tailwind v4 support in Astro is now provided using a Vite plugin and the Astro Tailwind integration is no longer required.
-
-1. **Remove the Astro Tailwind integration.** The Astro Tailwind integration is no longer required with Tailwind v4.
-
-   ```diff
-    // astro.config.mjs
-    import { defineConfig } from "astro/config";
-    import starlight from "@astrojs/starlight";
-   -import tailwind from "@astrojs/tailwind";
-
-    export default defineConfig({
-      integrations: [
-        starlight({
-          title: "Docs with Tailwind",
-          customCss: ["./src/tailwind.css"],
-        }),
-   -    tailwind({ applyBaseStyles: false }),
-      ],
-    });
-   ```
-
-1. **Install Tailwind v4.** Install the latest version of the `tailwindcss` and `@tailwindcss/vite` packages.
-
-   Use the `astro add tailwind` command to install and configure both packages:
-
-   ```sh
-   npx astro add tailwind
-   ```
-  
-1. **Update Tailwind base styles.** Tailwind CSS base styles needs to be updated for Tailwind v4 and also to use Starlight Tailwind CSS.
-
-   ```diff
-   /* src/tailwind.css */
-   -@tailwind base;
-   -@tailwind components;
-   -@tailwind utilities;
-   +@layer base, starlight, theme, components, utilities;
-   +
-   +@import '@astrojs/starlight-tailwind';
-   +@import 'tailwindcss/theme.css' layer(theme);
-   +@import 'tailwindcss/utilities.css' layer(utilities);
-   +
-   +@theme {
-   +	/*
-   +	Configure your Tailwind theme that will be used by Starlight.
-   +	https://starlight.astro.build/guides/css-and-tailwind/#styling-starlight-with-tailwind
-   +	*/
-   +}
-   +
-   +/*
-   +Add additional Tailwind styles to this file:
-   +https://tailwindcss.com/docs/adding-custom-styles#using-custom-css
-   +*/
-   ```
-
-1. **Update Tailwind customizations.** If you previously [customized your Tailwind theme configuration](https://starlight.astro.build/guides/css-and-tailwind/#styling-starlight-with-tailwind) in the `tailwind.config.mjs` file, such customizations are now defined through CSS using the `@theme` block in your Tailwind base styles.
-
-   1. Locate existing customizations in your `tailwind.config.mjs` file. The following example defines customizations for the accent colors, gray scale, and font families used by Starlight:
-
-      ```js
-      // tailwind.config.mjs
-      import starlightPlugin from '@astrojs/starlight-tailwind';
-      import colors from 'tailwindcss/colors';
-      
-      /** @type {import('tailwindcss').Config} */
-      export default {
-        content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
-        theme: {
-          extend: {
-            colors: {
-              // Custom accent colors.
-              accent: colors.fuchsia,
-              // Custom gray scale.
-              gray: colors.slate,
-            },
-            fontFamily: {
-              // Custom text font.
-              sans: ['"Atkinson Hyperlegible"'],
-              // Custom code font.
-              mono: ['"IBM Plex Mono"'],
-            },
-          },
-        },
-        plugins: [starlightPlugin()],
-      };
-      ```
-
-   1. The above customizations can be migrated to the new `@theme` block in the file containing your Tailwind base styles as follows:
-
-      ```css
-      /* src/tailwind.css */
-      @layer base, starlight, theme, components, utilities;
-      
-      @import '@astrojs/starlight-tailwind';
-      @import 'tailwindcss/theme.css' layer(theme);
-      @import 'tailwindcss/utilities.css' layer(utilities);
-      
-      @theme {
-      	/* Custom accent colors. */
-      	--color-accent-50: var(--color-fuchsia-50);
-      	--color-accent-100: var(--color-fuchsia-100);
-      	--color-accent-200: var(--color-fuchsia-200);
-      	--color-accent-300: var(--color-fuchsia-300);
-      	--color-accent-400: var(--color-fuchsia-400);
-      	--color-accent-500: var(--color-fuchsia-500);
-      	--color-accent-600: var(--color-fuchsia-600);
-      	--color-accent-700: var(--color-fuchsia-700);
-      	--color-accent-800: var(--color-fuchsia-800);
-      	--color-accent-900: var(--color-fuchsia-900);
-      	--color-accent-950: var(--color-fuchsia-950);
-      	/* Custom gray scale. */
-      	--color-gray-50: var(--color-slate-50);
-      	--color-gray-100: var(--color-slate-100);
-      	--color-gray-200: var(--color-slate-200);
-      	--color-gray-300: var(--color-slate-300);
-      	--color-gray-400: var(--color-slate-400);
-      	--color-gray-500: var(--color-slate-500);
-      	--color-gray-600: var(--color-slate-600);
-      	--color-gray-700: var(--color-slate-700);
-      	--color-gray-800: var(--color-slate-800);
-      	--color-gray-900: var(--color-slate-900);
-      	--color-gray-950: var(--color-slate-950);
-       /* Custom text font. */
-       --font-sans: 'Atkinson Hyperlegible';
-       /* Custom code font. */
-       --font-mono: 'IBM Plex Mono';
-      }
-      ```
-
-We recommend checking your site’s appearance when upgrading to make sure there are no style regressions caused by this change.
-
-For full details about upgrading from Tailwind v3 to v4, see the [official upgrade guide](https://tailwindcss.com/docs/upgrade-guide).
diff --git a/.changeset/quick-items-dream.md b/.changeset/quick-items-dream.md
deleted file mode 100644
index cb127773..00000000
--- a/.changeset/quick-items-dream.md
+++ /dev/null
@@ -1,24 +0,0 @@
----
-'@astrojs/starlight-markdoc': minor
----
-
-Adds support for generating clickable anchor links for headings.
-
-By default, the Starlight Markdoc preset now includes a default `heading` node, which renders an anchor link beside headings in your Markdoc content.
-
-If you want to disable this new feature, pass `headingLinks: false` in your Markdoc config:
-
-```js
-export default defineMarkdocConfig({
-  // Disable the default heading anchor link support
-  extends: [starlightMarkdoc({ headingLinks: false })],
-});
-```
-
-⚠️ **BREAKING CHANGE:** The minimum supported peer version of Starlight is now v0.34.0.
-
-Please update Starlight and the Starlight Markdoc preset together:
-
-```sh
-npx @astrojs/upgrade
-```
diff --git a/.changeset/shaggy-games-retire.md b/.changeset/shaggy-games-retire.md
deleted file mode 100644
index b6e7b5c1..00000000
--- a/.changeset/shaggy-games-retire.md
+++ /dev/null
@@ -1,43 +0,0 @@
----
-'@astrojs/starlight': minor
----
-
-Removes Shiki `css-variables` theme fallback.
-
-⚠️ **Breaking change:**
-
-Previously, Starlight used to automatically provide a fallback theme for Shiki, the default syntax highlighter built into Astro if the configured Shiki theme was not `github-dark`.
-
-This fallback was only relevant when the default Starlight code block renderer, Expressive Code, was disabled and Shiki was used. Starlight no longer provides this fallback.
-
-If you were relying on this behavior, you now manually need to update your Astro configuration to use the Shiki `css-variables` theme to match the previous behavior.
-
-```diff
-import { defineConfig } from 'astro/config';
-
-export default defineConfig({
-+ markdown: {
-+   shikiConfig: {
-+     theme: 'css-variables',
-+   },
-+ },
-});
-```
-
-Additionally, you can use [custom CSS](https://starlight.astro.build/guides/css-and-tailwind/#custom-css-styles) to control the appearance of the code blocks. Here are the previously used CSS variables for the fallback theme:
-
-```css
-:root {
-  --astro-code-foreground: var(--sl-color-white);
-  --astro-code-background: var(--sl-color-gray-6);
-  --astro-code-token-constant: var(--sl-color-blue-high);
-  --astro-code-token-string: var(--sl-color-green-high);
-  --astro-code-token-comment: var(--sl-color-gray-2);
-  --astro-code-token-keyword: var(--sl-color-purple-high);
-  --astro-code-token-parameter: var(--sl-color-red-high);
-  --astro-code-token-function: var(--sl-color-red-high);
-  --astro-code-token-string-expression: var(--sl-color-green-high);
-  --astro-code-token-punctuation: var(--sl-color-gray-2);
-  --astro-code-token-link: var(--sl-color-blue-high);
-}
-```
diff --git a/.changeset/warm-adults-wash.md b/.changeset/warm-adults-wash.md
deleted file mode 100644
index 15bf8ddb..00000000
--- a/.changeset/warm-adults-wash.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-'@astrojs/starlight': patch
----
-
-Fixes passing imported SVGs to the `frontmatter` prop of the `<StarlightPage>` component in Astro ≥5.7.0
diff --git a/examples/basics/package.json b/examples/basics/package.json
index 88cbdeee..561531b0 100644
--- a/examples/basics/package.json
+++ b/examples/basics/package.json
@@ -11,7 +11,7 @@
     "astro": "astro"
   },
   "dependencies": {
-    "@astrojs/starlight": "^0.33.2",
+    "@astrojs/starlight": "^0.34.0",
     "astro": "^5.6.1",
     "sharp": "^0.32.5"
   }
diff --git a/examples/markdoc/package.json b/examples/markdoc/package.json
index 5d9dc5c1..84d7c0ee 100644
--- a/examples/markdoc/package.json
+++ b/examples/markdoc/package.json
@@ -12,8 +12,8 @@
   },
   "dependencies": {
     "@astrojs/markdoc": "^0.13.3",
-    "@astrojs/starlight": "^0.33.2",
-    "@astrojs/starlight-markdoc": "^0.3.1",
+    "@astrojs/starlight": "^0.34.0",
+    "@astrojs/starlight-markdoc": "^0.4.0",
     "astro": "^5.6.1",
     "sharp": "^0.32.5"
   }
diff --git a/examples/tailwind/package.json b/examples/tailwind/package.json
index 90598b3c..e7f57372 100644
--- a/examples/tailwind/package.json
+++ b/examples/tailwind/package.json
@@ -11,8 +11,8 @@
     "astro": "astro"
   },
   "dependencies": {
-    "@astrojs/starlight": "^0.33.2",
-    "@astrojs/starlight-tailwind": "^3.0.1",
+    "@astrojs/starlight": "^0.34.0",
+    "@astrojs/starlight-tailwind": "^4.0.0",
     "@tailwindcss/vite": "^4.0.7",
     "astro": "^5.6.1",
     "sharp": "^0.32.5",
diff --git a/packages/markdoc/CHANGELOG.md b/packages/markdoc/CHANGELOG.md
index 98940366..340e6907 100644
--- a/packages/markdoc/CHANGELOG.md
+++ b/packages/markdoc/CHANGELOG.md
@@ -1,5 +1,30 @@
 # @astrojs/starlight-markdoc
 
+## 0.4.0
+
+### Minor Changes
+
+- [#3033](https://github.com/withastro/starlight/pull/3033) [`8c19678`](https://github.com/withastro/starlight/commit/8c19678e57c0270d3d80d4678f23a6fc287ebf12) Thanks [@delucis](https://github.com/delucis)! - Adds support for generating clickable anchor links for headings.
+
+  By default, the Starlight Markdoc preset now includes a default `heading` node, which renders an anchor link beside headings in your Markdoc content.
+
+  If you want to disable this new feature, pass `headingLinks: false` in your Markdoc config:
+
+  ```js
+  export default defineMarkdocConfig({
+    // Disable the default heading anchor link support
+    extends: [starlightMarkdoc({ headingLinks: false })],
+  });
+  ```
+
+  ⚠️ **BREAKING CHANGE:** The minimum supported peer version of Starlight is now v0.34.0.
+
+  Please update Starlight and the Starlight Markdoc preset together:
+
+  ```sh
+  npx @astrojs/upgrade
+  ```
+
 ## 0.3.1
 
 ### Patch Changes
diff --git a/packages/markdoc/package.json b/packages/markdoc/package.json
index 962d354d..1d60681d 100644
--- a/packages/markdoc/package.json
+++ b/packages/markdoc/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@astrojs/starlight-markdoc",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Markdoc preset for the Starlight documentation theme for Astro",
   "author": "Chris Swithinbank <swithinbank@gmail.com>",
   "license": "MIT",
diff --git a/packages/starlight/CHANGELOG.md b/packages/starlight/CHANGELOG.md
index 1ef73bcb..bd6a5db7 100644
--- a/packages/starlight/CHANGELOG.md
+++ b/packages/starlight/CHANGELOG.md
@@ -1,5 +1,103 @@
 # @astrojs/starlight
 
+## 0.34.0
+
+### Minor Changes
+
+- [#2322](https://github.com/withastro/starlight/pull/2322) [`f14eb0c`](https://github.com/withastro/starlight/commit/f14eb0cd7baa0391d6124379f6c5df4b9ab7cc44) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Groups all of Starlight's CSS declarations into a single `starlight` [cascade layer](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Styling_basics/Cascade_layers).
+
+  This change allows for easier customization of Starlight's CSS as any custom unlayered CSS will override the default styles. If you are using cascade layers in your custom CSS, you can use the [`@layer`](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer) CSS at-rule to define the order of precedence for different layers including the ones used by Starlight.
+
+  We recommend checking your site’s appearance when upgrading to make sure there are no style regressions caused by this change.
+
+- [#3122](https://github.com/withastro/starlight/pull/3122) [`3a087d8`](https://github.com/withastro/starlight/commit/3a087d8fbcd946336f8a0423203967e53e5678fe) Thanks [@delucis](https://github.com/delucis)! - Removes default `attrs` and `content` values from head entries parsed using Starlight’s schema.
+
+  Previously when adding `head` metadata via frontmatter or user config, Starlight would automatically add values for `attrs` and `content` if not provided. Now, these properties are left `undefined`.
+
+  This makes it simpler to add tags in route middleware for example as you no longer need to provide empty values for `attrs` and `content`:
+
+  ```diff
+  head.push({
+    tag: 'style',
+    content: 'div { color: red }'
+  - attrs: {},
+  });
+  head.push({
+    tag: 'link',
+  - content: ''
+    attrs: { rel: 'me', href: 'https://example.com' },
+  });
+  ```
+
+  This is mostly an internal API but if you are overriding Starlight’s `Head` component or processing head entries in some way, you may wish to double check your handling of `Astro.locals.starlightRoute.head` is compatible with `attrs` and `content` potentially being `undefined`.
+
+- [#3033](https://github.com/withastro/starlight/pull/3033) [`8c19678`](https://github.com/withastro/starlight/commit/8c19678e57c0270d3d80d4678f23a6fc287ebf12) Thanks [@delucis](https://github.com/delucis)! - Adds support for generating clickable anchor links for headings.
+
+  By default, Starlight now renders an anchor link beside headings in Markdown and MDX content. A new `<AnchorHeading>` component is available to achieve the same thing in custom pages built using `<StarlightPage>`.
+
+  If you want to disable this new Markdown processing set the `markdown.headingLinks` option in your Starlight config to `false`:
+
+  ```js
+  starlight({
+    title: 'My docs',
+    markdown: {
+      headingLinks: false,
+    },
+  }),
+  ```
+
+  ⚠️ **BREAKING CHANGE:** The minimum supported version of Astro is now v5.5.0.
+
+  Please update Starlight and Astro together:
+
+  ```sh
+  npx @astrojs/upgrade
+  ```
+
+- [#2322](https://github.com/withastro/starlight/pull/2322) [`f14eb0c`](https://github.com/withastro/starlight/commit/f14eb0cd7baa0391d6124379f6c5df4b9ab7cc44) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Removes Shiki `css-variables` theme fallback.
+
+  ⚠️ **BREAKING CHANGE:**
+
+  Previously, Starlight used to automatically provide a fallback theme for Shiki, the default syntax highlighter built into Astro if the configured Shiki theme was not `github-dark`.
+
+  This fallback was only relevant when the default Starlight code block renderer, Expressive Code, was disabled and Shiki was used. Starlight no longer provides this fallback.
+
+  If you were relying on this behavior, you now manually need to update your Astro configuration to use the Shiki `css-variables` theme to match the previous behavior.
+
+  ```diff
+  import { defineConfig } from 'astro/config';
+
+  export default defineConfig({
+  + markdown: {
+  +   shikiConfig: {
+  +     theme: 'css-variables',
+  +   },
+  + },
+  });
+  ```
+
+  Additionally, you can use [custom CSS](https://starlight.astro.build/guides/css-and-tailwind/#custom-css-styles) to control the appearance of the code blocks. Here are the previously used CSS variables for the fallback theme:
+
+  ```css
+  :root {
+    --astro-code-foreground: var(--sl-color-white);
+    --astro-code-background: var(--sl-color-gray-6);
+    --astro-code-token-constant: var(--sl-color-blue-high);
+    --astro-code-token-string: var(--sl-color-green-high);
+    --astro-code-token-comment: var(--sl-color-gray-2);
+    --astro-code-token-keyword: var(--sl-color-purple-high);
+    --astro-code-token-parameter: var(--sl-color-red-high);
+    --astro-code-token-function: var(--sl-color-red-high);
+    --astro-code-token-string-expression: var(--sl-color-green-high);
+    --astro-code-token-punctuation: var(--sl-color-gray-2);
+    --astro-code-token-link: var(--sl-color-blue-high);
+  }
+  ```
+
+### Patch Changes
+
+- [#3118](https://github.com/withastro/starlight/pull/3118) [`77a1104`](https://github.com/withastro/starlight/commit/77a110461dffacd1d3ee3b8934fd48b20111f3c4) Thanks [@delucis](https://github.com/delucis)! - Fixes passing imported SVGs to the `frontmatter` prop of the `<StarlightPage>` component in Astro ≥5.7.0
+
 ## 0.33.2
 
 ### Patch Changes
diff --git a/packages/starlight/package.json b/packages/starlight/package.json
index 39544e83..a46fbf18 100644
--- a/packages/starlight/package.json
+++ b/packages/starlight/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@astrojs/starlight",
-  "version": "0.33.2",
+  "version": "0.34.0",
   "description": "Build beautiful, high-performance documentation websites with Astro",
   "scripts": {
     "test": "vitest",
diff --git a/packages/tailwind/CHANGELOG.md b/packages/tailwind/CHANGELOG.md
index d8482785..c46ef5e6 100644
--- a/packages/tailwind/CHANGELOG.md
+++ b/packages/tailwind/CHANGELOG.md
@@ -1,5 +1,152 @@
 # @astrojs/starlight-tailwind
 
+## 4.0.0
+
+### Major Changes
+
+- [#2322](https://github.com/withastro/starlight/pull/2322) [`f14eb0c`](https://github.com/withastro/starlight/commit/f14eb0cd7baa0391d6124379f6c5df4b9ab7cc44) Thanks [@HiDeoo](https://github.com/HiDeoo)! - ⚠️ **BREAKING CHANGE:** The minimum supported version of Starlight is now 0.34.0
+
+  Please use the `@astrojs/upgrade` command to upgrade your project:
+
+  ```sh
+  npx @astrojs/upgrade
+  ```
+
+- [#2322](https://github.com/withastro/starlight/pull/2322) [`f14eb0c`](https://github.com/withastro/starlight/commit/f14eb0cd7baa0391d6124379f6c5df4b9ab7cc44) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Adds support for Tailwind v4, drops support for Tailwind v3.
+
+  ⚠️ **BREAKING CHANGE:** Tailwind v3 is no longer supported. Tailwind v4 support in Astro is now provided using a Vite plugin and the Astro Tailwind integration is no longer required.
+
+  1. **Remove the Astro Tailwind integration.** The Astro Tailwind integration is no longer required with Tailwind v4.
+
+     ```diff
+      // astro.config.mjs
+      import { defineConfig } from "astro/config";
+      import starlight from "@astrojs/starlight";
+     -import tailwind from "@astrojs/tailwind";
+
+      export default defineConfig({
+        integrations: [
+          starlight({
+            title: "Docs with Tailwind",
+            customCss: ["./src/tailwind.css"],
+          }),
+     -    tailwind({ applyBaseStyles: false }),
+        ],
+      });
+     ```
+
+  1. **Install Tailwind v4.** Install the latest version of the `tailwindcss` and `@tailwindcss/vite` packages.
+
+     Use the `astro add tailwind` command to install and configure both packages:
+
+     ```sh
+     npx astro add tailwind
+     ```
+
+  1. **Update Tailwind base styles.** Tailwind CSS base styles needs to be updated for Tailwind v4 and also to use Starlight Tailwind CSS.
+
+     ```diff
+     /* src/tailwind.css */
+     -@tailwind base;
+     -@tailwind components;
+     -@tailwind utilities;
+     +@layer base, starlight, theme, components, utilities;
+     +
+     +@import '@astrojs/starlight-tailwind';
+     +@import 'tailwindcss/theme.css' layer(theme);
+     +@import 'tailwindcss/utilities.css' layer(utilities);
+     +
+     +@theme {
+     +	/*
+     +	Configure your Tailwind theme that will be used by Starlight.
+     +	https://starlight.astro.build/guides/css-and-tailwind/#styling-starlight-with-tailwind
+     +	*/
+     +}
+     +
+     +/*
+     +Add additional Tailwind styles to this file:
+     +https://tailwindcss.com/docs/adding-custom-styles#using-custom-css
+     +*/
+     ```
+
+  1. **Update Tailwind customizations.** If you previously [customized your Tailwind theme configuration](https://starlight.astro.build/guides/css-and-tailwind/#styling-starlight-with-tailwind) in the `tailwind.config.mjs` file, such customizations are now defined through CSS using the `@theme` block in your Tailwind base styles.
+
+     1. Locate existing customizations in your `tailwind.config.mjs` file. The following example defines customizations for the accent colors, gray scale, and font families used by Starlight:
+
+        ```js
+        // tailwind.config.mjs
+        import starlightPlugin from '@astrojs/starlight-tailwind';
+        import colors from 'tailwindcss/colors';
+
+        /** @type {import('tailwindcss').Config} */
+        export default {
+          content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
+          theme: {
+            extend: {
+              colors: {
+                // Custom accent colors.
+                accent: colors.fuchsia,
+                // Custom gray scale.
+                gray: colors.slate,
+              },
+              fontFamily: {
+                // Custom text font.
+                sans: ['"Atkinson Hyperlegible"'],
+                // Custom code font.
+                mono: ['"IBM Plex Mono"'],
+              },
+            },
+          },
+          plugins: [starlightPlugin()],
+        };
+        ```
+
+     1. The above customizations can be migrated to the new `@theme` block in the file containing your Tailwind base styles as follows:
+
+        ```css
+        /* src/tailwind.css */
+        @layer base, starlight, theme, components, utilities;
+
+        @import '@astrojs/starlight-tailwind';
+        @import 'tailwindcss/theme.css' layer(theme);
+        @import 'tailwindcss/utilities.css' layer(utilities);
+
+        @theme {
+          /* Custom accent colors. */
+          --color-accent-50: var(--color-fuchsia-50);
+          --color-accent-100: var(--color-fuchsia-100);
+          --color-accent-200: var(--color-fuchsia-200);
+          --color-accent-300: var(--color-fuchsia-300);
+          --color-accent-400: var(--color-fuchsia-400);
+          --color-accent-500: var(--color-fuchsia-500);
+          --color-accent-600: var(--color-fuchsia-600);
+          --color-accent-700: var(--color-fuchsia-700);
+          --color-accent-800: var(--color-fuchsia-800);
+          --color-accent-900: var(--color-fuchsia-900);
+          --color-accent-950: var(--color-fuchsia-950);
+          /* Custom gray scale. */
+          --color-gray-50: var(--color-slate-50);
+          --color-gray-100: var(--color-slate-100);
+          --color-gray-200: var(--color-slate-200);
+          --color-gray-300: var(--color-slate-300);
+          --color-gray-400: var(--color-slate-400);
+          --color-gray-500: var(--color-slate-500);
+          --color-gray-600: var(--color-slate-600);
+          --color-gray-700: var(--color-slate-700);
+          --color-gray-800: var(--color-slate-800);
+          --color-gray-900: var(--color-slate-900);
+          --color-gray-950: var(--color-slate-950);
+          /* Custom text font. */
+          --font-sans: 'Atkinson Hyperlegible';
+          /* Custom code font. */
+          --font-mono: 'IBM Plex Mono';
+        }
+        ```
+
+  We recommend checking your site’s appearance when upgrading to make sure there are no style regressions caused by this change.
+
+  For full details about upgrading from Tailwind v3 to v4, see the [official upgrade guide](https://tailwindcss.com/docs/upgrade-guide).
+
 ## 3.0.1
 
 ### Patch Changes
diff --git a/packages/tailwind/package.json b/packages/tailwind/package.json
index 8835e9e8..e01ab2ae 100644
--- a/packages/tailwind/package.json
+++ b/packages/tailwind/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@astrojs/starlight-tailwind",
-  "version": "3.0.1",
+  "version": "4.0.0",
   "description": "Tailwind CSS plugin for the Starlight documentation theme for Astro",
   "author": "Chris Swithinbank <swithinbank@gmail.com>",
   "license": "MIT",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 671f572a..c6136a65 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -76,7 +76,7 @@ importers:
   examples/basics:
     dependencies:
       '@astrojs/starlight':
-        specifier: ^0.33.2
+        specifier: ^0.34.0
         version: link:../../packages/starlight
       astro:
         specifier: ^5.6.1
@@ -91,10 +91,10 @@ importers:
         specifier: ^0.13.3
         version: 0.13.4(astro@5.6.2(@types/node@18.16.19)(jiti@2.4.2)(lightningcss@1.29.3)(rollup@4.36.0)(tsx@4.15.2)(typescript@5.6.3)(yaml@2.6.1))
       '@astrojs/starlight':
-        specifier: ^0.33.2
+        specifier: ^0.34.0
         version: link:../../packages/starlight
       '@astrojs/starlight-markdoc':
-        specifier: ^0.3.1
+        specifier: ^0.4.0
         version: link:../../packages/markdoc
       astro:
         specifier: ^5.6.1
@@ -106,10 +106,10 @@ importers:
   examples/tailwind:
     dependencies:
       '@astrojs/starlight':
-        specifier: ^0.33.2
+        specifier: ^0.34.0
         version: link:../../packages/starlight
       '@astrojs/starlight-tailwind':
-        specifier: ^3.0.1
+        specifier: ^4.0.0
         version: link:../../packages/tailwind
       '@tailwindcss/vite':
         specifier: ^4.0.7