Skip to content

Commit a22c17e

Browse files
AntonioRedondoAntonioRedondo
authored
Readme.md updated.
1 parent e773d40 commit a22c17e

1 file changed

Lines changed: 84 additions & 60 deletions

File tree

‎README.md‎

Lines changed: 84 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -1,50 +1,49 @@
1-
Inline SVG extension for the HTML Webpack Plugin
1+
html-webpack-inline-svg-plugin
22
========================================
33
[![npm version](https://badge.fury.io/js/html-webpack-inline-svg-plugin.svg)](https://badge.fury.io/js/html-webpack-inline-svg-plugin) [![Build status](https://travis-ci.org/theGC/html-webpack-inline-svg-plugin.svg)](https://travis-ci.org/theGC/html-webpack-inline-svg-plugin)
44

5-
#### Convert .svg files into inline SVG tags within the output html of templates parsed by [html-webpack-plugin](https://github.com/ampedandwired/html-webpack-plugin).
5+
Converts .svg files into inlined `<svg>` tags within the output html of templates parsed by [html-webpack-plugin](https://github.com/ampedandwired/html-webpack-plugin).
66

7-
**Readme Index**
87

9-
* [Versions](#versions)
10-
* [Overview](#overview)
11-
* [Installation](#installation)
12-
* [Usage](#usage)
13-
* [Getting to your SVGs](#getting-to-your-svgs)
14-
* [Sample Project Structure](#sample-project-structure)
15-
* [Default Config (not setting `runPreEmit` option)](#default-config-not-setting-runpreemit-option)
16-
* [Setting `runPreEmit` option](#setting-runpreemit-option)
17-
* [Config](#config)
18-
* [Features](#features)
19-
* [Known Issues](#known-issues)
20-
* [Contribution](#contribution)
21-
* [License](#license)
8+
## Table of Contents
229

23-
## Webpack Support
10+
1. [Overview](#overview)
11+
1. [Features](#features)
12+
1. [Installation](#installation)
13+
1. [Usage](#usage)
14+
1. [Getting To Your SVGs](#getting-to-your-svgs)
15+
1. [Sample Project Structure](#sample-project-structure)
16+
1. [Default Config (not setting `runPreEmit` option)](#default-config-not-setting-runpreemit-option)
17+
1. [Incorrect File Paths And URLs](#incorrect-file-paths-and-urls)
18+
1. [Duplicated Attributes](#duplicated-attributes)
19+
1. [Config](#config)
20+
1. [Versions](#versions)
21+
1. [Contribution](#contribution)
22+
1. [License](#license)
2423

25-
The latest version of this package supports webpack 4. All versions marked v2.x.x will target webpack 4 and html-webpack-plugin v4.
2624

27-
For webpack 3 and html-webpack-plugin v3 support use v1.3.0 of this package.
28-
29-
### v2.x.x
30-
Support webpack v4
31-
Support html-webpack-plugin v4
32-
33-
### v1.3.0
34-
Support webpack v3
35-
Support html-webpack-plugin v3
36-
37-
# Overview
25+
## Overview
3826

3927
By inlining SVGs you can combine them with techniques such as: [Icon System with SVG Sprites](https://css-tricks.com/svg-sprites-use-better-icon-fonts/).
4028

4129
As of version 1.0.0 **by default** this plugin processes SVG files after all template and image files have been written to their corresponding output directory. This allows it to work alongside loaders, after webpack resolves all file locations.
4230

43-
> Please note: to use **aliases** you will need to install loaders to resolve your svg paths and parse the templates html. More info is provided below: [Getting to your SVGs](#getting-to-your-svgs).
31+
> Please note: to use **aliases** you will need to install loaders to resolve your svg paths and parse the templates html. More info is provided below: [Getting To Your SVGs](#getting-to-your-svgs).
4432
4533
**As of version 1.1.0** the plugin can also be run prior to the output of your templates. This allows you to reference image files from the root of your project which can help with getting to certain files, i.e. within your `node_modules` directory. More info is provided below: [Setting runPreEmit option](#setting-runpreemit-option).
4634

47-
The plugin relies on [svgo](https://github.com/svg/svgo) to optimise SVGs. You can configure it's settings, check [config](#config) for more details.
35+
The plugin relies on [svgo](https://github.com/svg/svgo) to optimise SVGs. You can configure it's settings, check [Config](#config) for more details.
36+
37+
38+
## Features
39+
40+
* Optimises/minimizes the output SVG.
41+
* Allows for deep nested SVGs.
42+
* Supports webpack aliases for file locations.
43+
* Ignores broken tags (in case you are outputting templates for various parts of the page).
44+
* Performs no html decoding (supports language tags, i.e. `<?php echo 'foo bar'; ?>`).
45+
* Can load image files locally and from an online URL with the `allowFromUrl` option.
46+
4847

4948
## Installation
5049

@@ -53,7 +52,7 @@ Install the plugin with npm:
5352
$ npm install --save-dev html-webpack-inline-svg-plugin
5453
```
5554

56-
**or** [yarn](https://yarnpkg.com/):
55+
or [Yarn](https://yarnpkg.com/):
5756
```shell
5857
$ yarn add html-webpack-inline-svg-plugin --dev
5958
```
@@ -88,32 +87,35 @@ Add `img` tags with `inline` attribute and `.svg` file as src to your template/s
8887
<img inline src="images/i-will-be-ignored.png">
8988
```
9089

91-
### Getting to your SVGs
90+
### Getting To Your SVGs
9291

9392
> Breaking change: As of version 1.0.0 the plugin waits for webpack to resolve image locations and write them to disk. If you were using a version prior to 1.0.0 then it is likely you'll need to update the src paths to your inline SVGs to reflect this change. See below for more info.
9493
95-
There are **three ways** of working with your `<img>` **src** attributes and this plugin.
94+
There are three ways of working with your `<img>` **src** attributes and this plugin:
95+
96+
1. If you are **not working with loaders** to allow webpack to parse and resolve the `img` tags `src` attributes within your *html-webpack-plugin* templates. Use paths that are relative to your **svg** images from the **output** location of the template that is referencing it.
97+
98+
1. **Alternatively use loaders** such as [html-loader](https://github.com/webpack-contrib/html-loader) to parse the html templates, and [file-loader](https://github.com/webpack-contrib/file-loader) or something similar, to resolve the paths of your `img` tags `src` attributes. As the plugin works after webpack has emitted all its assets and *html-webpack-plugin* has output your templates, it will read the SVGs that webpack places in your output directory, and replace any **inlined img tags** with this content.
9699

97-
1. If you are **not working with loaders** to allow webpack to parse and resolve the `img` tags `src` attributes within your *html-webpack-plugin* templates. Use paths that are relative to your **svg** images from the **output** location of the template that is referencing it.
98-
2. **Alternatively use loaders** such as [html-loader](https://github.com/webpack-contrib/html-loader) to parse the html templates, and [file-loader](https://github.com/webpack-contrib/file-loader) or something similar, to resolve the paths of your `img` tags `src` attributes. As the plugin works after webpack has emitted all its assets and *html-webpack-plugin* has output your templates, it will read the SVGs that webpack places in your output directory, and replace any **inlined img tags** with this content.
99-
3. **Set the `runPreEmit` flag** and reference files relative to your `package.json` file. This feature is only available with version >= 1.1.0. More info is provided below: [Setting runPreEmit option](#setting-runpreemit-option).
100+
1. **Set the `runPreEmit` flag** and reference files relative to your `package.json` file. This feature is only available with version >= 1.1.0. More info is provided below: [Setting runPreEmit option](#setting-runpreemit-option).
100101

101-
#### Sample Project Structure
102+
103+
### Sample Project Structure
102104

103105
```
104106
my-project
105-
-- package.json
106-
-- webpack-config.js
107-
-- <node_modules>
108-
-- <src>
109-
---- index.html
110-
---- <images>
111-
------ icons.svg
112-
------ foo.svg
107+
├── package.json
108+
├── webpack-config.js
109+
├── node_modules
110+
└── src
111+
├── index.html
112+
└── images
113+
├── icons.svg
114+
└── foo.svg
113115
```
114116

115-
#### Default Config (not setting `runPreEmit` option)
116-
With the above structure inlining icons.svg would look like:
117+
### Default Config (not setting `runPreEmit` option)
118+
With the above structure inlining `icons.svg` would look like:
117119
```html
118120
<img inline src="images/icons.svg">
119121
```
@@ -124,10 +126,10 @@ If an alias was in place for the images directory, i.e.
124126
```
125127
Then the svg can be inlined with: `<img inline src="~img/icons.svg">`. This method would require the use of **loaders** on your templates as shown above in point 2.
126128

127-
#### Incorrect file paths or URLs
129+
### Incorrect file paths and URLs
128130
If for any reason the path to a local SVG file is incorrect, or the file fails to be read, or an image retrieved with an URL fails to download, the webpack build process will fail with an error, like `ENOENT`.
129131

130-
#### Duplicated attributes
132+
### Duplicated attributes
131133
All the attributes of a `<img/>` element excepting `src` and `inline` will be copied to the inlined `<svg/>` element. Attributes like `id` or `class` will be copied to the resulting root of the `<svg/>` element and if the original SVG file already had these attributes they will be duplicated (and not replaced) on the resulting `<svg/>` element, though the attributes coming from the `<img/>` will appear first and [any subsequent duplicated attribute from the original SVG will be ignored by the browser](https://stackoverflow.com/questions/26341507/can-an-html-element-have-the-same-attribute-twice).
132134

133135
For example:
@@ -146,9 +148,10 @@ will result in:
146148

147149
The broswer will use `id=""myImageIMG"` and not `id="myImageSVG"`. It's however a better approach if you avoid having any duplicated attribute at all and only putting the required ones on the `<img>` element.
148150

149-
## Config options
150151

151-
The plugin accepts three options:
152+
## Config
153+
154+
The plugin accepts the below options:
152155

153156
- `runPreEmit`: defaults to `false`. If you aren't using **loaders** to resolve file locations, and would prefer to reference image paths relative to the **root** of your project (where your `package.json` file resides) then set the plugins `runPreEmit` config option to `true`:
154157

@@ -170,6 +173,7 @@ The plugin accepts three options:
170173
```
171174

172175
- `inlineAll`: defaults to `false`. It will inline all SVG images on the template without the need of the `inline` attribute on every image:
176+
173177
```javascript
174178
plugins: [
175179
new HtmlWebpackPlugin(),
@@ -188,8 +192,19 @@ The plugin accepts three options:
188192
</div>
189193
```
190194

191-
- `allowFromUrl`: defaults to `false`. It allows to use SVG images coming from an URL online in addition to local files. For example:
195+
- `allowFromUrl`: defaults to `false`. It allows to use SVG images coming from an URL online in addition to local files:
192196

197+
```javascript
198+
plugins: [
199+
new HtmlWebpackPlugin(),
200+
new HtmlWebpackInlineSVGPlugin({
201+
allowFromUrl: true
202+
})
203+
]
204+
```
205+
206+
For example:
207+
193208
```html
194209
<div>
195210
<img inline src="https://badge.fury.io/js/html-webpack-inline-svg-plugin.svg"> <!-- it will be inlined from the online SVG -->
@@ -212,20 +227,29 @@ The plugin accepts three options:
212227

213228
For a full list of the SVGO config (default) params we are using check out: [svgo-config.js](svgo-config.js). The config you set is merged with our defaults, it does not replace it.
214229

215-
## Features
216230

217-
* Optimises / minimizes the output SVG
218-
* Allows for deep nested SVGs
219-
* Supports webpack aliases for file locations
220-
* Ignores broken tags - incase you are outputting templates for various parts of the page
221-
* Performs no html decoding so supports language tags, i.e. `<?php echo 'foo bar'; ?>`
231+
## Versions
232+
233+
The latest version of this package supports webpack 4. All versions marked v2.x.x will target webpack 4 and html-webpack-plugin v4.
234+
235+
For webpack 3 and html-webpack-plugin v3 support use v1.3.0 of this package.
236+
237+
### v2.x.x
238+
- Support webpack v4.
239+
- Support html-webpack-plugin v4.
240+
241+
### v1.3.0
242+
- Support webpack v3.
243+
- Support html-webpack-plugin v3.
244+
222245

223246
## Contribution
224247

225248
You're free to contribute to this project by submitting issues and/or pull requests. This project is test-driven, so keep in mind that every change and new feature should be covered by tests.
226249

227250
I'm happy for someone to take over the project as I don't find myself using it anylonger due to changes in workflow. Therefore others are likely in a better position to support this project and roll out the right enhancements.
228251

252+
229253
## License
230254

231-
This project is licensed under [MIT](https://github.com/theGC/html-webpack-inline-svg-plugin/blob/master/LICENSE).
255+
This project is licensed under [MIT](https://github.com/theGC/html-webpack-inline-svg-plugin/blob/master/LICENSE).

0 commit comments

Comments
 (0)