Skip to content

Commit c141cab

Browse files
adamwathanadamwathan
committed
Initial draft of README
1 parent 5c7b231 commit c141cab

File tree

2 files changed

+254
-4
lines changed

2 files changed

+254
-4
lines changed

‎.github/logo.svg

Lines changed: 5 additions & 0 deletions
Loading

‎README.md

Lines changed: 249 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,257 @@
1-
# Tailwind CSS Typography
1+
<p>
2+
<img alt="Tailwind CSS Typography" width="350" src="./.github/logo.svg">
3+
</p>
24

3-
**Still very much a work-in-progress, not ready for use.**
5+
A plugin that provides a set of `prose` classes you can use to add beautiful typographic defaults to any vanilla HTML you don't control (like HTML rendered from Markdown, or pulled from a CMS).
46

5-
A plugin that provides a `rich-text` class you can use to add sensible typographic defaults to any vanilla HTML you don't control (like HTML rendered from Markdown, or pulled from a CMS).
7+
[View live demo](https://tailwindcss-typography.netlify.app/)
68

79
```html
8-
<div class="rich-text">
10+
<article class="prose lg:prose-xl">
911
{{ markdown }}
12+
</article>
13+
```
14+
15+
## Usage
16+
17+
Install the plugin from npm:
18+
19+
```sh
20+
# Using npm
21+
npm install @tailwindcss/typography
22+
23+
# Using Yarn
24+
yarn add @tailwindcss/typography
25+
```
26+
27+
Then add the plugin to your `tailwind.config.js` file:
28+
29+
```js
30+
// tailwind.config.js
31+
module.exports = {
32+
theme: {
33+
// ...
34+
},
35+
plugins: [
36+
require('@tailwindcss/typography'),
37+
// ...
38+
],
39+
}
40+
```
41+
42+
Now you can use the `prose` classes to add sensible typography styles to any vanilla HTML:
43+
44+
````html
45+
```html
46+
<article class="prose lg:prose-xl">
47+
<h1>Garlic bread with cheese: What the science tells us</h1>
48+
<p>
49+
For years parents have espoused the health benefits of eating garlic bread with cheese to their
50+
children, with the food earning such an iconic status in our culture that kids will often dress
51+
up as warm, cheesy loaf for Halloween.
52+
</p>
53+
<p>
54+
But a recent study shows that the celebrated appetizer may be linked to a series of rabies cases
55+
springing up around the country.
56+
</p>
57+
<!-- ... -->
58+
</article>
59+
````
60+
61+
### Size modifiers
62+
63+
Size modifiers allow you to adjust the overall size of your typography for different contexts.
64+
65+
```html
66+
<article class="prose prose-xl">
67+
{{ markdown }}
68+
</article>
69+
```
70+
71+
Five different typography sizes are included out of the box:
72+
73+
| Class | Body font size |
74+
| ----------- | --------------: |
75+
| `prose-sm` | 0.875rem (14px) |
76+
| `prose` | 1rem (16px) |
77+
| `prose-lg` | 1.125rem (18px) |
78+
| `prose-xl` | 1.25rem (20px) |
79+
| `prose-2xl` | 1.5rem (24px) |
80+
81+
Everything about the provided size modifiers has been hand-tuned to look as beautiful as possible, including the relationships between font sizes, heading spacing, code block padding, etc. Just like the Tailwind color palettes, none of these styles are based on naive mathematical formulas, and have been hand-crafted by professional designers.
82+
83+
Size modifiers are designed to be used with the [multi-class modifier pattern](http://nicolasgallagher.com/about-html-semantics-front-end-architecture/#component-modifiers) and **must be used in conjuction with the base `prose` class**:
84+
85+
```html
86+
<!-- Will not work -->
87+
<article class="prose-lg">
88+
{{ markdown }}
89+
</article>
90+
91+
<!-- Always add the `prose` class -->
92+
<article class="prose prose-lg">
93+
{{ markdown }}
94+
</article>
95+
```
96+
97+
### Responsive variants
98+
99+
None of the sizes are automatically responsive, but responsive variants are provided for each size modifier so you can easily change the typography size at different breakpoints:
100+
101+
```html
102+
<article class="prose prose-sm sm:prose lg:prose-lg xl:prose-xl">
103+
{{ markdown }}
104+
</article>
105+
```
106+
107+
## Customization
108+
109+
> The customization API is currently extremely low-level in order to be as flexible as possible. We will be introducing higher-level configuration options over time as we learn what types of customizations are most common.
110+
111+
To customize the styles provided by this plugin, add your overrides under the `typography` key in the `theme` section of your `tailwind.config.js` file:
112+
113+
```js
114+
// tailwind.config.js
115+
module.exports = {
116+
theme: {
117+
typography: {
118+
default: {
119+
css: {
120+
color: '#333',
121+
a: {
122+
color: '#3182ce',
123+
'&:hover': {
124+
color: '#2c5282',
125+
},
126+
},
127+
},
128+
},
129+
},
130+
},
131+
plugins: [
132+
require('@tailwindcss/typography'),
133+
// ...
134+
],
135+
}
136+
```
137+
138+
Customizations should be applied to a specific modifier like `default` or `xl`, and must be added under the `css` property. Customizations are authored in the same [CSS-in-JS syntax](https://tailwindcss.com/docs/plugins#css-in-js-syntax) used to write Tailwind plugins.
139+
140+
It's important to note that all customizations are **merged** with the defaults. If you'd like to completely override a provided size modifier, you can do so by disabling that modifier so the default styles are not included.
141+
142+
See [the default styles](./src/styles.js) for this plugin for more in-depth examples of configuring each modifier.
143+
144+
### Customizing shared styles
145+
146+
Many styles _(for example colors, font weight, and text decoration)_ are shared between all size modifiers, and are therefore defined only for the `default` modifier, since modifiers are designed to be used with the [multi-class modifier pattern](http://nicolasgallagher.com/about-html-semantics-front-end-architecture/#component-modifiers).
147+
148+
If you'd like to customize these sorts of styles, do so using the `default` modifier:
149+
150+
```js
151+
// tailwind.config.js
152+
module.exports = {
153+
theme: {
154+
typography: {
155+
default: {
156+
css: {
157+
color: '#333',
158+
strong: {
159+
fontWeight: '800',
160+
},
161+
// ...
162+
},
163+
},
164+
},
165+
},
166+
plugins: [
167+
require('@tailwindcss/typography'),
168+
// ...
169+
],
170+
}
171+
```
172+
173+
### Adding new modifiers
174+
175+
You can add a new modifier by creating a new key in the `typography` section of your theme and providing your own styles under the `css` key:
176+
177+
```js
178+
// tailwind.config.js
179+
module.exports = {
180+
theme: {
181+
typography: {
182+
'3xl': {
183+
css: {
184+
fontSize: '1.875rem',
185+
h1: {
186+
fontSize: '4rem',
187+
},
188+
// ...
189+
},
190+
},
191+
},
192+
},
193+
plugins: [
194+
require('@tailwindcss/typography'),
195+
// ...
196+
],
197+
}
198+
```
199+
200+
### Overriding max-width
201+
202+
Each size modifier comes with a baked in `max-width` designed to keep the content as readable as possible. This isn't always what you want though, and sometimes you'll want the content to just fill the width of its container.
203+
204+
In those cases, all you need to do is add `max-w-none` to your content to override the embedded max-width:
205+
206+
```html
207+
<div class="grid grid-cols-4">
208+
<div class="col-span-1">
209+
<!-- ... -->
210+
</div>
211+
<div class="col-span-3">
212+
<article class="prose max-w-none">
213+
{{ markdown }}
214+
</article>
215+
</div>
10216
</div>
11217
```
12218

219+
### Disabling size modifiers
220+
221+
If you'd like to completely disable any size modifiers (either for file size reasons or because you'd like to completely redefine that modifier), you can do so using the `modifiers` option when including the plugin:
222+
223+
```js
224+
// tailwind.config.js
225+
module.exports = {
226+
theme: {
227+
// ...
228+
},
229+
plugins: [
230+
require('@tailwindcss/typography')({
231+
modifiers: ['sm', 'lg'],
232+
}),
233+
// ...
234+
],
235+
}
236+
```
237+
238+
This option acts as a _safelist_, so you can list only the modifiers you'd actually like included and the others will be removed.
239+
240+
The `default` modifier is always included and cannot be disabled.
241+
242+
### Disabling responsive variants
243+
244+
If you'd like to disable the responsive variants for any reason, you can do so by setting the `typography` key to an empty array in the `variants` section of your `tailwind.config.js` file:
245+
246+
```js
247+
// tailwind.config.js
248+
module.exports = {
249+
theme: {
250+
// ...
251+
},
252+
plugins: [require('@tailwindcss/typography')],
253+
variants: {
254+
typography: [],
255+
},
256+
}
257+
```

0 commit comments

Comments
 (0)