Support Tailwind CSS integration and styles

[marcjulian]

What version of starlight are you using?

0.0.11

What version of astro are you using?

2.5.5

What package manager are you using?

npm

What operating system are you using?

Mac

What browser are you using?

Chrome, Firefox

Describe the Bug

Adding @astrojs/tailwind and using Tailwind CSS utilities in the content should apply the generated CSS.
The integration was added using npx astro add tailwind and the following tag and utility classes are added to src/content/docs/index.md.

<p class="text-red-500 font-bold">Tailwind CSS should work</p>

The base.css is not loaded and thus the styles are not applied, see the Stackblitz demo.

Link to Minimal Reproducible Example

https://stackblitz.com/edit/github-ypma4c?file=src%2Fcontent%2Fdocs%2Findex.md

Participation

• I am willing to submit a pull request for this issue.

[marcjulian]

The following workaround applies the styles correctly.

https://stackblitz.com/edit/github-ypma4c-otrxul?file=astro.config.mjs

Disabling applyBaseStyles for the tailwind integration and providing a customCss file for startlight

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

import tailwind from '@astrojs/tailwind';

// https://astro.build/config
export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      customCss: ['./src/styles/base.css'],
    }),
    tailwind({
      config: {
        applyBaseStyles: false,
      },
    }),
  ],
});

Add the base.css with the tailwind directives.

/* src/styles/base.css */
/* @tailwind base; // this breaks starlight styles like theme select, sidebar expandable */ 
@tailwind components;
@tailwind utilities;

Should this be added to the docs?

[delucis]

Thanks for opening the issue and for sharing that workaround! I’ll have a think what the best approach is. Would be nice not to force the extra customCss requirement, but may be necessary.

How usable do you think Tailwind is without the @tailwind base?

[marcjulian]

Yes I think it would be good if it works without customCss, but may be it will do for the beginning.

Tailwind adds preflight styles to the @tailwind base layer to reset styles cross-browser for better consistence. Maybe this is already done for starlight.
There would also be another way to keep the @tailwind base and disable preflight in the tailwind config. This way Tailwind still adds defaults for things like translate, ring etc.

/* src/styles/base.css */
@tailwind base
@tailwind components;
@tailwind utilities;

and

// tailwind.config.cjs

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
  corePlugins:{
    preflight: false, // disabling preflight styles
  },
  theme: {
    extend: {},
  },
  plugins: [],
};

[delucis]

Ah, yes, only disabling preflight sounds closer to ideal. Starlight does add a minimal reset, although it's not identical to Tailwind's. I think the one that could cause an issue is the default border style they apply — you'd likely need a more verbose syntax to enable borders, e.g. class="border border-current border-solid".

For what it's worth, I believe the fact that customCss is needed here, is an Astro bug. Haven't had time to make a minimal reproduction yet but will do that.

Eventually we should add a styling customisation guide to the docs, so once we figure out how to best make this work, we can definitely add a "how to use Tailwind" section to that.

[marcjulian]

Yes you are correct, disabling preflight will cause issues with the default boarder styles. I put together a simple TailwindPlay example. When you change the preflight option to false all the border styles and some more styles are lost.

This is how it looks when added to the Starlight content: https://stackblitz.com/edit/github-ypma4c-rg4gmw?file=tailwind.config.cjs

I also noticed some additional margin added to the div by the Markdown Content styles.

starlight/packages/starlight/components/MarkdownContent.astro

Lines 5 to 10 in 8688778

	:global(
	:not(a, strong, em, del, span, input)
	+ :not(a, strong, em, del, span, input)
	) {
	margin-top: 1.5rem;
	}

Maybe we could add a class not-content to undo the content style or even allow customising the Markdown Content style class name to e.g. prose if someone would like to use the @tailwindcss/typography plugin.

starlight/packages/starlight/components/MarkdownContent.astro

Line 1 in 8688778

<div class="content"><slot /></div>

Yes I think a guide for how to use Tailwind would be a good start.

[delucis]

