hexo-yam/README.md

337 lines
9.9 KiB
Markdown
Raw Normal View History

2019-09-11 01:48:32 +00:00
# hexo-yam
2016-06-23 05:27:24 +00:00
2020-09-05 13:49:02 +00:00
[![npm version](https://img.shields.io/npm/v/hexo-yam?logo=npm)](https://www.npmjs.com/package/hexo-yam)
[![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)
2020-09-05 13:51:51 +00:00
[![codecov](https://img.shields.io/codecov/c/gh/curbengh/hexo-yam?logo=codecov)](https://codecov.io/gh/curbengh/hexo-yam)
[![NPM Dependencies](https://img.shields.io/librariesio/release/npm/hexo-yam)](https://libraries.io/npm/hexo-yam)
[![Known Vulnerabilities](https://snyk.io/test/github/curbengh/hexo-yam/badge.svg)](https://snyk.io/test/github/curbengh/hexo-yam)
2018-09-27 07:13:18 +00:00
Yet Another Minifier for Hexo. Minify HTML, JS, CSS, SVG, XML and JSON. Compress static [web assets](https://github.com/curbengh/hexo-yam/blob/ba77db0094a7c07ea9f70f010bfc15541d4105ca/index.js#L64) using gzip, brotli and zstd.
2019-12-29 03:51:02 +00:00
## Table of contents
- [Installation](#installation)
- [Options](#options)
- [HTML](#html)
- [CSS](#css)
- [JS](#js)
- [SVG](#svg)
- [XML](#xml)
- [JSON](#json)
2019-12-29 03:51:02 +00:00
- [Gzip](#gzip)
- [Brotli](#brotli)
- [Zstd](#zstd)
2019-12-29 03:51:02 +00:00
- [Globbing](#globbing)
2016-05-26 11:09:41 +00:00
## Installation
```bash
$ npm install --save hexo-yam
2016-05-26 11:09:41 +00:00
```
2019-09-11 01:48:32 +00:00
## Options
```yaml
2019-09-11 01:48:32 +00:00
minify:
enable: true
previewServer: true
2019-12-29 03:51:02 +00:00
html:
css:
js:
svg:
2020-09-05 14:05:10 +00:00
xml:
json:
gzip:
brotli:
zstd:
2016-05-26 11:23:57 +00:00
```
2019-09-11 01:48:32 +00:00
- **enable** - Enable the plugin. Defaults to `true`.
- **previewServer** - Disable the plugin when running `hexo server`. Defaults to `true`.
2019-12-29 03:51:02 +00:00
- **html** - See [HTML](#html) section
- **css** - See [CSS](#css) section
- **js** - See [JS](#js) section
- **svg** - See [SVG](#svg) section
2020-09-05 14:05:10 +00:00
- **xml** - See [XML](#xml) section
- **json** - See [JSON](#json) section
- **gzip** - See [Gzip](#gzip) section
- **brotli** - See [Brotli](#brotli) section
- **zstd** - See [Zstd](#zstd) section
2019-09-11 01:48:32 +00:00
2019-12-29 03:51:02 +00:00
## HTML
2019-09-11 01:48:32 +00:00
```yaml
2019-09-11 01:48:32 +00:00
minify:
html:
enable: true
exclude:
2016-05-26 11:09:41 +00:00
```
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.
- **verbose** - Verbose output. Defaults to `false`.
2019-12-29 03:51:02 +00:00
- **exclude** - Exclude files. Support [wildcard](http://www.globtester.com/) pattern(s) in a string or array.
- **globOptions** - See [globbing](#globbing) section.
2018-10-26 05:06:58 +00:00
For more options, see [HTMLMinifier](https://github.com/kangax/html-minifier).
2019-12-29 03:51:02 +00:00
## CSS
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
```
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`.
- **verbose** - Verbose output. Defaults to `false`.
2019-12-29 03:51:02 +00:00
- **exclude** - Exclude files. Support [wildcard](http://www.globtester.com/) pattern(s) in a string or array.
- **level** - Optimization level. Defaults to `2`.
2024-12-04 08:41:23 +00:00
- **sourceMap** - Source map options. Defaults to `false`.
- **mapIncludeSources** - Include sources in map, Defaults to `false`.
2019-12-29 03:51:02 +00:00
- **globOptions** - See [globbing](#globbing) section.
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-12-29 03:51:02 +00:00
## JS
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
```
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`.
- **verbose** - Verbose output. Defaults to `false`.
2019-12-29 03:51:02 +00:00
- **exclude** - Exclude files. Support [wildcard](http://www.globtester.com/) pattern(s) in a string or array.
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}`.
2024-12-04 08:41:23 +00:00
- **sourceMap** - Source map options. Defaults to `false`.
- To include sources in map, `sourceMap: { includeSources: true }`
2019-12-29 03:51:02 +00:00
- **globOptions** - See [globbing](#globbing) section.
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-12-29 03:51:02 +00:00
## SVG
2018-09-28 07:43:54 +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
```
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`.
- **verbose** - Verbose output. Defaults to `false`.
2019-12-29 03:51:02 +00:00
- **include** - Include files. Support [wildcard](http://www.globtester.com/) pattern(s) in a string or array.
2019-04-23 07:59:35 +00:00
- Exclude `*.min.svg` by default.
2019-05-21 04:15:18 +00:00
- **plugins** - Plugin options.
- Examples:
```yaml
plugins:
# Retain comments
removeComments: false
# Do not remove unused ID attributes
cleanupIds: false
```
- For more options, see [svgo](https://github.com/svg/svgo).
2019-12-29 03:51:02 +00:00
- **globOptions** - See [globbing](#globbing) section.
2019-04-23 07:59:35 +00:00
## XML
Remove whitespaces in xml.
```yaml
minify:
xml:
enable: false
include:
- "*.xml"
- "!*.min.xml"
```
- **enable** - Enable the plugin. Defaults to `false`.
- **priority** - Plugin's priority. Defaults to `10`.
- **verbose** - Verbose output. Defaults to `false`.
- **include** - Include files. Support [wildcard](http://www.globtester.com/) pattern(s) in a string or array.
- Exclude `*.min.xml` by default.
- **removeComments** - Remove [comments](https://developer.mozilla.org/en-US/docs/Web/XML/XML_introduction) in xml. Defaults to `true`.
- **globOptions** - See [globbing](#globbing) section.
For more options, see [minify-xml](https://github.com/kristian/minify-xml#options).
## JSON
Remove whitespaces in json.
```yaml
minify:
json:
enable: false
include:
- "*.json"
- "*.webmanifest"
- "!*.min.json"
- "!*.min.webmanifest"
```
- **enable** - Enable the plugin. Defaults to `false`.
- **priority** - Plugin's priority. Defaults to `10`.
- **verbose** - Verbose output. Defaults to `false`.
- **include** - Include files. Support [wildcard](http://www.globtester.com/) pattern(s) in a string or array.
- Exclude `*.min.json` by default.
- **globOptions** - See [globbing](#globbing) section.
2019-12-29 03:51:02 +00:00
## Gzip
2019-04-23 07:59:35 +00:00
```yaml
2019-09-11 01:48:32 +00:00
minify:
gzip:
enable: true
include:
- "*.html"
- "*.css"
- "*.js"
- "*.map"
- "*.wasm"
- "*.txt"
- "*.ttf"
- "*.atom"
- "*.stl"
- "*.xml"
- "*.svg"
- "*.eot"
- "*.json"
- "*.webmanifest"
2018-09-28 07:43:54 +00:00
```
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`.
- **verbose** - Verbose output. Defaults to `false`.
2019-12-29 03:51:02 +00:00
- **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.
2019-12-29 03:51:02 +00:00
- **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)
2016-05-26 11:09:41 +00:00
2019-12-29 03:51:02 +00:00
## Brotli
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"
- "*.map"
- "*.wasm"
- "*.txt"
- "*.ttf"
- "*.atom"
- "*.stl"
- "*.xml"
- "*.svg"
- "*.eot"
- "*.json"
- "*.webmanifest"
2018-09-30 07:30:32 +00:00
```
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`.
- **verbose** - Verbose output. Defaults to `false`.
2019-12-29 03:51:02 +00:00
- **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)
2018-09-30 07:30:32 +00:00
## Zstd
```yaml
minify:
zstd:
enable: false
include:
- "*.html"
- "*.css"
- "*.js"
- "*.map"
- "*.wasm"
- "*.txt"
- "*.ttf"
- "*.atom"
- "*.stl"
- "*.xml"
- "*.svg"
- "*.eot"
- "*.json"
- "*.webmanifest"
```
- **enable** - Enable the plugin. Defaults to `false`.
- **priority** - Plugin's priority. Defaults to `10`.
- **verbose** - Verbose output. Defaults to `false`.
- **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-22`. Defaults to `3`, or the value of [`DEFAULT_LEVEL`](https://github.com/mongodb-js/zstd/blob/a3a08c61c9045411c8275e248498dbc583457fb5/src/lib.rs#L9)
### Cannot find module '@mongodb-js/zstd-linux-x64-gnu'
`npm install --save @mongodb-js/zstd-linux-x64-gnu`
- @mongodb-js/zstd-darwin-arm64 (Apple Silicon)
- @mongodb-js/zstd-darwin-x64 (Intel Mac)
- @mongodb-js/zstd-linux-arm64-gnu
- @mongodb-js/zstd-linux-arm64-musl (Alpine)
- @mongodb-js/zstd-linux-x64-gnu
- @mongodb-js/zstd-linux-x64-musl (Alpine)
- @mongodb-js/zstd-win32-x64-msvc
2019-12-29 03:51:02 +00:00
## 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
2019-12-29 03:51:02 +00:00
exclude:
- "*foo.html" # basename is enabled
- "**/bar/*/*.html" # basename is automatically disabled
- "*baz.css" # basename is enabled
2019-12-29 03:51:02 +00:00
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,
2019-12-29 03:51:02 +00:00
```yml
2019-12-29 03:51:02 +00:00
include:
- "!foo.svg"
- "!**/bar/*/*.svg"
2019-12-29 03:51:02 +00:00
globOptions:
basename: true
```
- basename will stay disabled, if explicitly disabled in "globOptions".
## Credits
All credits go to the following work:
- [hexo-neat](https://github.com/rozbo/hexo-neat) by rozbo
2019-04-10 10:04:43 +00:00
- gzip feature is inspired by [hexo-generator-optimize](https://github.com/JackyRen/hexo-generator-optimize)