hexo-yam/README.md

200 lines
7.4 KiB
Markdown
Raw Normal View History

2019-09-11 01:48:32 +00:00
# hexo-yam
2016-06-23 05:27:24 +00:00
2018-09-27 07:13:18 +00:00
[![npm version](https://badge.fury.io/js/hexo-yam.svg)](https://www.npmjs.com/package/hexo-yam)
2019-07-18 08:04:26 +00:00
[![Build Status](https://travis-ci.com/curbengh/hexo-yam.svg?branch=master)](https://travis-ci.com/curbengh/hexo-yam)
[![NPM Dependencies](https://david-dm.org/curbengh/hexo-yam.svg)](https://david-dm.org/curbengh/hexo-yam)
2018-09-28 02:24:17 +00:00
[![Known Vulnerabilities](https://snyk.io/test/npm/hexo-yam/badge.svg)](https://snyk.io/test/npm/hexo-yam)
2019-07-18 08:04:26 +00:00
[![Greenkeeper badge](https://badges.greenkeeper.io/curbengh/hexo-yam.svg)](https://greenkeeper.io/)
2018-09-27 07:13:18 +00:00
2019-07-18 08:04:26 +00:00
Yet Another Minifier for Hexo. Minify and compress HTML, JS, CSS and SVG. XML, JSON and [many more](https://github.com/curbengh/hexo-yam/blob/ba77db0094a7c07ea9f70f010bfc15541d4105ca/index.js#L64) are also compressed. Support gzip and [brotli](https://en.wikipedia.org/wiki/Brotli) [compressions](https://en.wikipedia.org/wiki/HTTP_compression).
2019-09-11 01:48:32 +00:00
## Version 3
In v3 onwards, this plugin is enabled by default. Most [options](#options) have changed and they are now under `minify:` option.
Example:
```
neat_svg:
plugins: [{cleanupIDs: false}]
```
2016-05-26 11:09:41 +00:00
2019-09-11 01:48:32 +00:00
needs to be updated to
```
minify:
svg:
plugins: [{cleanupIDs: false}]
```
2018-11-02 10:29:00 +00:00
2016-05-26 11:09:41 +00:00
## Installation
``` bash
$ npm install hexo-yam --save
2016-05-26 11:09:41 +00:00
```
2019-09-11 01:48:32 +00:00
## Options
2016-05-26 11:09:41 +00:00
``` yaml
2019-09-11 01:48:32 +00:00
minify:
enable: true
2016-05-26 11:23:57 +00:00
```
2019-09-11 01:48:32 +00:00
- **enable** - Enable the plugin. Defaults to `true`.
---
2016-05-26 11:23:57 +00:00
``` yaml
2019-09-11 01:48:32 +00:00
minify:
html:
enable: true
exclude:
2016-05-26 11:09:41 +00:00
```
- **enable** - Enable the plugin. Defaults to `true`.
2019-10-09 22:33:34 +00:00
- **priority** - Plugin's priority. Defaults to `10`. Set lower value to set higher priority and vice versa.
2018-10-25 10:14:33 +00:00
- **logger** - Verbose output. Defaults to `false`.
2019-07-10 02:20:23 +00:00
- **exclude** - Exclude files.
- Support one-liner, `exclude: [*.min.html, *.note.html]`.
- To exclude a file, double asterisk and the full path must be specified, `**/themes/typing/source/js/source.js`.
- `*source.js` also works, but it also excludes `resource.js`.
- Test glob pattern on the web using [Globtester](http://www.globtester.com/).
2019-08-07 23:38:51 +00:00
- **globOptions** - [micromatch options](https://github.com/micromatch/micromatch#options) to customise how glob patterns match files. Defaults to `{ basename: true }`, unless the pattern has a slash.
2018-10-26 05:06:58 +00:00
For more options, see [HTMLMinifier](https://github.com/kangax/html-minifier).
2019-09-11 01:48:32 +00:00
---
2016-05-26 11:09:41 +00:00
``` yaml
2019-09-11 01:48:32 +00:00
minify:
css:
enable: true
exclude:
- '*.min.css'
2016-05-26 11:09:41 +00:00
```
- **enable** - Enable the plugin. Defaults to `true`.
2019-10-09 22:33:34 +00:00
- **priority** - Plugin's priority. Defaults to `10`.
2018-10-25 10:14:33 +00:00
- **logger** - Verbose output. Defaults to `false`.
- **exclude** - Exclude files. Support wildcard pattern.
- **level** - Optimization level. Defaults to `2`.
2019-09-11 01:48:32 +00:00
- **globOptions** - See [`html:`](#options).
2019-04-23 04:01:04 +00:00
For more options, see [clean-css](https://github.com/jakubpawlowicz/clean-css).
2016-05-26 11:09:41 +00:00
2019-09-11 01:48:32 +00:00
---
2016-05-26 11:09:41 +00:00
``` yaml
2019-09-11 01:48:32 +00:00
minify:
js:
enable: true
exclude:
- '*.min.js'
2016-05-26 11:09:41 +00:00
```
- **enable** - Enable the plugin. Defaults to `true`.
2019-10-09 22:33:34 +00:00
- **priority** - Plugin's priority. Defaults to `10`.
2018-10-25 10:14:33 +00:00
- **logger** - Verbose output. Defaults to `false`.
- **exclude** - Exclude files. Support wildcard pattern.
2019-04-23 04:01:04 +00:00
- **compress** - Compress options.
- **mangle** - Mangle variable names. Defaults to `true`. Pass an object to specify [mangle options](https://github.com/terser-js/terser#mangle-options).
- **output** - Output options.
- To retain comments, `output: {comments: true}`.
2019-09-11 01:48:32 +00:00
- **globOptions** - See [`html:`](#options).
2018-10-25 10:14:33 +00:00
For more options, see [Terser](https://github.com/terser-js/terser).
2016-05-26 11:09:41 +00:00
2019-09-11 01:48:32 +00:00
---
2018-09-28 07:43:54 +00:00
2019-04-23 07:59:35 +00:00
``` yaml
2019-09-11 01:48:32 +00:00
minify:
svg:
enable: true
include:
- '*.svg'
- '!*.min.svg'
2019-04-23 07:59:35 +00:00
```
- **enable** - Enable the plugin. Defaults to `true`.
2019-10-09 22:33:34 +00:00
- **priority** - Plugin's priority. Defaults to `10`.
2019-04-23 07:59:35 +00:00
- **logger** - Verbose output. Defaults to `false`.
- **include** - Include files. Support wildcard pattern.
- Exclude `*.min.svg` by default.
2019-05-21 04:15:18 +00:00
- **plugins** - Plugin options.
2019-04-23 07:59:35 +00:00
- To retain comments, `plugins: [{removeComments: false}]`.
2019-09-11 01:48:32 +00:00
- **globOptions** - See [`html:`](#options).
2019-04-23 07:59:35 +00:00
For more options, see [svgo](https://github.com/svg/svgo).
2019-09-11 01:48:32 +00:00
---
2019-04-23 07:59:35 +00:00
2018-09-28 07:43:54 +00:00
``` yaml
2019-09-11 01:48:32 +00:00
minify:
gzip:
enable: true
include:
- '*.html'
- '*.css'
- '*.js'
- '*.txt'
- '*.ttf'
- '*.atom'
- '*.stl'
- '*.xml'
- '*.svg'
- '*.eot'
- '*.json'
2018-09-28 07:43:54 +00:00
```
- **enable** - Enable the plugin. Defaults to `true`.
2019-10-09 22:33:34 +00:00
- **priority** - Plugin's priority. Defaults to `10`.
2018-10-25 10:14:33 +00:00
- **logger** - Verbose output. Defaults to `false`.
- **include** - Include files. Support wildcard pattern.
- Support one-liner, `include: ['*.html','*.css','*.js']`.
- Must include asterisk and single quotes. `.html` is invalid. `'*.html'` is valid.
2019-09-11 01:48:32 +00:00
- **globOptions** - See [`html:`](#options).
2016-05-26 11:09:41 +00:00
2019-09-11 01:48:32 +00:00
---
2018-09-30 07:30:32 +00:00
``` yaml
2019-09-11 01:48:32 +00:00
minify:
brotli:
enable: true
include:
- '*.html'
- '*.css'
- '*.js'
- '*.txt'
- '*.ttf'
- '*.atom'
- '*.stl'
- '*.xml'
- '*.svg'
- '*.eot'
- '*.json'
2018-09-30 07:30:32 +00:00
```
- **enable** - Enable the plugin. Defaults to `true`.
2019-10-09 22:33:34 +00:00
- **priority** - Plugin's priority. Defaults to `10`.
2018-10-25 10:14:33 +00:00
- **logger** - Verbose output. Defaults to `false`.
- **include** - Include files. Support wildcard pattern.
2019-09-11 01:48:32 +00:00
- **globOptions** - See [`html:`](#options).
2018-09-30 07:30:32 +00:00
2018-11-02 10:29:00 +00:00
## HTTP Compression
While most modern web browsers [support Brotli](https://www.caniuse.com/#feat=brotli), you also need to consider whether the web/app server, hosting platform, reverse proxy or CDN (whichever relevant to you) support it.
2018-11-02 10:40:36 +00:00
As of May 2019, GitHub Pages, GitLab Pages and Netlify *do not* support brotli yet. You can generate `.br` files, but they won't serve those files.
2018-11-02 10:29:00 +00:00
Name | Status (May 8, 2019)
--- | ---
GitHub Pages | [In consideration](https://github.community/t5/GitHub-Pages/Support-for-pre-compressed-assets-and-brotli-compression/m-p/22055)
GitLab Pages | [In progress](https://gitlab.com/gitlab-org/gitlab-pages/merge_requests/120)
Netlify | [In consideration](https://postimg.cc/qgxn0261)
If you have access to the web server config, you should disable on-the-fly compression for static files (that are already compressed by this plugin),
2018-11-02 10:29:00 +00:00
- [nginx](https://github.com/google/ngx_brotli): Make sure both filter and static modules are enabled. This way pre-compressed `.br` files will be served while dynamic content can be compressed on-the-fly. Protip: `brotli_types text/plain text/css application/javascript application/json image/svg+xml application/xml+rss;` to prevent compressing media files (which are already compressed anyway).
- [Apache](https://httpd.apache.org/docs/2.4/en/mod/mod_brotli.html): See 'Serving pre-compressed content' section of [mod_brotli](https://httpd.apache.org/docs/2.4/en/mod/mod_brotli.html).
- [Caddy](https://caddyserver.com/features): [0.9.4+](https://caddyserver.com/blog/caddy-0_9_4-released) by default support pre-compressed `.gz` `.br` files and on-the-fly gzip compress dynamic files.
- [express](https://github.com/expressjs/express)/[connect](https://github.com/senchalabs/connect): Use [pre-compressed-assets](https://github.com/domadams/pre-compressed-assets). You still can continue to use [compression](https://github.com/expressjs/compression)/[shrink-ray-current](https://github.com/Alorel/shrink-ray) for dynamic files.
## Credits
All credits go to the following work:
- [hexo-neat](https://github.com/rozbo/hexo-neat) by rozbo
2016-05-26 11:23:57 +00:00
- neat html by [HTMLMinifier](https://github.com/kangax/html-minifier)
- neat css by [clean-css](https://github.com/jakubpawlowicz/clean-css)
2019-04-10 10:04:43 +00:00
- neat js by [terser](https://github.com/terser-js/terser)
- gzip feature is inspired by [hexo-generator-optimize](https://github.com/JackyRen/hexo-generator-optimize)