Thanks for taking a look. I wonder if it’s practical to improve compatibility and have the Starlight reset be closer to Tailwind’s. Could be tricky to maintain I guess.

By the way, looks like you’re building some card links, right?

We’re planning to add support for landing pages and some reusable components like that soon just to give you a heads up! Will include cards and some call to action buttons:

[marcjulian]

Yes also not quite sure how to handle the compatibility from Starlight reset with Tailwinds.

Yes correct, I was planing to build some card links with Tailwind CSS. That sounds and looks awesome! Custom landing page sounds good too.

Let me know if I can help with the Tailwind setup documentation or anything else related.

[marcjulian]

Note: How to enable dark mode with Tailwind supporting data-theme="dark" from Starlight

// tailwind.config.cjs

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
  darkMode: ['class', '[data-theme="dark"]'], // support dark mode 🌑
  corePlugins:{
    preflight: false, // disabling preflight styles
  },
  theme: {
    extend: {},
  },
  plugins: [],
};

[delucis]

Thanks for sharing!

[marcjulian]

Using Tailwind colors to override starlight css variables

/* src/styles/base.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

@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.800');
    --sl-color-black: theme('colors.gray.950');

    --sl-color-text-accent: theme('colors.teal.200');
  }

  /* Light Theme */
  :root[data-theme='light'] {
    --sl-color-white: theme('colors.gray.900');
    --sl-color-gray-1: theme('colors.gray.800');
    --sl-color-gray-2: theme('colors.gray.700');
    --sl-color-gray-3: theme('colors.gray.500');
    --sl-color-gray-4: theme('colors.gray.400');
    --sl-color-gray-5: theme('colors.gray.300');
    --sl-color-gray-6: theme('colors.gray.200');
    --sl-color-gray-7: theme('colors.gray.100');

    --sl-color-text-accent: theme('colors.teal.700');
  }
}

[surjithctly]

While not related, I wish there is a way to change the theme itself using Tailwind CSS.

[evan-dunkel]

I also noticed some additional margin added to the div by the Markdown Content styles.

@marcjulian, did you find a way to accomplish the "not-content" styling so global margin-top styles don't apply to components in Markdown?

[marcjulian]

@evan-dunkel I haven't looked into not-content yet. I guess this would need to be considered in the content styles.
As a workaround you could use !mt-0 to override the margin top styles for your components.

margin-top is also set to 0 for the CardGrid:

https://github.com/withastro/starlight/blob/c433f9f3a89e297264cb024fd524b6279539d04d/packages/starlight/user-components/CardGrid.astro#L17-L19C4

[clearfram3]

One option is to adopt Tailwind preflight and write the rest of the Starlight CSS on top of it

[delucis]

Thought I should give a small update in this issue. We’re waiting on withastro/astro#7563 to fix basic Tailwind usage in Starlight routes and also would like to ensure better compatibility for a smoother experience when folks are adding Starlight to sites that have an existing Tailwind config — for example compatibility with Preflight. Still researching what that would take and will want to ensure we’re not negatively impacting people who don’t need Tailwind, but will keep you all posted.

In the meantime, Starlight v0.5.0 does include a not-content class, so you should be able to avoid !important styles like !mt-0 in your components by using that.

[marcjulian]

Sounds great. Do you think once this is figured out we should add Tailwind usage to the docs or even create a starwind (starlight + tailwind) example?

[delucis]

Yes, part of the aim would be a simple recipe in docs of steps to follow to add Tailwind to a Starlight site, including documenting any gotchas that remain, and we could make a template in examples/ with this pre-configured, so that people can also quickly create astro using that template.

Hadn’t thought of calling it starwind but does sound good! 🤩

[marcjulian]

Let me know if I can help you out the the recipe or the starwind example and even helping to figure out better compatibility between Starlight + Tailwind.

[delucis]

Thanks so much for the offer @marcjulian! I just pushed up #337 with a draft PR that adds a Tailwind plugin and a starter template — docs still needed. Would be really curious about feedback from you (and everyone else in this thread)!