README.md

   1 # hexo-yam
   2
   3 [![npm version](https://img.shields.io/npm/v/hexo-yam?logo=npm)](https://www.npmjs.com/package/hexo-yam)
   4 [![Build Status](https://img.shields.io/github/actions/workflow/status/curbengh/hexo-yam/tester.yml?branch=master&logo=github)](https://github.com/curbengh/hexo-yam/actions?query=workflow%3ATester)
   5 [![codecov](https://img.shields.io/codecov/c/gh/curbengh/hexo-yam?logo=codecov)](https://codecov.io/gh/curbengh/hexo-yam)
   6 [![NPM Dependencies](https://img.shields.io/librariesio/release/npm/hexo-yam)](https://libraries.io/npm/hexo-yam)
   7 [![Known Vulnerabilities](https://img.shields.io/snyk/vulnerabilities/npm/hexo-yam?logo=snyk)](https://snyk.io/test/npm/hexo-yam)
   8
   9 Yet Another Minifier for Hexo. Minify and compress HTML, JS, CSS, SVG, XML and JSON. [Other files](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).
  10
  11
  12 ## Table of contents
  13
  14 - [Installation](#installation)
  15 - [Options](#options)
  16 - [HTML](#html)
  17 - [CSS](#css)
  18 - [JS](#js)
  19 - [SVG](#svg)
  20 - [Gzip](#gzip)
  21 - [Brotli](#brotli)
  22 - [XML](#xml)
  23 - [JSON](#json)
  24 - [Globbing](#globbing)
  25 - [HTTP Compression](#http-compression)
  26
  27 ## Installation
  28 ``` bash
  29 $ npm install hexo-yam --save
  30 ```
  31
  32 ## Options
  33
  34 ``` yaml
  35 minify:
  36   enable: true
  37   html:
  38   css:
  39   js:
  40   svg:
  41   gzip:
  42   brotli:
  43   xml:
  44   json:
  45 ```
  46
  47 - **enable** - Enable the plugin. Defaults to `true`.
  48 - **html** - See [HTML](#html) section
  49 - **css** - See [CSS](#css) section
  50 - **js** - See [JS](#js) section
  51 - **svg** - See [SVG](#svg) section
  52 - **gzip** - See [Gzip](#gzip) section
  53 - **brotli** - See [Brotli](#brotli) section
  54 - **xml** - See [XML](#xml) section
  55 - **json** - See [JSON](#json) section
  56
  57 ## HTML
  58
  59 ``` yaml
  60 minify:
  61   html:
  62     enable: true
  63     exclude:
  64 ```
  65 - **enable** - Enable the plugin. Defaults to `true`.
  66 - **priority** - Plugin's priority. Defaults to `10`. Set lower value to set higher priority and vice versa.
  67 - **verbose** - Verbose output. Defaults to `false`.
  68 - **exclude** - Exclude files. Support [wildcard](http://www.globtester.com/) pattern(s) in a string or array.
  69 - **globOptions** - See [globbing](#globbing) section.
  70
  71 For more options, see [HTMLMinifier](https://github.com/kangax/html-minifier).
  72
  73 ## CSS
  74
  75 ``` yaml
  76 minify:
  77   css:
  78     enable: true
  79     exclude:
  80       - '*.min.css'
  81 ```
  82 - **enable** - Enable the plugin. Defaults to `true`.
  83 - **priority** - Plugin's priority. Defaults to `10`.
  84 - **verbose** - Verbose output. Defaults to `false`.
  85 - **exclude** - Exclude files. Support [wildcard](http://www.globtester.com/) pattern(s) in a string or array.
  86 - **level** - Optimization level. Defaults to `2`.
  87 - **globOptions** - See [globbing](#globbing) section.
  88
  89 For more options, see [clean-css](https://github.com/jakubpawlowicz/clean-css).
  90
  91 ## JS
  92
  93 ``` yaml
  94 minify:
  95   js:
  96     enable: true
  97     exclude:
  98       - '*.min.js'
  99 ```
 100 - **enable** - Enable the plugin. Defaults to `true`.
 101 - **priority** - Plugin's priority. Defaults to `10`.
 102 - **verbose** - Verbose output. Defaults to `false`.
 103 - **exclude** - Exclude files. Support [wildcard](http://www.globtester.com/) pattern(s) in a string or array.
 104 - **compress** - Compress options.
 105 - **mangle** - Mangle variable names. Defaults to `true`. Pass an object to specify [mangle options](https://github.com/terser-js/terser#mangle-options).
 106 - **output** - Output options.
 107   - To retain comments, `output: {comments: true}`.
 108 - **globOptions** - See [globbing](#globbing) section.
 109
 110 For more options, see [Terser](https://github.com/terser-js/terser).
 111
 112 ## SVG
 113
 114 ``` yaml
 115 minify:
 116   svg:
 117     enable: true
 118     include:
 119       - '*.svg'
 120       - '!*.min.svg'
 121 ```
 122 - **enable** - Enable the plugin. Defaults to `true`.
 123 - **priority** - Plugin's priority. Defaults to `10`.
 124 - **verbose** - Verbose output. Defaults to `false`.
 125 - **include** - Include files. Support [wildcard](http://www.globtester.com/) pattern(s) in a string or array.
 126   - Exclude `*.min.svg` by default.
 127 - **plugins** - Plugin options.
 128   - Examples:
 129   ``` yaml
 130   plugins:
 131     # Retain comments
 132     removeComments: false
 133     # Do not remove unused ID attributes
 134     cleanupIds: false
 135   ```
 136   - For more options, see [svgo](https://github.com/svg/svgo).
 137 - **globOptions** - See [globbing](#globbing) section.
 138
 139 ## Gzip
 140
 141 ``` yaml
 142 minify:
 143   gzip:
 144     enable: true
 145     include:
 146       - '*.html'
 147       - '*.css'
 148       - '*.js'
 149       - '*.txt'
 150       - '*.ttf'
 151       - '*.atom'
 152       - '*.stl'
 153       - '*.xml'
 154       - '*.svg'
 155       - '*.eot'
 156       - '*.json'
 157 ```
 158 - **enable** - Enable the plugin. Defaults to `true`.
 159 - **priority** - Plugin's priority. Defaults to `10`.
 160 - **verbose** - Verbose output. Defaults to `false`.
 161 - **include** - Include files. Support [wildcard](http://www.globtester.com/) pattern(s) in a string or array.
 162   - Support one-liner, `include: ['*.html','*.css','*.js']`.
 163   - Must include asterisk and single quotes. `.html` is invalid. `'*.html'` is valid.
 164 - **globOptions** - See [globbing](#globbing) section.
 165 - **level** - Compression level; lower value may results in faster compression but slightly larger (compressed) file. Range `1-9`. Defaults to `9`, or the value of [`zlib.constants.Z_BEST_COMPRESSION`](https://nodejs.org/docs/latest-v12.x/api/zlib.html#zlib_zlib_constants)
 166
 167 ## Brotli
 168
 169 ``` yaml
 170 minify:
 171   brotli:
 172     enable: true
 173     include:
 174       - '*.html'
 175       - '*.css'
 176       - '*.js'
 177       - '*.txt'
 178       - '*.ttf'
 179       - '*.atom'
 180       - '*.stl'
 181       - '*.xml'
 182       - '*.svg'
 183       - '*.eot'
 184       - '*.json'
 185 ```
 186 - **enable** - Enable the plugin. Defaults to `true`.
 187 - **priority** - Plugin's priority. Defaults to `10`.
 188 - **verbose** - Verbose output. Defaults to `false`.
 189 - **include** - Include files. Support [wildcard](http://www.globtester.com/) pattern(s) in a string or array.
 190 - **globOptions** - See [globbing](#globbing) section.
 191 - **level** - Compression level. Range `1-11`. Defaults to `11`, or the value of [`zlib.constants.BROTLI_MAX_QUALITY`](https://nodejs.org/docs/latest-v12.x/api/zlib.html#zlib_brotli_constants)
 192
 193 ## XML
 194
 195 Remove whitespaces in xml.
 196
 197 ``` yaml
 198 minify:
 199   xml:
 200     enable: false
 201     include:
 202       - '*.xml'
 203       - '!*.min.xml'
 204 ```
 205 - **enable** - Enable the plugin. Defaults to `false`.
 206 - **priority** - Plugin's priority. Defaults to `10`.
 207 - **verbose** - Verbose output. Defaults to `false`.
 208 - **include** - Include files. Support [wildcard](http://www.globtester.com/) pattern(s) in a string or array.
 209   - Exclude `*.min.xml` by default.
 210 - **removeComments** - Remove [comments](https://developer.mozilla.org/en-US/docs/Web/XML/XML_introduction) in xml. Defaults to `true`.
 211 - **globOptions** - See [globbing](#globbing) section.
 212
 213 For more options, see [minify-xml](https://github.com/kristian/minify-xml#options).
 214
 215 ## JSON
 216
 217 Remove whitespaces in json.
 218
 219 ``` yaml
 220 minify:
 221   json:
 222     enable: false
 223     include:
 224       - '*.json'
 225       - '!*.min.json'
 226 ```
 227 - **enable** - Enable the plugin. Defaults to `false`.
 228 - **priority** - Plugin's priority. Defaults to `10`.
 229 - **verbose** - Verbose output. Defaults to `false`.
 230 - **include** - Include files. Support [wildcard](http://www.globtester.com/) pattern(s) in a string or array.
 231   - Exclude `*.min.json` by default.
 232 - **globOptions** - See [globbing](#globbing) section.
 233
 234 ## Globbing
 235
 236 Use "globOptions" to customise how glob patterns match files. Refer to [micromatch](https://github.com/micromatch/micromatch#options) for available options.
 237
 238 - basename is enabled by default, unless the pattern has a slash.
 239 - basename is disabled depending on each pattern.
 240 - This means the following options would work,
 241
 242 ``` yml
 243 exclude:
 244   - '*foo.html' # basename is enabled
 245   - '**/bar/*/*.html' # basename is automatically disabled
 246   - '*baz.css' # basename is enabled
 247 globOptions:
 248   basename: true # default
 249 ```
 250
 251 - This behaviour doesn't apply to pattern that starts with `!` (negation).
 252 - This limitation only applies to `include:` option used in svg, gzip and brotli.
 253 - This means the following options would *not* work,
 254
 255 ``` yml
 256 include:
 257   - '!foo.svg'
 258   - '!**/bar/*/*.svg'
 259 globOptions:
 260   basename: true
 261 ```
 262
 263 - basename will stay disabled, if explicitly disabled in "globOptions".
 264
 265
 266 ## HTTP Compression
 267
 268 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.
 269
 270 Brotli support as of May 2022:
 271
 272 Name | Brotli support
 273 --- | ---
 274 GitHub Pages | [In consideration](https://github.community/t5/GitHub-Pages/Support-for-pre-compressed-assets-and-brotli-compression/m-p/22055)
 275 GitLab Pages | Yes
 276 Netlify | Yes
 277 Hexo Server | [In progress](https://github.com/hexojs/hexo-server/pull/100)
 278
 279 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),
 280
 281 - [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. [v2.4.0+](https://github.com/caddyserver/caddy/releases/tag/v2.4.0-beta.2) requires specifying the [`precompressed`](https://caddyserver.com/docs/caddyfile/directives/file_server) option.
 282 - [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).
 283 - [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).
 284 - [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.
 285
 286 ## Credits
 287 All credits go to the following work:
 288 - [hexo-neat](https://github.com/rozbo/hexo-neat) by rozbo
 289 - gzip feature is inspired by [hexo-generator-optimize](https://github.com/JackyRen/hexo-generator-optimize)