You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Given HTML, juice will inline your CSS properties into the `style` attribute.
3
+
[![CI][github-ci-shield]][github-ci]
4
+
5
+
[![License][license-shield]][license]
6
+
7
+
Given HTML, Juice will inline your CSS properties into the `style` attribute.
7
8
8
-
[Some projects using Juice](PROJECTS.md)
9
+
[Some projects using Juice→](PROJECTS.md)
9
10
10
11
## How to use
11
12
12
-
Juice has a number of functions based on whether you want to process a file, HTML string, or a cheerio document, and whether you want juice to automatically get remote stylesheets, scripts and image dataURIs to inline.
13
+
Juice has a number of functions based on whether you want to process a file, HTML string, or a cheerio document, and whether you want Juice to automatically get remote stylesheets, scripts and image dataURIs to inline.
13
14
14
15
To inline HTML without getting remote resources, using default options:
15
16
16
17
```js
17
-
var juice =require('juice');
18
-
var result =juice("<style>div{color:red;}</style><div/>");
[Try out the web client version](https://automattic.github.io/juice/)
27
28
28
-
## What is this useful for?
29
+
## What is this useful for?
29
30
30
-
- HTML emails. For a comprehensive list of supported selectors see [here](https://www.campaignmonitor.com/css/)
31
+
- HTML emails. For CSS support in email clients see [Can I Email](https://www.caniemail.com/).
31
32
- Embedding HTML in 3rd-party websites.
32
33
33
34
## Documentation
@@ -36,137 +37,191 @@ Juice is exposed as a standard module, and from CLI with a smaller set of option
36
37
37
38
### Options
38
39
39
-
All juice methods take an options object that can contain any of these properties, though not every method uses all of these:
40
-
41
-
*`applyAttributesTableElements` - whether to create attributes for styles in `juice.styleToAttribute` on elements set in `juice.tableElements`. Defaults to `true`.
42
-
43
-
*`applyHeightAttributes` - whether to use any CSS pixel heights to create `height` attributes on elements set in `juice.heightElements`. Defaults to `true`.
44
-
45
-
*`applyStyleTags` - whether to inline styles in `<style></style>` Defaults to `true`.
46
-
47
-
*`applyWidthAttributes` - whether to use any CSS pixel widths to create `width` attributes on elements set in `juice.widthElements`. Defaults to `true`.
48
-
49
-
*`decodeStyleAttributes` - whether to decode the value of `style=` attributes. Defaults to `false`.
50
-
51
-
*`extraCss` - extra css to apply to the file. Defaults to `""`.
52
-
53
-
*`insertPreservedExtraCss` - whether to insert into the document any preserved `@media` or `@font-face` content from `extraCss` when using `preserveMediaQueries`, `preserveFontFaces` or `preserveKeyFrames`. When `true` order of preference to append the `<style>` element is into `head`, then `body`, then at the end of the document. When a `string` the value is treated as a CSS/jQuery/cheerio selector, and when found, the `<style>` tag will be appended to the end of the first match. Defaults to `true`.
54
-
55
-
*`inlinePseudoElements` - Whether to insert pseudo elements (`::before` and `::after`) as `<span>` into the DOM. *Note*: Inserting pseudo elements will modify the DOM and may conflict with CSS selectors elsewhere on the page (e.g., `:last-child`).
56
-
57
-
*`preserveFontFaces` - preserves all `@font-face` within `<style></style>` tags as a refinement when `removeStyleTags` is `true`. Other styles are removed. Defaults to `true`.
58
-
59
-
*`preserveImportant` - preserves `!important` in values. Defaults to `false`.
60
-
61
-
*`preserveMediaQueries` - preserves all media queries (and contained styles) within `<style></style>` tags as a refinement when `removeStyleTags` is `true`. Other styles are removed. Defaults to `true`.
62
-
63
-
*`preserveKeyFrames` - preserves all key frames within `<style></style>` tags as a refinement when `removeStyleTags` is `true`. Other styles are removed. Defaults to `true`.
64
-
65
-
*`preservePseudos` - preserves all rules containing pseudo selectors defined in `ignoredPseudos` within `<style></style>` tags as a refinement when `removeStyleTags` is `true`. Other styles are removed. Defaults to `true`.
66
-
67
-
*`removeStyleTags` - whether to remove the original `<style></style>` tags after (possibly) inlining the css from them. Defaults to `true`.
68
-
69
-
*`resolveCSSVariables` - whether to resolve CSS variables. Defaults to `true`.
70
-
71
-
*`webResources` - An options object that will be passed to [web-resource-inliner](https://www.npmjs.com/package/web-resource-inliner) for juice functions that will get remote resources (`juiceResources` and `juiceFile`). Defaults to `{}`.
72
-
73
-
*`xmlMode` - whether to output XML/XHTML with all tags closed. Note that the input *must* also be valid XML/XHTML or you will get undesirable results. Defaults to `false`.
74
-
40
+
All Juice methods take an options object that can contain any of these properties, though not every method uses all of these:
41
+
42
+
| Option | Default value | Description |
43
+
|--------|-------|------------|
44
+
|`applyAttributesTableElements`|`true`| Create attributes for styles in `juice.styleToAttribute` on elements set in `juice.tableElements`. |
45
+
|`applyHeightAttributes`|`true`| Use any CSS pixel heights to create `height` attributes on elements set in `juice.heightElements`. |
46
+
|`applyStyleTags`|`true`| Inline styles in `<style>` tags. |
47
+
|`applyWidthAttributes`|`true`| Use any CSS pixel widths to create `width` attributes on elements set in `juice.widthElements`. |
48
+
|`decodeStyleAttributes`|`false`| Decode the value of `style` attributes. |
49
+
|`extraCss`|`""`| Extra CSS to apply to the file. |
50
+
|`insertPreservedExtraCss`|`true`| Whether to insert into the document any preserved `@media` or `@font-face` content from `extraCss` when using `preserveMediaQueries`, `preserveFontFaces` or `preserveKeyFrames`. <br><br> When set to `true`, order of preference to append the `<style>` element is into `head`, then `body`, then at the end of the document. <br><br> When a `string` the value is treated as a CSS/jQuery/cheerio selector, and when found, the `<style>` tag will be appended to the end of the first match. |
51
+
|`inlinePseudoElements`|`false`| Insert pseudo elements (`::before` and `::after`) as `<span>` into the DOM. *Note*: Inserting pseudo elements will modify the DOM and may conflict with CSS selectors elsewhere on the page (e.g., `:last-child`). |
52
+
|`preserveFontFaces`|`true`| Preserve all `@font-face` within `<style>` tags as a refinement when `removeStyleTags` is `true`. Other styles are removed. |
53
+
|`preserveImportant`|`false`| Preserve `!important` in CSS values. |
54
+
|`preserveMediaQueries`|`true`| Preserve all media queries (and contained styles) within `<style>` tags as a refinement when `removeStyleTags` is `true`. Other styles are removed. |
55
+
|`preserveKeyFrames`|`true`| Preserve all key frames within `<style>` tags as a refinement when `removeStyleTags` is `true`. Other styles are removed. |
56
+
|`preservePseudos`|`true`| Preserve all rules containing pseudo selectors defined in `ignoredPseudos` within `<style>` tags as a refinement when `removeStyleTags` is `true`. Other styles are removed. |
57
+
|`removeStyleTags`|`true`| Remove the original `<style>` tags after (possibly) inlining their CSS content. |
|`webResources`|`{}`| An options object that will be passed to [web-resource-inliner](https://www.npmjs.com/package/web-resource-inliner) for Juice functions that will get remote resources (`juiceResources` and `juiceFile`). |
60
+
|`xmlMode`|`false`| Output XML/XHTML with all tags closed. Note that the input *must* also be valid XML/XHTML or you will get undesirable results. |
75
61
76
62
### Methods
77
63
78
64
#### juice(html [, options])
79
65
80
-
Returns string containing inlined HTML. Does not fetch remote resources.
66
+
Returns a string containing the HTML with inlined CSS.
81
67
82
-
*`html` - html string, accepts complete documents as well as fragments
68
+
Does not fetch remote resources.
69
+
70
+
*`html` - HTML string, accepts complete documents as well as fragments
Callback returns a string containing the HTML with inlined CSS.
88
+
89
+
Fetches remote resources.
98
90
99
-
*`filePath` - path to the html file to be juiced
91
+
*`filePath` - path to the HTML file to be Juiced
100
92
*`options` - see Options above
101
93
*`callback(err, html)`
102
94
-`err` - `Error` object or `null`
103
-
-`html` - inlined HTML
95
+
-`html` - (string) HTML with inlined CSS
104
96
105
97
#### juice.juiceDocument($ [, options])
106
98
107
-
This takes a cheerio instance and performs inlining in-place. Returns the
108
-
same cheerio instance. Does not fetch remote resources.
99
+
This takes a `cheerio` instance and performs inlining in-place. Returns the same `cheerio` instance.
100
+
Does not fetch remote resources.
109
101
110
-
*`$` - a cheerio instance, be sure to use the same cheerio version that juice uses
111
-
*`options` - optional, see Options above`
102
+
*`$` - a `cheerio` instance, be sure to use the same `cheerio` version that Juice uses
103
+
*`options` - (object) optional, see Options above
112
104
113
105
#### juice.inlineContent(html, css [, options])
114
106
115
-
This takes html and css and returns new html with the provided css inlined.
107
+
This takes HTML and CSS and returns new HTML with the provided CSS inlined.
108
+
116
109
It does not look at `<style>` or `<link rel="stylesheet">` elements at all.
117
110
118
-
*`html` - html string
119
-
*`css` - css string
120
-
*`options` - optional, see Options above
111
+
*`html` - HTML string
112
+
*`css` - CSS string
113
+
*`options` - (object) optional, see Options above
121
114
122
115
#### juice.inlineDocument($, css [, options])
123
116
124
-
Given a cheerio instance and css, this modifies the cheerio instance so that the provided css is inlined. It does not look at `<style>` or `<link rel="stylesheet">` elements at all.
117
+
Given a `cheerio` instance and CSS, this modifies the `cheerio` instance so that the provided CSS is inlined. It does not look at `<style>` or `<link rel="stylesheet">` elements at all.
125
118
126
-
*`$` - a cheerio instance, be sure to use the same cheerio version that juice uses
127
-
*`css` - css string
128
-
*`options` - optional, see Options above
119
+
*`$` - a `cheerio` instance, be sure to use the same `cheerio` version that juice uses
120
+
*`css` - CSS string
121
+
*`options` - (object) optional, see Options above
129
122
130
123
### Global settings
131
124
132
125
#### juice.codeBlocks
133
126
134
-
An object where each value has a `start` and `end` to specify fenced code blocks that should be ignored during parsing and inlining. For example, Handlebars (hbs) templates are `juice.codeBlocks.HBS = {start: '{{', end: '}}'}`. `codeBlocks` can fix problems where otherwise juice might interpret code like `<=` as HTML, when it is meant to be template language code. Note that `codeBlocks` is a dictionary which can contain many different code blocks, so don't do `juice.codeBlocks = {...}` do `juice.codeBlocks.myBlock = {...}`
127
+
Type: Object\
128
+
Default:
129
+
130
+
```js
131
+
{
132
+
EJS: { start:'<%', end:'%>' },
133
+
HBS: { start:'{{', end:'}}' }
134
+
}
135
+
```
136
+
137
+
An object where each value has a `start` and `end` to specify fenced code blocks that should be ignored during parsing and inlining.
138
+
139
+
For example, Handlebars (hbs) templates are `juice.codeBlocks.HBS = {start: '{{', end: '}}'}`. `codeBlocks` can fix problems where otherwise juice might interpret code like `<=` as HTML, when it is meant to be template language code.
140
+
141
+
Note that `codeBlocks` is a dictionary which can contain many different code blocks, so don't do `juice.codeBlocks = {...}` do `juice.codeBlocks.myBlock = {...}`
Array of elements that will not have styles inlined because they are not intended to render.
159
193
160
194
#### juiceClient.excludedProperties
161
195
162
-
Array of css properties that won't be inlined.
196
+
Type: Array\
197
+
Default: `[]`
198
+
199
+
Array of CSS properties that won't be inlined.
163
200
164
201
### Special markup
165
202
166
203
#### data-embed
167
-
When a `data-embed` attribute is present on a stylesheet `<link>` that has been inlined into the document as a `<style></style>` tag by the web-resource-inliner juice will not inline the styles and will not remove the `<style></style>` tags.
168
204
169
-
This can be used to embed email client support hacks that rely on css selectors into your email templates.
205
+
Add `data-embed` to any `<style>` tag to prevent Juice from inlining its CSS and removing it.
206
+
Can be used to embed email client support hacks that rely on CSS selectors into your email templates:
207
+
208
+
```html
209
+
<styledata-embed>
210
+
u+.body.your-class-name {
211
+
/* CSS here targets Gmail */
212
+
}
213
+
</style>
214
+
```
215
+
216
+
The `data-embed` attribute will be removed from the output HTML, but no inlining or style tag removal will take place:
217
+
218
+
```html
219
+
<style>
220
+
u+.body.your-class-name {
221
+
/* CSS here targets Gmail */
222
+
}
223
+
</style>
224
+
```
170
225
171
226
### CLI Options
172
227
@@ -176,8 +231,6 @@ For a listing of all available options, just type `juice -h`.
176
231
177
232
> Note that if you want to just type `juice` from the command line, you should `npm install juice -g` so it is globally available.
178
233
179
-
CLI Options:
180
-
181
234
The CLI should have all the above [options](#options) with the names changed from camel case to hyphen-delimited, so for example `extraCss` becomes `extra-css` and `webResources.scripts` becomes `web-resources-scripts`.
182
235
183
236
These are additional options not included in the standard `juice` options listed above:
@@ -192,12 +245,17 @@ Attempting to Browserify `require('juice')` fails because portions of Juice and
192
245
193
246
## License
194
247
195
-
MIT Licensed, see License.md
248
+
MIT Licensed, see [LICENSE.md](LICENSE.md).
196
249
197
250
### 3rd-party
198
251
199
-
- Uses [cheerio](https://github.com/cheeriojs/cheerio) for the underlying DOM
200
-
representation.
252
+
- Uses [cheerio](https://github.com/cheeriojs/cheerio) for the underlying DOM representation.
201
253
- Uses [mensch](https://github.com/brettstimmerman/mensch) to parse out CSS and
202
254
[Slick](https://github.com/subtleGradient/slick) to tokenize them.
203
255
- Icon by [UnheardSounds](http://unheardsounds.deviantart.com/gallery/26536908#/d2ngozi)
0 commit comments