Add a Tailwind plugin and docs

[delucis]

What kind of changes does this PR include?

• Changes to Starlight code

Description

• Closes Support Tailwind CSS integration and styles #88
• Adds a Tailwind plugin, available by installing @astrojs/starlight-tailwind, which will configure Tailwind for compatibility with Starlight
  • Disables Preflight (but re-enables its important border styling)
  • Configures Tailwind’s dark mode for compatibility with Starlight’s data-theme attribute
  • Links Starlight’s color custom properties to gray and accent in Tailwind’s theme.colors config.
  • Links Starlight’s font custom properties to sans and mono in Tailwind’s theme.fontFamily config.
• Adds a Tailwind starter project at examples/tailwind/

Big shout out to @marcjulian for many of the tips in #88 that helped shape the work here. Very curious to hear feedback from folks about whether this solution works or not.

To do

• Write docs for how to set up and use Tailwind alongside Starlight
• Remove workarounds in the starter template due to Injected scripts not injected to non-local injected routes astro#7563 once that is fixed

Try it

Keeping this a draft while we wait for withastro/astro#7563 to be fixed, but you can try the starter template by cloning this branch, installing dependencies, then running cd examples/tailwind && pnpm dev.

[changeset-bot]

🦋 Changeset detected

Latest commit: adf7903

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@astrojs/starlight-tailwind	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[netlify]

✅ Deploy Preview for astro-starlight ready!

Name	Link
🔨 Latest commit	adf7903
🔍 Latest deploy log	https://app.netlify.com/sites/astro-starlight/deploys/64d4a34b03d58e00082127cb
😎 Deploy Preview	https://deploy-preview-337--astro-starlight.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[astrobot-houston]

size-limit report 📦

Path	Size
/index.html	9.36 KB (0%)
/_astro/*.js	15.85 KB (0%)
/_astro/*.css	8.36 KB (0%)

[sarah11918]

Docs LGTM! So excited for this feature!

[yanthomasdev]

Docs and example Markdown files all look great to me! Only added a small, non-blocking comment 🙌

[HiDeoo]

Super neat and clean ✨

I assume the withastro/starlight/examples/tailwind template would get aliased at some point in create-astro like Starlight?

Small question: any specific reason to use a .cjs file for the Tailwind configuration file considering they're supporting ESM now? Could be 1 less file type maybe for the end user?

[delucis]

any specific reason to use a .cjs file for the Tailwind configuration file

Mainly that it's what astro add tailwind currently generates. Tailwind docs also show CJS syntax like importing with require and exporting with module.exports (although usually with a .js extension).

I actually tried and all extensions work here (also .ts) and, perhaps most weirdly, you can use import or require in all of them thanks to how Tailwind processes the file during loading. But I thought it might be easiest to stick to what Astro does to have a better chance of matching what a user has.

I assume the withastro/starlight/examples/tailwind template would get aliased at some point

Ah yes, I'd been meaning to do that. Currently create astro has a hardcoded alias that maps starlight to the basics template. Would be nice to support anything after a slash to shorten things, e.g. --template starlight/tailwind.

Update: Proposed support for this here: withastro/astro#7993

[HiDeoo]

But I thought it might be easiest to stick to what Astro does to have a better chance of matching what a user has.

Makes total sense, thanks.

Would be nice to support anything after a slash to shorten things

Ah yeah, that would be great indeed.

[marcjulian]

Hey @delucis this looks awesome. Providing a starlightPlugin for preparing Tailwind to work well with Starlight styles is is perfect. It's event easy to swap out accent and gray color by just changing it in the tailwind config.

Would be nice to support anything after a slash to shorten things, e.g. --template starlight/tailwind.

Even shorter would be starwind ⭐ 🌬️

[marcjulian]

I noticed two things while playing around with a custom theme.

1. Changing accent to colors.red in tailwind.config.cjs updates the accent while in dev mode. However, the accent is overridden in the build output by the default Starlight colors.

Dev mode with accent: colors.red

Build output with accent: colors.red

I checked the generated CSS content. It does contain --sl-color-accent: #dc2626; (theme(colors.red.600) at the beginning of the CSS file in :root. But after all tailwind styles there is a block :root,::backdrop which redefines --sl-color-accent: hsl(var(--sl-hue-accent), 100%, 60%);, the default Starlight theme (coming from packages/starlight/style/props.css).

A workaround would be to add the customCss file back with the tailwind directives (8e3602b). This works because the tailwind styles are added last to the generated CSS file.

2. When the starlightPlugin is enabled, I cannot override the theme styles with providing a customCss file.
   For example, if the theme should have a darker toolbar/sidebar and a lighter content area in dark mode or when I need to apply my own theme:

/* needs base directive otherwise vite throws: `@layer base` is used but no matching `@tailwind base` directive is present. */
@tailwind base;

@layer base {
  /* Dark Theme */
  :root {
    --sl-color-white: theme('colors.white');
    --sl-color-gray-1: theme('colors.gray.200');
    --sl-color-gray-2: theme('colors.gray.300');
    --sl-color-gray-3: theme('colors.gray.500');
    --sl-color-gray-4: theme('colors.gray.600');
    --sl-color-gray-5: theme('colors.gray.700');
    --sl-color-gray-6: theme('colors.gray.950'); /* darker toolbar/sidebar */
    --sl-color-black: theme('colors.gray.800'); /* brighter content */
  }
}

The custom theme styles are overridden by the styles provided by the starlightPlugin, but only in dev mode again.

In build output, the custom styles take effect over the starlightPlugin styles.

Perhaps allowing starlightPlugin to receive an option to disable the default style mapping from starlight would help here. This also eliminates having duplicate definitions of CSS variables and thus leading to a smaller CSS file.

[delucis]

Thanks for testing @marcjulian! Which Astro version was this with?

[marcjulian]

[email protected] I forked this project and test it with the tailwind example.

[delucis]

Thanks for the testing and feedback @marcjulian! I’ve moved the docs and starter template back to the customCSS approach as this seems to be the best way to resolve all these issues.

[marcjulian]

Yes using customCss option solves both issues for dev mode and build. Thanks for the quick update.