Add a Tailwind plugin and docs

.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,196 @@
+---
+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.
+
+### 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
+# create a new project with npm
+npm create astro@latest -- --template withastro/starlight/examples/tailwind
+```
+
+</TabItem>
+<TabItem label="pnpm">
+
+```sh
+# create a new project with pnpm
+pnpm create astro --template withastro/starlight/examples/tailwind
+```
+
+</TabItem>
+<TabItem label="Yarn">
+
+```sh
+# create a new project with yarn
+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.  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"
+    }
+  ]
+}

examples/tailwind/README.md

@@ -0,0 +1,52 @@
+# Starlight Starter Kit: Tailwind
+
+```
+npm create astro@latest -- --template withastro/starlight/examples/tailwind
+```
+
+[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/withastro/starlight/tree/main/examples/basics)
+[![Open with CodeSandbox](https://assets.codesandbox.io/github/button-edit-lime.svg)](https://codesandbox.io/p/sandbox/github/withastro/starlight/tree/main/examples/basics)
+
+> 🧑‍🚀 **Seasoned astronaut?** Delete this file. Have fun!
+
+## 🚀 Project Structure
+
+Inside of your Astro + Starlight project, you'll see the following folders and files:
+
+```
+.
+├── public/
+├── src/
+│   ├── assets/
+│   ├── content/
+│   │   ├── docs/
+│   │   └── config.ts
+│   └── env.d.ts
+├── astro.config.mjs
+├── package.json
+├── tailwind.config.cjs
+└── tsconfig.json
+```
+
+Starlight looks for `.md` or `.mdx` files in the `src/content/docs/` directory. Each file is exposed as a route based on its file name.
+
+Images can be added to `src/assets/` and embedded in Markdown with a relative link.
+
+Static assets, like favicons, can be placed in the `public/` directory.
+
+## 🧞 Commands
+
+All commands are run from the root of the project, from a terminal:
+
+| Command                   | Action                                           |
+| :------------------------ | :----------------------------------------------- |
+| `npm install`             | Installs dependencies                            |
+| `npm run dev`             | Starts local dev server at `localhost:3000`      |
+| `npm run build`           | Build your production site to `./dist/`          |
+| `npm run preview`         | Preview your build locally, before deploying     |
+| `npm run astro ...`       | Run CLI commands like `astro add`, `astro check` |
+| `npm run astro -- --help` | Get help using the Astro CLI                     |
+
+## 👀 Want to learn more?
+
+Check out [Starlight’s docs](https://starlight.astro.build/), read [the Astro documentation](https://docs.astro.build), or jump into the [Astro Discord server](https://astro.build/chat).