Skip to content

Commit 6101bd9

Browse files
thecrypticacereinink
thecrypticace
and
reinink
authored
Improve documentation (#2280)
This is a bit of a catchall PR for some documentation updates - Adds a step to the "Using Vite" guide: #2254 - Adds a Gatsby guide: Fixes #2274 - Adds a note about using configs alongside normal, CSS-driven configuration: Fixes #2277 - Adds a details about using `source()`, `theme()`, `prefix()`, etc… when using individual imports: Fixes #2145 - Adds a link to the `@source inline()` docs after discussing `@config` — we already do this in the upgrade guide so I added it for consistency. --------- Co-authored-by: Jonathan Reinink <jonathan@reinink.ca>
1 parent 97c018a commit 6101bd9

File tree

6 files changed

+232
-2
lines changed

6 files changed

+232
-2
lines changed

‎src/app/(docs)/docs/installation/(tabs)/using-vite/page.tsx‎

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,23 @@ export const metadata: Metadata = {
1717
};
1818

1919
const steps: Step[] = [
20+
{
21+
title: "Create your project",
22+
body: (
23+
<p>
24+
Start by creating a new Vite project if you don’t have one set up already. The most common approach is to use{" "}
25+
<a href="https://vite.dev/guide/#scaffolding-your-first-vite-project">Create Vite</a>.
26+
</p>
27+
),
28+
code: {
29+
name: "Terminal",
30+
lang: "shell",
31+
code: dedent`
32+
npm create vite@latest my-project
33+
cd my-project
34+
`,
35+
},
36+
},
2037
{
2138
title: "Install Tailwind CSS",
2239
body: (
@@ -106,7 +123,7 @@ const steps: Step[] = [
106123
<meta charset="UTF-8">
107124
<meta name="viewport" content="width=device-width, initial-scale=1.0">
108125
<!-- [!code highlight:2] -->
109-
<link href="/src/styles.css" rel="stylesheet">
126+
<link href="/src/style.css" rel="stylesheet">
110127
</head>
111128
<body>
112129
<!-- [!code highlight:4] -->

‎src/app/(docs)/docs/installation/framework-guides/gatsby.tsx‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
import { astro, css, js, Page, shell, Step, Tile } from "./utils";
2+
import Logo from "@/docs/img/guides/gatsby.react.svg";
3+
4+
export let tile: Tile = {
5+
title: "Gatsby",
6+
description: "Framework for building static sites with React and GraphQL.",
7+
Logo,
8+
};
9+
10+
export let page: Page = {
11+
title: "Install Tailwind CSS with Gatsby",
12+
description: "Setting up Tailwind CSS in a Gatsby project.",
13+
};
14+
15+
export let steps: Step[] = [
16+
{
17+
title: "Create your project",
18+
body: (
19+
<p>
20+
Start by creating a new Gatsby project if you don’t have one set up already. The most common approach is to use{" "}
21+
<a href="https://www.gatsbyjs.com/docs/reference/gatsby-cli/#how-to-use-gatsby-cli">Gatsby CLI</a>.
22+
</p>
23+
),
24+
code: {
25+
name: "Terminal",
26+
lang: "shell",
27+
code: shell`
28+
gatsby new my-project
29+
cd my-project
30+
`,
31+
},
32+
},
33+
{
34+
title: "Install Tailwind CSS",
35+
body: (
36+
<p>
37+
Using npm, install <code>@tailwindcss/postcss</code>, its peer dependencies, and{" "}
38+
<code>gatsby-plugin-postcss</code>.
39+
</p>
40+
),
41+
code: {
42+
name: "Terminal",
43+
lang: "shell",
44+
code: shell`
45+
npm install @tailwindcss/postcss tailwindcss postcss gatsby-plugin-postcss
46+
`,
47+
},
48+
},
49+
{
50+
title: "Enable the Gatsby PostCSS plugin",
51+
body: (
52+
<p>
53+
In your <code>gatsby-config.js</code> file, enable <code>gatsby-plugin-postcss</code>. See{" "}
54+
<a href="https://www.gatsbyjs.com/plugins/gatsby-plugin-postcss/">the plugin's documentation</a> for more
55+
information.
56+
</p>
57+
),
58+
code: {
59+
name: "gatsby-config.js",
60+
lang: "js",
61+
code: js`
62+
module.exports = {
63+
plugins: [
64+
// [!code highlight:2]
65+
'gatsby-plugin-postcss',
66+
// ...
67+
],
68+
}
69+
`,
70+
},
71+
},
72+
{
73+
title: "Configure PostCSS Plugins",
74+
body: (
75+
<p>
76+
Create a <code>postcss.config.js</code> file in the root of your project and add the{" "}
77+
<code>@tailwindcss/postcss</code> plugin to your PostCSS configuration.
78+
</p>
79+
),
80+
code: {
81+
name: "postcss.config.js",
82+
lang: "js",
83+
code: js`
84+
module.exports = {
85+
plugins: {
86+
// [!code highlight:2]
87+
"@tailwindcss/postcss": {},
88+
},
89+
};
90+
`,
91+
},
92+
},
93+
{
94+
title: "Import Tailwind CSS",
95+
body: (
96+
<p>
97+
Create a <code>./src/styles/global.css</code> file and add an <code>@import</code> for Tailwind CSS.
98+
</p>
99+
),
100+
code: {
101+
name: "global.css",
102+
lang: "css",
103+
code: css`
104+
@import "tailwindcss";
105+
`,
106+
},
107+
},
108+
{
109+
title: "Import the CSS file",
110+
body: (
111+
<p>
112+
Create a <code>gatsby-browser.js</code> file at the root of your project if it doesn’t already exist, and import
113+
your newly-created <code>./src/styles/global.css</code> file.
114+
</p>
115+
),
116+
code: {
117+
name: "gatsby-browser.js",
118+
lang: "js",
119+
code: js`
120+
import './src/styles/global.css';
121+
`,
122+
},
123+
},
124+
{
125+
title: "Start your build process",
126+
body: (
127+
<p>
128+
Run your build process with <code>gatsby develop</code>.
129+
</p>
130+
),
131+
code: {
132+
name: "Terminal",
133+
lang: "shell",
134+
code: shell`
135+
gatsby develop
136+
`,
137+
},
138+
},
139+
{
140+
title: "Start using Tailwind in your project",
141+
body: <p>Start using Tailwind’s utility classes to style your content.</p>,
142+
code: {
143+
name: "index.js",
144+
lang: "js",
145+
code: js`
146+
export default function IndexPage() {
147+
return (
148+
<Layout>
149+
/* [!code highlight:4] */
150+
<h1 className="text-3xl font-bold underline">
151+
Hello world!
152+
</h1>
153+
</Layout>
154+
)
155+
}
156+
`,
157+
},
158+
},
159+
];

‎src/app/(docs)/docs/installation/framework-guides/index.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ const guides: Guide[] = await create({
1414
nuxt: () => import("./nuxtjs"),
1515
solidjs: () => import("./solidjs"),
1616
sveltekit: () => import("./sveltekit"),
17+
gatsby: () => import("./gatsby"),
1718
angular: () => import("./angular"),
1819
"ruby-on-rails": () => import("./ruby-on-rails"),
1920
"react-router": () => import("./react-router"),

‎src/docs/functions-and-directives.mdx‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -246,6 +246,8 @@ This can also be useful in arbitrary values, especially in combination with `cal
246246

247247
The following directives and functions exist solely for compatibility with Tailwind CSS v3.x.
248248

249+
The `@config` and `@plugin` directives may be used in conjunction with `@theme`, `@utility`, and other CSS-driven features. This can be used to incrementally move over your theme, custom configuration, utilities, variants, and presets to CSS. Things defined in CSS will be merged where possible and otherwise take precedence over those defined in configs, presets, and plugins.
250+
249251
<h3 id="config-directive">
250252
<a href="#config-directive">@config</a>
251253
</h3>
@@ -257,7 +259,7 @@ Use the `@config` directive to load a legacy JavaScript-based configuration file
257259
@config "../../tailwind.config.js";
258260
```
259261

260-
The `corePlugins`, `safelist`, and `separator` options from the JavaScript-based config are not supported in v4.0.
262+
The `corePlugins`, `safelist`, and `separator` options from the JavaScript-based config are not supported in v4.0. To safelist utilities in v4 use [`@source inline()`](/docs/detecting-classes-in-source-files#safelisting-specific-utilities).
261263

262264
<h3 id="plugin-directive">
263265
<a href="#plugin-directive">@plugin</a>

‎src/docs/img/guides/gatsby.react.svg‎

Lines changed: 4 additions & 0 deletions
Loading

‎src/docs/preflight.mdx‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -231,3 +231,50 @@ To disable Preflight, simply omit its import while keeping everything else:
231231
@import "tailwindcss/preflight.css" layer(base); /* [!code --] */
232232
@import "tailwindcss/utilities.css" layer(utilities);
233233
```
234+
235+
When importing Tailwind CSS' files individually, features like `source()`, `theme()`, and `prefix()` should go on their respective imports.
236+
237+
For example, source detection affects generated utilities, so `source(…)` should be added to the `utilities.css` import:
238+
239+
```css
240+
/* [!code filename:CSS] */
241+
@layer theme, base, components, utilities;
242+
243+
@import "tailwindcss/theme.css" layer(theme);
244+
@import "tailwindcss/utilities.css" layer(utilities); /* [!code --] */
245+
@import "tailwindcss/utilities.css" layer(utilities) source(none); /* [!code ++] */
246+
```
247+
248+
The same goes for `important`, which also affects utilities:
249+
250+
```css
251+
/* [!code filename:CSS] */
252+
@layer theme, base, components, utilities;
253+
254+
@import "tailwindcss/theme.css" layer(theme);
255+
@import "tailwindcss/utilities.css" layer(utilities); /* [!code --] */
256+
@import "tailwindcss/utilities.css" layer(utilities) important; /* [!code ++] */
257+
```
258+
259+
Similarly, `theme(static)` and `theme(inline)` affect the generated theme variables and should be placed on the `theme.css` import:
260+
261+
```css
262+
/* [!code filename:CSS] */
263+
@layer theme, base, components, utilities;
264+
265+
@import "tailwindcss/theme.css" layer(theme); /* [!code --] */
266+
@import "tailwindcss/theme.css" layer(theme) theme(static); /* [!code ++] */
267+
@import "tailwindcss/utilities.css" layer(utilities);
268+
```
269+
270+
Finally, using a prefix with `prefix(tw)` affects the utilities and variables, so it should go on both imports:
271+
272+
```css
273+
/* [!code filename:CSS] */
274+
@layer theme, base, components, utilities;
275+
276+
@import "tailwindcss/theme.css" layer(theme); /* [!code --] */
277+
@import "tailwindcss/utilities.css" layer(utilities); /* [!code --] */
278+
@import "tailwindcss/theme.css" layer(theme) prefix(tw); /* [!code ++] */
279+
@import "tailwindcss/utilities.css" layer(utilities) prefix(tw); /* [!code ++] */
280+
```

0 commit comments

Comments
 (0)