Add a Tailwind plugin and docs (#337)

.changeset/flat-hounds-poke.md

@@ -0,0 +1,5 @@
+---
+"@astrojs/starlight-tailwind": minor
+---
+
+Add Tailwind plugin

.github/labeler.yml

@@ -14,5 +14,8 @@ i18n:
 '🌟 core':
   - packages/starlight/**
 
+'🌟 tailwind':
+  - packages/tailwind/**
+
 '📚 docs':
   - docs/**

.github/workflows/ci.yml

@@ -27,9 +27,8 @@ jobs:
           node-version: ${{ env.NODE_VERSION }}
           cache: 'pnpm'
       - run: pnpm i
-      - name: Test packages/starlight
-        working-directory: ./packages/starlight
-        run: pnpm test:coverage
+      - name: Test packages
+        run: pnpm -r test:coverage
 
   pa11y:
     name: Check for accessibility issues

.gitignore

@@ -13,3 +13,6 @@ pnpm-debug.log*
 
 # macOS-specific files
 .DS_Store
+
+# Vitest
+__coverage__/

docs/src/content/docs/guides/css-and-tailwind.mdx

@@ -0,0 +1,233 @@
+---
+title: CSS & Styling
+description: Learn how to style your Starlight site with custom CSS or integrate with Tailwind CSS.
+---
+
+You can style your Starlight site with custom CSS files or use the Starlight Tailwind plugin.
+
+## Custom CSS styles
+
+Customize the styles applied to your Starlight site by providing additional CSS files to modify or extend Starlight’s default styles.
+
+1. Add a CSS file to your `src/` directory.
+   For example, you could override Starlight’s default blue accent hue to purple:
+
+   ```css
+   /* src/styles/custom.css */
+   :root {
+   	--sl-hue-accent: 270;
+   }
+   ```
+
+2. Add the path to your CSS file to Starlight’s `customCss` array in `astro.config.mjs`:
+
+   ```js
+   // astro.config.mjs
+   import { defineConfig } from 'astro/config';
+   import starlight from '@astrojs/starlight';
+
+   export default defineConfig({
+   	integrations: [
+   		starlight({
+   			title: 'Docs With Custom CSS',
+   			customCss: [
+   				// Relative path to your custom CSS file
+   				'./src/styles/custom.css',
+   			],
+   		}),
+   	],
+   });
+   ```
+
+You can see all the CSS custom properties used by Starlight that you can set to customize your site in the [`props.css` file on GitHub](https://github.com/withastro/starlight/blob/main/packages/starlight/style/props.css).
+
+## Tailwind CSS
+
+Tailwind CSS support in Astro projects is provided by the [Astro Tailwind integration](https://docs.astro.build/en/guides/integrations-guide/tailwind/).
+Starlight provides a complementary Tailwind plugin to help configure Tailwind for compatibility with Starlight’s styles.
+
+The Starlight Tailwind plugin applies the following configuration:
+
+- Configures Tailwind’s `dark:` variants to work with Starlight’s dark mode.
+- Uses Tailwind [theme colors and fonts](#styling-starlight-with-tailwind) in Starlight’s UI.
+- Disables Tailwind’s [Preflight](https://tailwindcss.com/docs/preflight) reset styles while selectively restoring essential parts of Preflight required for Tailwind’s border utility classes.
+
+### Create a new project with Tailwind
+
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
+Start a new Starlight project with Tailwind CSS pre-configured using `create astro`:
+
+<Tabs>
+<TabItem label="npm">
+
+```sh
+npm create astro@latest -- --template withastro/starlight/examples/tailwind
+```
+
+</TabItem>
+<TabItem label="pnpm">
+
+```sh
+pnpm create astro --template withastro/starlight/examples/tailwind
+```
+
+</TabItem>
+<TabItem label="Yarn">
+
+```sh
+yarn create astro --template withastro/starlight/examples/tailwind
+```
+
+</TabItem>
+</Tabs>
+
+### Add Tailwind to an existing project
+
+If you already have a Starlight site and want to add Tailwind CSS, follow these steps.
+
+1.  Add Astro’s Tailwind integration:
+
+    <Tabs>
+
+    <TabItem label="npm">
+
+    ```sh
+    npx astro add tailwind
+    ```
+
+    </TabItem>
+
+    <TabItem label="pnpm">
+
+    ```sh
+    pnpm astro add tailwind
+    ```
+
+    </TabItem>
+
+    <TabItem label="Yarn">
+
+    ```sh
+    yarn astro add tailwind
+    ```
+
+    </TabItem>
+
+    </Tabs>
+
+2.  Install the Starlight Tailwind plugin:
+
+    <Tabs>
+
+    <TabItem label="npm">
+
+    ```sh
+    npm install @astrojs/starlight-tailwind
+    ```
+
+    </TabItem>
+
+    <TabItem label="pnpm">
+
+    ```sh
+    pnpm install @astrojs/starlight-tailwind
+    ```
+
+    </TabItem>
+
+    <TabItem label="Yarn">
+
+    ```sh
+    yarn add @astrojs/starlight-tailwind
+    ```
+
+    </TabItem>
+
+    </Tabs>
+
+3.  Create a CSS file for Tailwind’s base styles, for example at `src/tailwind.css`:
+
+    ```css
+    /* src/tailwind.css */
+    @tailwind base;
+    @tailwind components;
+    @tailwind utilities;
+    ```
+
+4.  Update your Astro config file to use your Tailwind base styles and disable the default base styles:
+
+    ```js {11-12,16-17}
+    // 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: [
+    				// Path to your Tailwind base styles:
+    				'./src/tailwind.css',
+    			],
+    		}),
+    		tailwind({
+    			// Disable the default base styles:
+    			applyBaseStyles: false,
+    		}),
+    	],
+    });
+    ```
+
+5.  Add the Starlight Tailwind plugin to `tailwind.config.cjs`:
+
+    ```js ins={2,7}
+    // tailwind.config.cjs
+    const starlightPlugin = require('@astrojs/starlight-tailwind');
+
+    /** @type {import('tailwindcss').Config} */
+    module.exports = {
+    	content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
+    	plugins: [starlightPlugin()],
+    };
+    ```
+
+### Styling Starlight with Tailwind
+
+Starlight will use values from your [Tailwind theme config](https://tailwindcss.com/docs/theme) in its UI.
+
+If set, the following options will override Starlight’s default styles:
+
+- `colors.accent` — used for links and current item highlighting
+- `colors.gray` — used for background colors and borders
+- `fontFamily.sans` — used for UI and content text
+- `fontFamily.mono` — used for code examples
+
+```js {12,14,18,20}
+// tailwind.config.cjs
+const starlightPlugin = require('@astrojs/starlight-tailwind');
+const colors = require('tailwindcss/colors');
+
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+	content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
+	theme: {
+		extend: {
+			colors: {
+				// Your preferred accent color. Indigo is closest to Starlight’s defaults.
+				accent: colors.indigo,
+				// Your preferred gray scale. Zinc is closest to Starlight’s defaults.
+				gray: colors.zinc,
+			},
+			fontFamily: {
+				// Your preferred text font. Starlight uses a system font stack by default.
+				sans: ['"Atkinson Hyperlegible"'],
+				// Your preferred code font. Starlight uses system monospace fonts by default.
+				mono: ['"IBM Plex Mono"'],
+			},
+		},
+	},
+	plugins: [starlightPlugin()],
+};
+```

docs/src/content/docs/guides/customization.mdx

@@ -1,6 +1,6 @@
 ---
 title: Customizing Starlight
-description: Learn how to make your Starlight site your own with custom styles, fonts, and more.
+description: Learn how to make your Starlight site your own with your logo, custom fonts, landing page design and more.
 ---
 
 import { Tabs, TabItem } from '@astrojs/starlight/components';
@@ -263,42 +263,6 @@ hero:
 ---
 ```
 
