UNPKG

4.8 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## Features
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. **Required**.
130
131#### options.preserveMediaQueries
132
133Type: `Boolean`
134Default: `false`
135
136Preserves all media queries (and contained styles) within `<style></style>` tags as a refinement when `removeStyleTags` is `true`. Other styles are removed.
137
138#### options.applyWidthAttributes
139
140Type: `Boolean`
141Default: `false`
142
143Whether to use any CSS pixel widths to create `width` attributes on elements.
144
145#### options.applyTableAttributes
146
147Type: `Boolean`
148Default: `false`
149
150Whether to apply the `border`, `cellpadding` and `cellspacing` attributes to `table` elements.
151
152#### options.removeHtmlSelectors
153
154Type: `Boolean`
155Default: `false`
156
157Whether to remove the `class` and `id` attributes from the markup.
158
159#### options.codeBlocks
160
161Type: `Object`
162Default: `{ EJS: { start: '<%', end: '%>' }, HBS: { start: '{{', end: '}}' } }`
163
164An 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 `HBS: {start: '{{', end: '}}'}`. `codeBlocks` can fix problems where otherwise inline-css 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 `codeBlocks: {...}` do `codeBlocks.myBlock = {...}`.
165
166### Special markup
167
168#### data-embed
169
170When a data-embed attribute is present on a <style></style> tag, inline-css will not inline the styles and will not remove the <style></style> tags.
171
172This can be used to embed email client support hacks that rely on css selectors into your email templates.
173
174### cheerio options
175
176Options to passed to [cheerio](https://github.com/cheeriojs/cheerio).
177
178## Contributing
179
180See the [CONTRIBUTING Guidelines](https://github.com/jonkemp/inline-css/blob/master/CONTRIBUTING.md)
181
182## License
183
184MIT © [Jonathan Kemp](http://jonkemp.com)