Skip to content

Commit 8d133ec

Browse files
reininkreinink
committed
Add docs to readme
1 parent a86e601 commit 8d133ec

File tree

1 file changed

+373
-3
lines changed

1 file changed

+373
-3
lines changed

‎README.md

+373-3
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,383 @@
88
</a>
99
</p>
1010

11-
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.
11+
The official Tailwind CSS Typography plugin 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.
12+
13+
```html
14+
<article class="prose lg:prose-xl">{{ markdown }}</article>
15+
```
16+
17+
To see what it looks like in action, check out our [live demo](https://play.tailwindcss.com/uj1vGACRJA?layout=preview) on Tailwind Play.
18+
19+
---
20+
21+
## Installation
22+
23+
Install the plugin from npm:
24+
25+
```shell
26+
npm install -D @tailwindcss/typography
27+
```
28+
29+
Then add the plugin to your `tailwind.config.js` file:
30+
31+
```js
32+
/** @type {import('tailwindcss').Config} */
33+
module.exports = {
34+
theme: {
35+
// ...
36+
},
37+
plugins: [
38+
require('@tailwindcss/typography'),
39+
// ...
40+
],
41+
}
42+
```
43+
44+
---
45+
46+
## Basic usage
47+
48+
Now you can use the `prose` classes to add sensible typography styles to any vanilla HTML:
49+
50+
```html
51+
<article class="prose lg:prose-xl">
52+
<h1>Garlic bread with cheese: What the science tells us</h1>
53+
<p>
54+
For years parents have espoused the health benefits of eating garlic bread with cheese to their
55+
children, with the food earning such an iconic status in our culture that kids will often dress
56+
up as warm, cheesy loaf for Halloween.
57+
</p>
58+
<p>
59+
But a recent study shows that the celebrated appetizer may be linked to a series of rabies cases
60+
springing up around the country.
61+
</p>
62+
<!-- ... -->
63+
</article>
64+
```
65+
66+
### Choosing a gray scale
67+
68+
This plugin includes a modifier class for each of the five gray scales Tailwind includes by default so you can easily style your content to match the grays you're using in your project.
69+
70+
```html
71+
<article class="prose prose-slate">{{ markdown }}</article>
72+
```
73+
74+
Here are the classes that are generated using a totally default Tailwind CSS v2.0 build:
75+
76+
| Class | Gray scale |
77+
| ------------------------ | ---------- |
78+
| `prose-gray` _(default)_ | Gray |
79+
| `prose-slate` | Slate |
80+
| `prose-zinc` | Zinc |
81+
| `prose-neutral` | Neutral |
82+
| `prose-stone` | Stone |
83+
84+
Modifier classes 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 conjunction with the base `prose` class.
85+
86+
> [!NOTE]
87+
> Always include the `prose` class when adding a gray scale modifier
88+
89+
```html
90+
<article class="prose prose-stone">{{ markdown }}</article>
91+
```
92+
93+
To learn about creating your own color themes, read the [adding custom color themes](#adding-custom-color-themes) documentation.
94+
95+
### Applying a type scale
96+
97+
Size modifiers allow you to adjust the overall size of your typography for different contexts.
98+
99+
```html
100+
<article class="prose prose-xl">{{ markdown }}</article>
101+
```
102+
103+
Five different typography sizes are included out of the box:
104+
105+
| Class | Body font size |
106+
| ------------------------ | ----------------- |
107+
| `prose-sm` | 0.875rem _(14px)_ |
108+
| `prose-base` _(default)_ | 1rem _(16px)_ |
109+
| `prose-lg` | 1.125rem _(18px)_ |
110+
| `prose-xl` | 1.25rem _(20px)_ |
111+
| `prose-2xl` | 1.5rem _(24px)_ |
112+
113+
These can be used in combination with Tailwind's [breakpoint modifiers](https://tailwindcss.com/docs/responsive-design) to change the overall font size of a piece of content at different viewport sizes:
114+
115+
```html
116+
<article class="prose md:prose-lg lg:prose-xl">{{ markdown }}</article>
117+
```
118+
119+
Everything about the provided size modifiers has been hand-tuned by professional designers to look as beautiful as possible, including the relationships between font sizes, heading spacing, code block padding, and more.
120+
121+
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 conjunction with the base `prose` class.
122+
123+
> [!NOTE]
124+
> Always include the `prose` class when adding a size modifier
125+
126+
```html
127+
<article class="prose prose-lg">{{ markdown }}</article>
128+
```
129+
130+
To learn about customizing the included type scales, read the documentation on [customizing the CSS](#customizing-the-css).
131+
132+
### Adapting to dark mode
133+
134+
Each default color theme includes a hand-designed dark mode version that you can trigger by adding the `prose-invert` class:
135+
136+
```html
137+
<article class="prose dark:prose-invert">{{ markdown }}</article>
138+
```
139+
140+
To learn about creating your own color themes, read the [adding custom color themes](#adding-custom-color-themes) documentation.
141+
142+
### Element modifiers
143+
144+
Use element modifiers to customize the style of individual elements in your content directly in your HTML:
145+
146+
```html
147+
<article class="prose prose-img:rounded-xl prose-headings:underline prose-a:text-blue-600">
148+
{{ markdown }}
149+
</article>
150+
```
151+
152+
This makes it easy to do things like style links to match your brand, add a border radius to images, and tons more.
153+
154+
Here's a complete list of available element modifiers:
155+
156+
| Modifier | Target |
157+
| ---------------------------- | ---------------------------- |
158+
| `prose-headings:{utility}` | `h1`, `h2`, `h3`, `h4`, `th` |
159+
| `prose-lead:{utility}` | `[class~="lead"]` |
160+
| `prose-h1:{utility}` | `h1` |
161+
| `prose-h2:{utility}` | `h2` |
162+
| `prose-h3:{utility}` | `h3` |
163+
| `prose-h4:{utility}` | `h4` |
164+
| `prose-p:{utility}` | `p` |
165+
| `prose-a:{utility}` | `a` |
166+
| `prose-blockquote:{utility}` | `blockquote` |
167+
| `prose-figure:{utility}` | `figure` |
168+
| `prose-figcaption:{utility}` | `figcaption` |
169+
| `prose-strong:{utility}` | `strong` |
170+
| `prose-em:{utility}` | `em` |
171+
| `prose-code:{utility}` | `code` |
172+
| `prose-pre:{utility}` | `pre` |
173+
| `prose-ol:{utility}` | `ol` |
174+
| `prose-ul:{utility}` | `ul` |
175+
| `prose-li:{utility}` | `li` |
176+
| `prose-table:{utility}` | `table` |
177+
| `prose-thead:{utility}` | `thead` |
178+
| `prose-tr:{utility}` | `tr` |
179+
| `prose-th:{utility}` | `th` |
180+
| `prose-td:{utility}` | `td` |
181+
| `prose-img:{utility}` | `img` |
182+
| `prose-video:{utility}` | `video` |
183+
| `prose-hr:{utility}` | `hr` |
184+
185+
When stacking these modifiers with other modifiers like `hover`, you most likely want the other modifier to come first:
186+
187+
```html
188+
<article class="prose prose-a:text-blue-600 hover:prose-a:text-blue-500">{{ markdown }}</article>
189+
```
190+
191+
Read the Tailwind CSS documentation on [ordering stacked modifiers](https://tailwindcss.com/docs/hover-focus-and-other-states#ordering-stacked-modifiers) to learn more.
192+
193+
### Overriding max-width
194+
195+
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.
196+
197+
In those cases, all you need to do is add `max-w-none` to your content to override the embedded max-width:
198+
199+
```html
200+
<div class="grid grid-cols-4">
201+
<div class="col-span-1">
202+
<!-- ... -->
203+
</div>
204+
<div class="col-span-3">
205+
<article class="prose max-w-none">{{ markdown }}</article>
206+
</div>
207+
</div>
208+
```
12209

13210
---
14211

15-
## Documentation
212+
## Advanced topics
213+
214+
### Undoing typography styles
215+
216+
If you have a block of markup embedded in some content that shouldn't inherit the `prose` styles, use the `not-prose` class to sandbox it:
217+
218+
```html
219+
<article class="prose">
220+
<h1>My Heading</h1>
221+
<p>...</p>
222+
223+
<div class="not-prose">
224+
<!-- Some example or demo that needs to be prose-free -->
225+
</div>
226+
227+
<p>...</p>
228+
<!-- ... -->
229+
</article>
230+
```
231+
232+
Note that you can't nest new `prose` instances within a `not-prose` block at this time.
233+
234+
### Adding custom color themes
16235

17-
For full documentation, visit [tailwindcss.com/docs/typography-plugin](https://tailwindcss.com/docs/typography-plugin).
236+
You can create your own color theme by adding a new key in the `typography` section of your `tailwind.config.js` file and providing your colors under the `css` key:
237+
238+
```js {{ filename: 'tailwind.config.js' }}
239+
/** @type {import('tailwindcss').Config} */
240+
module.exports = {
241+
theme: {
242+
extend: {
243+
typography: ({ theme }) => ({
244+
pink: {
245+
css: {
246+
'--tw-prose-body': theme('colors.pink[800]'),
247+
'--tw-prose-headings': theme('colors.pink[900]'),
248+
'--tw-prose-lead': theme('colors.pink[700]'),
249+
'--tw-prose-links': theme('colors.pink[900]'),
250+
'--tw-prose-bold': theme('colors.pink[900]'),
251+
'--tw-prose-counters': theme('colors.pink[600]'),
252+
'--tw-prose-bullets': theme('colors.pink[400]'),
253+
'--tw-prose-hr': theme('colors.pink[300]'),
254+
'--tw-prose-quotes': theme('colors.pink[900]'),
255+
'--tw-prose-quote-borders': theme('colors.pink[300]'),
256+
'--tw-prose-captions': theme('colors.pink[700]'),
257+
'--tw-prose-code': theme('colors.pink[900]'),
258+
'--tw-prose-pre-code': theme('colors.pink[100]'),
259+
'--tw-prose-pre-bg': theme('colors.pink[900]'),
260+
'--tw-prose-th-borders': theme('colors.pink[300]'),
261+
'--tw-prose-td-borders': theme('colors.pink[200]'),
262+
'--tw-prose-invert-body': theme('colors.pink[200]'),
263+
'--tw-prose-invert-headings': theme('colors.white'),
264+
'--tw-prose-invert-lead': theme('colors.pink[300]'),
265+
'--tw-prose-invert-links': theme('colors.white'),
266+
'--tw-prose-invert-bold': theme('colors.white'),
267+
'--tw-prose-invert-counters': theme('colors.pink[400]'),
268+
'--tw-prose-invert-bullets': theme('colors.pink[600]'),
269+
'--tw-prose-invert-hr': theme('colors.pink[700]'),
270+
'--tw-prose-invert-quotes': theme('colors.pink[100]'),
271+
'--tw-prose-invert-quote-borders': theme('colors.pink[700]'),
272+
'--tw-prose-invert-captions': theme('colors.pink[400]'),
273+
'--tw-prose-invert-code': theme('colors.white'),
274+
'--tw-prose-invert-pre-code': theme('colors.pink[300]'),
275+
'--tw-prose-invert-pre-bg': 'rgb(0 0 0 / 50%)',
276+
'--tw-prose-invert-th-borders': theme('colors.pink[600]'),
277+
'--tw-prose-invert-td-borders': theme('colors.pink[700]'),
278+
},
279+
},
280+
}),
281+
},
282+
},
283+
plugins: [
284+
require('@tailwindcss/typography'),
285+
// ...
286+
],
287+
}
288+
```
289+
290+
See our internal [style definitions](https://github.com/tailwindlabs/tailwindcss-typography/blob/master/src/styles.js) for some more examples.
291+
292+
### Changing the default class name
293+
294+
If you need to use a class name other than `prose` for any reason, you can do so using the `className` option when registering the plugin:
295+
296+
```js {{ filename: 'tailwind.config.js' }}
297+
/** @type {import('tailwindcss').Config} */
298+
module.exports = {
299+
theme: {
300+
// ...
301+
},
302+
plugins: [
303+
require('@tailwindcss/typography')({
304+
className: 'wysiwyg',
305+
}),
306+
]
307+
...
308+
}
309+
```
310+
311+
Now every instance of `prose` in the default class names will be replaced by your custom class name:
312+
313+
```html
314+
<article class="wysiwyg wysiwyg-slate lg:wysiwyg-xl">
315+
<h1>My Heading</h1>
316+
<p>...</p>
317+
318+
<div class="not-wysiwyg">
319+
<!-- Some example or demo that needs to be prose-free -->
320+
</div>
321+
322+
<p>...</p>
323+
<!-- ... -->
324+
</article>
325+
```
326+
327+
### Customizing the CSS
328+
329+
If you want to customize the raw CSS generated by this plugin, add your overrides under the `typography` key in the `theme` section of your `tailwind.config.js` file:
330+
331+
```js {{ filename: 'tailwind.config.js' }}
332+
/** @type {import('tailwindcss').Config} */
333+
module.exports = {
334+
theme: {
335+
extend: {
336+
typography: {
337+
DEFAULT: {
338+
css: {
339+
color: '#333',
340+
a: {
341+
color: '#3182ce',
342+
'&:hover': {
343+
color: '#2c5282',
344+
},
345+
},
346+
},
347+
},
348+
},
349+
},
350+
},
351+
plugins: [
352+
require('@tailwindcss/typography'),
353+
// ...
354+
],
355+
}
356+
```
357+
358+
Like with all theme customizations in Tailwind, you can also define the `typography` key as a function if you need access to the `theme` helper:
359+
360+
```js {{ filename: 'tailwind.config.js' }}
361+
/** @type {import('tailwindcss').Config} */
362+
module.exports = {
363+
theme: {
364+
extend: {
365+
typography: (theme) => ({
366+
DEFAULT: {
367+
css: {
368+
color: theme('colors.gray.800'),
369+
370+
// ...
371+
},
372+
},
373+
}),
374+
},
375+
},
376+
plugins: [
377+
require('@tailwindcss/typography'),
378+
// ...
379+
],
380+
}
381+
```
382+
383+
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.
384+
385+
See [the default styles](https://github.com/tailwindlabs/tailwindcss-typography/blob/master/src/styles.js) for this plugin for more in-depth examples of configuring each modifier.
386+
387+
---
18388

19389
## Community
20390

0 commit comments

Comments
 (0)