mirror of
https://github.com/KevinMidboe/inline-html.git
synced 2025-10-29 17:40:29 +00:00
Change api to separate html file and string processing.
This commit is contained in:
Alexandre Gigliotti
142
README.md
142
README.md
@@ -8,39 +8,24 @@ Inline local assets referenced in an HTML document.
|
||||
[](https://david-dm.org/panosoft/inline-html)
|
||||
[](https://www.npmjs.com/package/inline-html)
|
||||
|
||||
## Installation
|
||||
This library parses HTML, embeds the contents of local assets that are referenced within that HTML, and returns a new inlined HTML string.
|
||||
|
||||
```sh
|
||||
npm install inline-html
|
||||
```
|
||||
The following HTML elements and CSS data types are inlined:
|
||||
|
||||
- Images - The source path is replaced with a datauri.
|
||||
|
||||
- Linked LESS stylesheets - The LESS is compiled and the result is inlined within a `<style>` element. Note that `@imports` are processed as well.
|
||||
|
||||
- CSS url data types - The reference path is replaced with a datauri. These can be used in linked stylesheets, style elements, and element style attributes.
|
||||
|
||||
## Usage
|
||||
|
||||
Reads an HTML file, embeds the contents of local assets that are referenced within that file, and returns the inlined `html` string.
|
||||
|
||||
The following elements and data types are inlined:
|
||||
|
||||
- LESS stylesheets - The LESS is compiled and the result is inlined within a `<style>` element.
|
||||
- CSS url data types - The reference path is replaced with a datauri. These can be used in linked stylesheets, style elements, and element style attributes.
|
||||
- Images - The source path is replaced with a datauri.
|
||||
|
||||
Assuming we have the following files:
|
||||
|
||||
- `index.html`
|
||||
|
||||
```html
|
||||
<link rel="stylesheet/less" href="main.less"/>
|
||||
<style>
|
||||
div { background-image: url('path/to/file'); }
|
||||
</style>
|
||||
<div style="background-image: url('path/to/file');"></div>
|
||||
<img src="path/to/file"/>
|
||||
```
|
||||
Assuming ...
|
||||
|
||||
- `main.less`
|
||||
|
||||
```css
|
||||
@import (inline) 'main.css';
|
||||
@import (less) 'main.css';
|
||||
div { background-image: url('path/to/file'); }
|
||||
```
|
||||
|
||||
@@ -50,57 +35,110 @@ Assuming we have the following files:
|
||||
@font-face { src: url('path/to/file'); }
|
||||
```
|
||||
|
||||
We can use `inline-html`:
|
||||
Then ...
|
||||
|
||||
```js
|
||||
var inlineHtml = require('inline-html');
|
||||
var co = require('co');
|
||||
var inline = require('inline-html');
|
||||
|
||||
inlineHtml('index.html').then(function (html) {
|
||||
// ...
|
||||
co(function * () {
|
||||
var html = `
|
||||
<link rel="stylesheet/less" href="main.less"/>
|
||||
<style> div { background-image: url('path/to/file'); } </style>
|
||||
<div style="background-image: url('path/to/file');"></div>
|
||||
<img src="path/to/file"/>
|
||||
`;
|
||||
html = yield inline.html(html);
|
||||
console.log(html);
|
||||
/**
|
||||
<style>
|
||||
@font-face { src: url('data:...'); }
|
||||
div { background-image: url('data:...'); }
|
||||
</style>
|
||||
<style> div { background-image: url('data:...'); } </style>
|
||||
<div style="background-image: url('data:...');"></div>
|
||||
<img src="data:..."/>
|
||||
*/
|
||||
});
|
||||
```
|
||||
|
||||
To create the following `html` string:
|
||||
## Installation
|
||||
|
||||
```html
|
||||
<style>
|
||||
@font-face { src: url('data:...'); }
|
||||
div { background-image: url('data:...'); }
|
||||
</style>
|
||||
<style>
|
||||
div { background-image: url('data:...'); }
|
||||
</style>
|
||||
<div style="background-image: url('data:...');"></div>
|
||||
<img src="data:..."/>
|
||||
```sh
|
||||
npm install inline-html
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
- [`inlineHtml`](#inlineHtml)
|
||||
- [`inline.html`](#html)
|
||||
- [`inline.file`](#file)
|
||||
- [`Results`](#results)
|
||||
|
||||
---
|
||||
|
||||
<a name="inlineHtml"/>
|
||||
### inlineHtml ( html [, options] )
|
||||
<a name="html"/>
|
||||
### inline.html ( html [, options] )
|
||||
|
||||
Reads an HTML file and embeds referenced local assets into the HTML.
|
||||
Parses an HTML string and embeds referenced local assets into the HTML.
|
||||
|
||||
Returns a `Promise` that is fulfilled with an `html` string or an instance of [`Results`](#Results) depending on the value of `options.verbose`.
|
||||
Returns a `Promise` that is fulfilled with an `html` string or an instance of [`Results`](#results) depending on the value of `options.verbose`.
|
||||
|
||||
__Arguments__
|
||||
|
||||
- `html` - An HTML string or a filename of an HTML file to inline. Relative file paths are resolved relative to `options.filename` if a string or the filename's directory if a filename.
|
||||
- `html` - An HTML string to inline.
|
||||
|
||||
|
||||
- `options`
|
||||
- `filename` - The filename used to resolve relative paths when `html` is a string. If `html` is a string and this option is not provided, relative paths will be resolved relative to the process's current working directory.
|
||||
- `filename` - The filename used to resolve relative paths. If this option is not provided, relative paths will be resolved relative to the process's current working directory.
|
||||
- `less` - An object containing LESS options to pass to the less compiler. Defaults to `{}`.
|
||||
- `verbose` - A boolean that determines the promises fulfillment value. Supported values are:
|
||||
- `true`: An instance of [`Results`](#Results).
|
||||
- `false`: An `html` string. (_default_)
|
||||
- `true`: An instance of [`Results`](#results).
|
||||
- `false`: An `html` string. (_Default_)
|
||||
|
||||
<a name="Results"/>
|
||||
__Results__
|
||||
__Example__
|
||||
|
||||
The `Promise` returned by this function is optionally fulfilled with a `results` object that has the following properties:
|
||||
```js
|
||||
co(function * () {
|
||||
var html = yield inline.html(`<img src="test.png">`);
|
||||
console.log(html); // <img src="data:...">
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
<a name="file"/>
|
||||
### inline.file ( filename [, options] )
|
||||
|
||||
Reads an HTML file and embeds referenced local assets into the HTML.
|
||||
|
||||
Returns a `Promise` that is fulfilled with an `html` string or an instance of [`Results`](#results) depending on the value of `options.verbose`.
|
||||
|
||||
__Arguments__
|
||||
|
||||
- `html` - A filename of an HTML file to inline. Relative file paths are resolved relative to the filename's directory.
|
||||
|
||||
|
||||
- `options`
|
||||
- `less` - An object containing LESS options to pass to the less compiler. Defaults to `{}`.
|
||||
- `verbose` - A boolean that determines the promises fulfillment value. Supported values are:
|
||||
- `true`: An instance of [`Results`](#results).
|
||||
- `false`: An `html` string. (_Default_)
|
||||
|
||||
__Example__
|
||||
|
||||
```js
|
||||
co(function * () {
|
||||
html = yield inline.file(`index.html`);
|
||||
console.log(html); // <img src="data:...">
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
<a name="results"/>
|
||||
### Results
|
||||
|
||||
The `Promise` returned by these functions is optionally fulfilled with a `results` object that has the following properties:
|
||||
|
||||
- `html` - The inlined html
|
||||
- `files` - An array of filenames for the local assets that were inlined.
|
||||
|
||||
Reference in New Issue
Block a user