UNPKG

4.52 kBMarkdownView Raw
1# inline-css [![npm](http://img.shields.io/npm/v/inline-css.svg?style=flat)](https://badge.fury.io/js/inline-css) [![Build Status](https://travis-ci.org/jonkemp/inline-css.svg?branch=master)](https://travis-ci.org/jonkemp/inline-css) [![Coverage Status](https://coveralls.io/repos/jonkemp/inline-css/badge.svg?branch=master&service=github)](https://coveralls.io/github/jonkemp/inline-css?branch=master)
2
3[![NPM](https://nodei.co/npm/inline-css.png?downloads=true)](https://nodei.co/npm/inline-css/)
4
5> Inline your CSS properties into the `style` attribute in an html file. Useful for emails.
6
7Inspired by the [juice](https://github.com/Automattic/juice) library.
8
9## Why inline-css instead of Juice?
10- Uses [cheerio](https://github.com/cheeriojs/cheerio) instead of jsdom
11- Works on Windows
12- Preserves Doctype
13- Modular
14- Gets your CSS automatically through style and link tags
15- Functions return [A+ compliant](https://promisesaplus.com/) Promises
16
17## How It Works
18
19This module takes html and inlines the CSS properties into the style attribute.
20
21`/path/to/file.html`:
22```html
23<html>
24<head>
25 <style>
26 p { color: red; }
27 </style>
28 <link rel="stylesheet" href="style.css">
29</head>
30<body>
31 <p>Test</p>
32</body>
33</html>
34```
35
36`style.css`
37```css
38p {
39 text-decoration: underline;
40}
41```
42
43Output:
44```html
45<html>
46<head>
47</head>
48<body>
49 <p style="color: red; text-decoration: underline;">Test</p>
50</body>
51</html>
52```
53
54## What is this useful for ?
55
56- HTML emails. For a comprehensive list of supported selectors see
57[here](http://www.campaignmonitor.com/css/)
58- Embedding HTML in 3rd-party websites.
59- 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.
60
61
62## Install
63
64Install with [npm](https://npmjs.org/package/inline-css)
65
66```
67npm install --save inline-css
68```
69
70## Usage
71
72```js
73var inlineCss = require('inline-css');
74var html = "<style>div{color:red;}</style><div/>";
75
76inlineCss(html, options)
77 .then(function(html) { console.log(html); });
78```
79
80## API
81
82### inlineCss(html, options)
83
84
85#### options.extraCss
86
87Type: `String`
88Default: `""`
89
90Extra css to apply to the file.
91
92
93#### options.applyStyleTags
94
95Type: `Boolean`
96Default: `true`
97
98Whether to inline styles in `<style></style>`.
99
100
101#### options.applyLinkTags
102
103Type: `Boolean`
104Default: `true`
105
106Whether to resolve `<link rel="stylesheet">` tags and inline the resulting styles.
107
108
109#### options.removeStyleTags
110
111Type: `Boolean`
112Default: `true`
113
114Whether to remove the original `<style></style>` tags after (possibly) inlining the css from them.
115
116
117#### options.removeLinkTags
118
119Type: `Boolean`
120Default: `true`
121
122Whether to remove the original `<link rel="stylesheet">` tags after (possibly) inlining the css from them.
123
124#### options.url
125
126Type: `String`
127Default: `filePath`
128
129How to resolve hrefs. Must be a string of one character or more. **Required**.
130
131Relative urls in links will have this value prepended to them. So these links:
132* `<a href="page-relative">Page</a>`
133* `<a href="/root-relative">Root</a>` <- _note leading /_
134
135
136With this option:
137```js
138inlineCss(html, { url: 'http://example.com/mushroom'})
139 .then(function(html) { console.log(html); });
140```
141
142Will result in
143
144* `<a href="http://example.com/mushroom/page-relative">Page</a>`
145* `<a href="http://example.com/root-relative">Root</a>`
146
147If you don't need this feature, simply set the property to a short string eg `{url: ' '}` (one space) and everything will work.
148
149#### options.preserveMediaQueries
150
151Type: `Boolean`
152Default: `false`
153
154Preserves all media queries (and contained styles) within `<style></style>` tags as a refinement when `removeStyleTags` is `true`. Other styles are removed.
155
156#### options.applyWidthAttributes
157
158Type: `Boolean`
159Default: `false`
160
161Whether to use any CSS pixel widths to create `width` attributes on elements.
162
163#### options.applyTableAttributes
164
165Type: `Boolean`
166Default: `false`
167
168Whether to apply the `border`, `cellpadding` and `cellspacing` attributes to `table` elements.
169
170#### options.removeHtmlSelectors
171
172Type: `Boolean`
173Default: `false`
174
175Whether to remove the `class` and `id` attributes from the markup.
176
177### cheerio options
178
179Options to passed to [cheerio](https://github.com/cheeriojs/cheerio).
180
181## Contributing
182
183See the [CONTRIBUTING Guidelines](https://github.com/jonkemp/inline-css/blob/master/CONTRIBUTING.md)
184
185## License
186
187MIT © [Jonathan Kemp](http://jonkemp.com)