-## Custom CSS styles
-
-Customize the styles applied to your Starlight site by providing additional CSS files to modify or extend Starlight’s default styles.
-
-1. Add a CSS file to your `src/` directory.
-   For example, you could override Starlight’s default blue accent hue to purple:
-
-   ```css
-   /* src/styles/custom.css */
-   :root {
-   	--sl-hue-accent: 270;
-   }
-   ```
-
-2. Add the path to your CSS file to Starlight’s `customCss` array in `astro.config.mjs`:
-
-   ```js
-   // astro.config.mjs
-   import { defineConfig } from 'astro/config';
-   import starlight from '@astrojs/starlight';
-
-   export default defineConfig({
-   	integrations: [
-   		starlight({
-   			title: 'Docs With Custom CSS',
-   			customCss: [
-   				// Relative path to your custom CSS file
-   				'./src/styles/custom.css',
-   			],
-   		}),
-   	],
-   });
-   ```
-
-You can see all the CSS custom properties used by Starlight that you can set to customize your site in the [`props.css` file on GitHub](https://github.com/withastro/starlight/blob/main/packages/starlight/style/props.css).
-
 ## Custom fonts
 
 By default, Starlight uses sans-serif fonts available on a user’s local device for all text.
@@ -426,7 +390,7 @@ It provides npm modules you can install for the fonts you want to use and includ
 
 ### Use fonts
 
-To apply the font you set up to your site, use your chosen font’s name in a custom CSS file.
+To apply the font you set up to your site, use your chosen font’s name in a [custom CSS file](/guides/css-and-tailwind/#custom-css-styles).
 For example, to override Starlight’s default font everywhere, set the `--sl-font` custom property:
 
 ```css
@@ -448,4 +412,4 @@ main {
 }
 ```
 
-Follow the [custom CSS instructions](#custom-css-styles) to add your styles to your site.
+Follow the [custom CSS instructions](/guides/css-and-tailwind/#custom-css-styles) to add your styles to your site.

examples/tailwind/.gitignore

@@ -0,0 +1,21 @@
+# build output
+dist/
+# generated types
+.astro/
+
+# dependencies
+node_modules/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
+.DS_Store

examples/tailwind/.vscode/extensions.json

@@ -0,0 +1,4 @@
+{
+  "recommendations": ["astro-build.astro-vscode"],
+  "unwantedRecommendations": []
+}

examples/tailwind/.vscode/launch.json

@@ -0,0 +1,11 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "command": "./node_modules/.bin/astro dev",
+      "name": "Development server",
+      "request": "launch",
+      "type": "node-terminal"
+    }
+  ]
+}