Skip to content

Commit aa2f81a

Browse files
lukasvinclavlukasvinclav
authored
docs: tailwind configuration (#974)
1 parent 5a10af1 commit aa2f81a

File tree

3 files changed

+128
-75
lines changed

3 files changed

+128
-75
lines changed

‎docs/styles-scripts/customizing-tailwind.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
---
2+
title: Customizing Tailwind stylesheet
3+
order: 1
4+
description: How to customize Tailwind stylesheet to match Unfold design.
5+
---
6+
7+
# Loading Tailwind stylesheet in Django project
8+
9+
When creating a custom dashboard or adding custom components, you may need to add your own styles to provide styling for new elements. The way styles can be loaded is described in the previous section. Once the styles are loaded, you can write CSS selectors with properties. This is sufficient if you don't need to use Tailwind.
10+
11+
Before starting with the Tailwind configuration at the project level, you need to install Tailwind CSS into your project by running `npm install tailwindcss` in the project directory. Don't forget to add `package.json` and `package-lock.json` to your repository.
12+
13+
Most likely, you'll want new elements to match the rest of the administration panel. First, create a `tailwind.config.js` file in your application. Below is the minimal configuration that contains color specifications so all Tailwind classes like `bg-primary-600` will match the admin theme.
14+
15+
```javascript
16+
// tailwind.config.js
17+
18+
module.exports = {
19+
// Support dark mode classes
20+
darkMode: "class",
21+
// Your project's files to scan for Tailwind classes
22+
content: ["./your_project/**/*.{html,py,js}"],
23+
theme: {
24+
extend: {
25+
// Colors that match with UNFOLD["COLORS"] settings
26+
colors: {
27+
base: {
28+
50: "rgb(var(--color-base-50) / <alpha-value>)",
29+
100: "rgb(var(--color-base-100) / <alpha-value>)",
30+
200: "rgb(var(--color-base-200) / <alpha-value>)",
31+
300: "rgb(var(--color-base-300) / <alpha-value>)",
32+
400: "rgb(var(--color-base-400) / <alpha-value>)",
33+
500: "rgb(var(--color-base-500) / <alpha-value>)",
34+
600: "rgb(var(--color-base-600) / <alpha-value>)",
35+
700: "rgb(var(--color-base-700) / <alpha-value>)",
36+
800: "rgb(var(--color-base-800) / <alpha-value>)",
37+
900: "rgb(var(--color-base-900) / <alpha-value>)",
38+
950: "rgb(var(--color-base-950) / <alpha-value>)",
39+
},
40+
primary: {
41+
50: "rgb(var(--color-primary-50) / <alpha-value>)",
42+
100: "rgb(var(--color-primary-100) / <alpha-value>)",
43+
200: "rgb(var(--color-primary-200) / <alpha-value>)",
44+
300: "rgb(var(--color-primary-300) / <alpha-value>)",
45+
400: "rgb(var(--color-primary-400) / <alpha-value>)",
46+
500: "rgb(var(--color-primary-500) / <alpha-value>)",
47+
600: "rgb(var(--color-primary-600) / <alpha-value>)",
48+
700: "rgb(var(--color-primary-700) / <alpha-value>)",
49+
800: "rgb(var(--color-primary-800) / <alpha-value>)",
50+
900: "rgb(var(--color-primary-900) / <alpha-value>)",
51+
950: "rgb(var(--color-primary-950) / <alpha-value>)",
52+
},
53+
font: {
54+
"subtle-light": "rgb(var(--color-font-subtle-light) / <alpha-value>)",
55+
"subtle-dark": "rgb(var(--color-font-subtle-dark) / <alpha-value>)",
56+
"default-light": "rgb(var(--color-font-default-light) / <alpha-value>)",
57+
"default-dark": "rgb(var(--color-font-default-dark) / <alpha-value>)",
58+
"important-light": "rgb(var(--color-font-important-light) / <alpha-value>)",
59+
"important-dark": "rgb(var(--color-font-important-dark) / <alpha-value>)",
60+
}
61+
}
62+
}
63+
}
64+
};
65+
```
66+
67+
Next, create a `styles.css` file in your project's root directory. This file will be used to compile Tailwind CSS into your project:
68+
69+
```css
70+
/* styles.css */
71+
72+
@tailwind base;
73+
@tailwind components;
74+
@tailwind utilities;
75+
76+
/* Your custom styles */
77+
.some-class {
78+
@apply bg-primary-600;
79+
}
80+
```
81+
82+
Once the configuration file is set up, you can compile the styles which can be loaded into the admin using the **STYLES** key in the **UNFOLD** dictionary.
83+
84+
```bash
85+
# One-time build with minified output
86+
npx tailwindcss -i styles.css -o your_project/static/css/styles.css --minify
87+
88+
# Watch for changes and compile automatically with minified output
89+
npx tailwindcss -i styles.css -o your_project/static/css/styles.css --minify --watch
90+
```
91+
92+
You can automate this process by adding the following scripts to your `package.json` file:
93+
94+
```json
95+
{
96+
"scripts": {
97+
"tailwind:watch": "npx tailwindcss -i styles.css -o your_project/static/css/styles.css --minify --watch",
98+
"tailwind:build": "npx tailwindcss -i styles.css -o your_project/static/css/styles.css --minify"
99+
}
100+
// rest of configuration
101+
}
102+
```

‎docs/styles-scripts/index.md‎

Lines changed: 0 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -1,79 +1,4 @@
11
---
22
title: Styles & scripts
33
order: 8
4-
description: Custom styles and scripts for Unfold.
54
---
6-
7-
# Adding custom styles and scripts
8-
9-
To add new custom styles, for example for custom dashboard, it is possible to load them via **STYLES** key in **UNFOLD** dict. This key accepts a list of strings or lambda functions which will be loaded on all pages. JavaScript files can be loaded by using similar apprach, but **SCRIPTS** is used.
10-
11-
```python
12-
# settings.py
13-
14-
from django.templatetags.static import static
15-
16-
UNFOLD = {
17-
"STYLES": [
18-
lambda request: static("css/styles.css"),
19-
],
20-
"SCRIPTS": [
21-
lambda request: static("js/scripts.js"),
22-
],
23-
}
24-
```
25-
26-
## Project level Tailwind stylesheet
27-
28-
When creating custom dashboard or adding custom components, it is needed to add own styles. Adding custom styles is described above. Most of the time, it is supposed that new elements are going to match with the rest of the administration panel. First of all, create tailwind.config.js in your application. Below is located minimal configuration for this file.
29-
30-
```javascript
31-
// tailwind.config.js
32-
33-
module.exports = {
34-
// Support dark mode classes
35-
darkMode: "class",
36-
// Your projects files to look for Tailwind classes
37-
content: ["./your_project/**/*.{html,py,js}"],
38-
//
39-
// In case custom colors are defined in UNFOLD["COLORS"]
40-
colors: {
41-
font: {
42-
"subtle-light": "rgb(var(--color-font-subtle-light) / <alpha-value>)",
43-
"subtle-dark": "rgb(var(--color-font-subtle-dark) / <alpha-value>)",
44-
"default-light": "rgb(var(--color-font-default-light) / <alpha-value>)",
45-
"default-dark": "rgb(var(--color-font-default-dark) / <alpha-value>)",
46-
"important-light": "rgb(var(--color-font-important-light) / <alpha-value>)",
47-
"important-dark": "rgb(var(--color-font-important-dark) / <alpha-value>)",
48-
},
49-
primary: {
50-
50: "rgb(var(--color-primary-50) / <alpha-value>)",
51-
100: "rgb(var(--color-primary-100) / <alpha-value>)",
52-
200: "rgb(var(--color-primary-200) / <alpha-value>)",
53-
300: "rgb(var(--color-primary-300) / <alpha-value>)",
54-
400: "rgb(var(--color-primary-400) / <alpha-value>)",
55-
500: "rgb(var(--color-primary-500) / <alpha-value>)",
56-
600: "rgb(var(--color-primary-600) / <alpha-value>)",
57-
700: "rgb(var(--color-primary-700) / <alpha-value>)",
58-
800: "rgb(var(--color-primary-800) / <alpha-value>)",
59-
900: "rgb(var(--color-primary-900) / <alpha-value>)",
60-
950: "rgb(var(--color-primary-950) / <alpha-value>)",
61-
},
62-
},
63-
};
64-
```
65-
66-
67-
```css
68-
/* styles.css */
69-
70-
@tailwind base;
71-
@tailwind components;
72-
@tailwind utilities;
73-
```
74-
75-
Once the configuration file is set, it is possible to compile new styles which can be loaded into admin by using **STYLES** key in **UNFOLD** dict.
76-
77-
```bash
78-
npx tailwindcss -i styles.css -o your_project/static/css/styles.css --minify
79-
```

‎docs/styles-scripts/loading-files.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
title: Loading styles and scripts
3+
order: 0
4+
description: Settings.py configuration for loading custom styles and scripts files in Unfold.
5+
---
6+
7+
# Loading styles and scripts
8+
9+
To add custom styles, for example for a custom dashboard, you can load them via the **STYLES** key in the **UNFOLD** dictionary in settings.py. This key accepts a list of strings or lambda functions that will be loaded on all pages. JavaScript files can be loaded using a similar approach with the **SCRIPTS** key.
10+
11+
```python
12+
# settings.py
13+
14+
from django.templatetags.static import static
15+
16+
UNFOLD = {
17+
"STYLES": [
18+
lambda request: static("css/styles.css"),
19+
],
20+
"SCRIPTS": [
21+
lambda request: static("js/scripts.js"),
22+
],
23+
}
24+
```
25+
26+
**Note:** When deploying to production, make sure to run the `python manage.py collectstatic` command to collect all static files. This ensures that all custom styles and scripts are properly included in the production build.

0 commit comments

Comments
 (0)