diff --git a/README.md b/README.md index 30e2ed2..36639e2 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,21 @@ 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). + +## Table of contents + +- [Version 4](#version-4) +- [Installation](#installation) +- [Options](#options) +- [HTML](#html) +- [CSS](#css) +- [JS](#js) +- [SVG](#svg) +- [Gzip](#gzip) +- [Brotli](#brotli) +- [Globbing](#globbing) +- [HTTP Compression](#http-compression) + ## Version 4 In v4, `logger:` option has been renamed to `verbose:` @@ -37,11 +52,23 @@ $ npm install hexo-yam --save ``` yaml minify: enable: true + html: + css: + js: + svg: + gzip: + brotli: ``` - **enable** - Enable the plugin. Defaults to `true`. +- **html** - See [HTML](#html) section +- **css** - See [CSS](#css) section +- **js** - See [JS](#js) section +- **svg** - See [SVG](#svg) section +- **gzip** - See [Gzip](#gzip) section +- **brotli** - See [Brotli](#brotli) section ---- +## HTML ``` yaml minify: @@ -52,35 +79,12 @@ minify: - **enable** - Enable the plugin. Defaults to `true`. - **priority** - Plugin's priority. Defaults to `10`. Set lower value to set higher priority and vice versa. - **verbose** - Verbose output. Defaults to `false`. -- **exclude** - Exclude files. - - Support one-liner, `exclude: [*.min.html, *.note.html]`. - - Test glob pattern on the web using [Globtester](http://www.globtester.com/). -- **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. - - basename is disabled depending on each pattern. - - This means the following options would work, - ``` yml - exclude: - - '*foo.html' - - '**/bar/*/*.html' - globOptions: - basename: true # default - ``` - - This behaviour doesn't apply to pattern that starts with `!` (negation). - - This limitation only applies to `include:` option used in svg, gzip and brotli. - - This means the following options would *not* work, - ``` yml - include: - - '!foo.svg' - - '!**/bar/*/*.svg' - globOptions: - basename: true - ``` - - basename would stay disabled, if explicitly disabled in `globOptions:`. +- **exclude** - Exclude files. Support [wildcard](http://www.globtester.com/) pattern(s) in a string or array. +- **globOptions** - See [globbing](#globbing) section. For more options, see [HTMLMinifier](https://github.com/kangax/html-minifier). ---- +## CSS ``` yaml minify: @@ -92,13 +96,13 @@ minify: - **enable** - Enable the plugin. Defaults to `true`. - **priority** - Plugin's priority. Defaults to `10`. - **verbose** - Verbose output. Defaults to `false`. -- **exclude** - Exclude files. Support wildcard pattern. +- **exclude** - Exclude files. Support [wildcard](http://www.globtester.com/) pattern(s) in a string or array. - **level** - Optimization level. Defaults to `2`. -- **globOptions** - See [`html:`](#options). +- **globOptions** - See [globbing](#globbing) section. For more options, see [clean-css](https://github.com/jakubpawlowicz/clean-css). ---- +## JS ``` yaml minify: @@ -110,16 +114,16 @@ minify: - **enable** - Enable the plugin. Defaults to `true`. - **priority** - Plugin's priority. Defaults to `10`. - **verbose** - Verbose output. Defaults to `false`. -- **exclude** - Exclude files. Support wildcard pattern. +- **exclude** - Exclude files. Support [wildcard](http://www.globtester.com/) pattern(s) in a string or array. - **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}`. -- **globOptions** - See [`html:`](#options). +- **globOptions** - See [globbing](#globbing) section. For more options, see [Terser](https://github.com/terser-js/terser). ---- +## SVG ``` yaml minify: @@ -132,14 +136,14 @@ minify: - **enable** - Enable the plugin. Defaults to `true`. - **priority** - Plugin's priority. Defaults to `10`. - **verbose** - Verbose output. Defaults to `false`. -- **include** - Include files. Support wildcard pattern. +- **include** - Include files. Support [wildcard](http://www.globtester.com/) pattern(s) in a string or array. - Exclude `*.min.svg` by default. - **plugins** - Plugin options. - - To retain comments, `plugins: [{removeComments: false}]`. + - Example: to retain comments, `plugins: [{removeComments: false}]`. - For more options, see [svgo](https://github.com/svg/svgo). -- **globOptions** - See [`html:`](#options). +- **globOptions** - See [globbing](#globbing) section. ---- +## Gzip ``` yaml minify: @@ -161,13 +165,13 @@ minify: - **enable** - Enable the plugin. Defaults to `true`. - **priority** - Plugin's priority. Defaults to `10`. - **verbose** - Verbose output. Defaults to `false`. -- **include** - Include files. Support wildcard pattern. +- **include** - Include files. Support [wildcard](http://www.globtester.com/) pattern(s) in a string or array. - Support one-liner, `include: ['*.html','*.css','*.js']`. - Must include asterisk and single quotes. `.html` is invalid. `'*.html'` is valid. -- **globOptions** - See [`html:`](#options). +- **globOptions** - See [globbing](#globbing) section. - **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) ---- +## Brotli ``` yaml minify: @@ -189,11 +193,44 @@ minify: - **enable** - Enable the plugin. Defaults to `true`. - **priority** - Plugin's priority. Defaults to `10`. - **verbose** - Verbose output. Defaults to `false`. -- **include** - Include files. Support wildcard pattern. -- **globOptions** - See [`html:`](#options). +- **include** - Include files. Support [wildcard](http://www.globtester.com/) pattern(s) in a string or array. +- **globOptions** - See [globbing](#globbing) section. - **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) +## Globbing + +Use "globOptions" to customise how glob patterns match files. Refer to [micromatch](https://github.com/micromatch/micromatch#options) for available options. + +- basename is enabled by default, unless the pattern has a slash. +- basename is disabled depending on each pattern. +- This means the following options would work, + +``` yml +exclude: + - '*foo.html' # basename is enabled + - '**/bar/*/*.html' # basename is automatically disabled + - '*baz.css' # basename is enabled +globOptions: + basename: true # default +``` + +- This behaviour doesn't apply to pattern that starts with `!` (negation). +- This limitation only applies to `include:` option used in svg, gzip and brotli. +- This means the following options would *not* work, + +``` yml +include: + - '!foo.svg' + - '!**/bar/*/*.svg' +globOptions: + basename: true +``` + +- basename will stay disabled, if explicitly disabled in "globOptions". + + ## 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. 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.