1 | # [gulp](https://github.com/wearefractal/gulp)-inline-css [![Build Status](https://travis-ci.org/jonkemp/gulp-inline-css.svg?branch=master)](https://travis-ci.org/jonkemp/gulp-inline-css) [![Coverage Status](https://coveralls.io/repos/jonkemp/gulp-inline-css/badge.svg?branch=master&service=github)](https://coveralls.io/github/jonkemp/gulp-inline-css?branch=master)
|
2 |
|
3 | [![NPM](https://nodei.co/npm/gulp-inline-css.png?downloads=true)](https://nodei.co/npm/gulp-inline-css/)
|
4 |
|
5 | > Inline your CSS properties into the `style` attribute in an html file. Useful for emails.
|
6 |
|
7 | Inspired by the grunt plugin [grunt-inline-css](https://github.com/jgallen23/grunt-inline-css). Uses the [inline-css](https://github.com/jonkemp/inline-css) module.
|
8 |
|
9 | ## What's new in 3.0?
|
10 |
|
11 | - Uses Promises with [inline-css](https://github.com/jonkemp/inline-css) version 2.0
|
12 |
|
13 | ## How It Works
|
14 |
|
15 | This gulp plugin takes an html file and inlines the CSS properties into the style attribute.
|
16 |
|
17 | `/path/to/file.html`:
|
18 | ```html
|
19 | <html>
|
20 | <head>
|
21 | <style>
|
22 | p { color: red; }
|
23 | </style>
|
24 | <link rel="stylesheet" href="style.css">
|
25 | </head>
|
26 | <body>
|
27 | <p>Test</p>
|
28 | </body>
|
29 | </html>
|
30 | ```
|
31 |
|
32 | `style.css`
|
33 | ```css
|
34 | p {
|
35 | text-decoration: underline;
|
36 | }
|
37 | ```
|
38 |
|
39 | Output:
|
40 | ```html
|
41 | <html>
|
42 | <head>
|
43 | </head>
|
44 | <body>
|
45 | <p style="color: red; text-decoration: underline;">Test</p>
|
46 | </body>
|
47 | </html>
|
48 | ```
|
49 |
|
50 | ## What is this useful for ?
|
51 |
|
52 | - HTML emails. For a comprehensive list of supported selectors see
|
53 | [here](http://www.campaignmonitor.com/css/)
|
54 | - Embedding HTML in 3rd-party websites.
|
55 | - Performance. Downloading external stylesheets delays the rendering of the page in the browser. Inlining CSS speeds up this process because the browser doesn't have to wait to download an external stylesheet to start rendering the page.
|
56 |
|
57 |
|
58 | ## Install
|
59 |
|
60 | Install with [npm](https://npmjs.org/package/gulp-inline-css)
|
61 |
|
62 | ```
|
63 | npm install --save-dev gulp-inline-css
|
64 | ```
|
65 |
|
66 |
|
67 | ## Usage
|
68 |
|
69 | ```js
|
70 | var gulp = require('gulp'),
|
71 | inlineCss = require('gulp-inline-css');
|
72 |
|
73 | gulp.task('default', function() {
|
74 | return gulp.src('./*.html')
|
75 | .pipe(inlineCss())
|
76 | .pipe(gulp.dest('build/'));
|
77 | });
|
78 | ```
|
79 |
|
80 | With options:
|
81 |
|
82 | ```js
|
83 | var gulp = require('gulp'),
|
84 | inlineCss = require('gulp-inline-css');
|
85 |
|
86 | gulp.task('default', function() {
|
87 | return gulp.src('./*.html')
|
88 | .pipe(inlineCss({
|
89 | applyStyleTags: true,
|
90 | applyLinkTags: true,
|
91 | removeStyleTags: true,
|
92 | removeLinkTags: true
|
93 | }))
|
94 | .pipe(gulp.dest('build/'));
|
95 | });
|
96 | ```
|
97 |
|
98 | Options are passed directly to [inline-css](https://github.com/jonkemp/inline-css).
|
99 |
|
100 |
|
101 | ## API
|
102 |
|
103 | ### inlineCss(options)
|
104 |
|
105 |
|
106 | #### options.extraCss
|
107 |
|
108 | Type: `String`
|
109 | Default: `""`
|
110 |
|
111 | Extra css to apply to the file.
|
112 |
|
113 |
|
114 | #### options.applyStyleTags
|
115 |
|
116 | Type: `Boolean`
|
117 | Default: `true`
|
118 |
|
119 | Whether to inline styles in `<style></style>`.
|
120 |
|
121 |
|
122 | #### options.applyLinkTags
|
123 |
|
124 | Type: `Boolean`
|
125 | Default: `true`
|
126 |
|
127 | Whether to resolve `<link rel="stylesheet">` tags and inline the resulting styles.
|
128 |
|
129 |
|
130 | #### options.removeStyleTags
|
131 |
|
132 | Type: `Boolean`
|
133 | Default: `true`
|
134 |
|
135 | Whether to remove the original `<style></style>` tags after (possibly) inlining the css from them.
|
136 |
|
137 |
|
138 | #### options.removeLinkTags
|
139 |
|
140 | Type: `Boolean`
|
141 | Default: `true`
|
142 |
|
143 | Whether to remove the original `<link rel="stylesheet">` tags after (possibly) inlining the css from them.
|
144 |
|
145 |
|
146 | #### options.url
|
147 |
|
148 | Type: `String`
|
149 | Default: `filePath`
|
150 |
|
151 | How to resolve hrefs.
|
152 |
|
153 | #### options.preserveMediaQueries
|
154 |
|
155 | Type: `Boolean`
|
156 | Default: `false`
|
157 |
|
158 | Preserves all media queries (and contained styles) within `<style></style>` tags as a refinement when `removeStyleTags` is `true`. Other styles are removed.
|
159 |
|
160 | #### options.applyWidthAttributes
|
161 |
|
162 | Type: `Boolean`
|
163 | Default: `false`
|
164 |
|
165 | Whether to use any CSS pixel widths to create `width` attributes on elements.
|
166 |
|
167 | #### options.applyTableAttributes
|
168 |
|
169 | Type: `Boolean`
|
170 | Default: `false`
|
171 |
|
172 | Whether to apply the `border`, `cellpadding` and `cellspacing` attributes to `table` elements.
|
173 |
|
174 | #### options.removeHtmlSelectors
|
175 |
|
176 | Type: `Boolean`
|
177 | Default: `false`
|
178 |
|
179 | Whether to remove the `class` and `id` attributes from the markup.
|
180 |
|
181 | ### cheerio options
|
182 |
|
183 | Options to passed to [cheerio](https://github.com/cheeriojs/cheerio).
|
184 |
|
185 | ## License
|
186 |
|
187 | MIT © [Jonathan Kemp](http://jonkemp.com)
|