Skip to content

Setting up a minifier plugin

Introduction

Even today, when most of us have quite fast internet connection, page size still matters to over feeling of fast page load and as one of the factors of SEO. For that reason, a good publishing tool, should allow optimizing image size and (less important) page code size optimization. Publisher for MkDocs has that ability, but it does not introduce new optimization algorithms, etc. It's using tools that are created by others and considered stable with a good performance, etc.

Installation

To simplify the entire process, below is presented a single way of installation of all the tools. If you just want to use a single tool or learn more about what tool is used for what type of file, please take a look below for a configuration section where it's described.

In macOS, the easiest way to install any software, is to use a Homebrew . You have to install it before. All the instructions can be found on project web page. 

brew install pngquant oxipng mozjpeg node
npm install -f --no-fund svgo html-minifier postcss cssnano postcss-svgo postcss-cli uglify-js

brew install pngquant oxipng

brew install mozjpeg

brew install node
npm install -f --no-fund svgo

brew install node
npm install -f --no-fund html-minifier

brew install node
npm install -f --no-fund postcss cssnano postcss-svgo postcss-cli

brew install node
npm install -f --no-fund uglify-js

In Windows, the easiest way to install any software, is to use Scoop . You have to install it before. All the instructions can be found on project web page. 

scoop bucket add main
scoop install pngquant oxipng mozjpeg nodejs
npm install -f --no-fund svgo html-minifier postcss cssnano postcss-svgo postcss-cli uglify-js

scoop install pngquant oxipng

scoop install mozjpeg

scoop install nodejs
npm install -f --no-fund svgo

scoop install nodejs
npm install -f --no-fund html-minifier

scoop install nodejs
npm install -f --no-fund postcss cssnano postcss-svgo postcss-cli

scoop install nodejs
npm install -f --no-fund uglify-js

In Ubuntu, the easiest way to install any software, is to use a built-in packages manager called apt . 

sudo apt update
sudo apt install -y rustc pngquant libjpeg-turbo-progs nodejs
cargo install oxipng
npm install --no-fund -f svgo html-minifier postcss cssnano postcss-svgo postcss-cli uglify-js

sudo apt update
sudo apt install -y rustc pngquant
cargo install oxipng

sudo apt update
sudo apt install -y libjpeg-turbo-progs

sudo apt update
sudo apt install nodejs
npm install --no-fund -f svgo

sudo apt update
sudo apt install nodejs
npm install --no-fund -f html-minifier

sudo apt update
sudo apt install nodejs
npm install --no-fund -f postcss cssnano postcss-svgo postcss-cli

sudo apt update
sudo apt install nodejs
npm install --no-fund -f uglify-js

Configuration

To enable the built-in optimization plugin, the following lines have to be added to mkdocs.yml file: 

plugins:
  - pub-minifier

Just like that, all optimization tools are enabled with optimal settings (according to my small experiments).

General

Advanced settings

In day to day usage, those settings should be considered as advanced and probably shouldn't be changed. Those options are exposed, so you can adjust some settings offered by a given tool, but you should test those options locally. 

plugins:
  - pub-minifier:
      cache_enabled: true
      cache_dir: .pub_min_cache
      cache_file: .cache_files_list.yml
      exclude: []
      threads: 0

By default, this directory is created on the same level as docs directory and the directory structure looks like this: 

    .
    ├─ .pub_min_cache/
    │  └─ .cache_files_list.yml
    ├─ docs/
    └─ mkdocs.yml
cache_enabled

Control if caching mechanism is enabled. When it's enabled, you can still disable cache per each file type.

cache_dir

Defines the directory location, where the cached files are stored.

cache_file

Defines the name of the file, where all the data needed for proper cache working is stored. When this file is missing or corrupt, it and all cached files will be recreated. This file is stored inside the cache directory, and by default, the directory structure looks like this:

exclude

Defines a list of exclusion patterns for files or directories that will not be minified. Each file type has its own exclusion list that inherits values from this one, so you don't have to add the same values.

threads

File optimization process is a CPU intensive. Most modern computers have processors with multiple CPU cores. Each core can be used to optimize a single file. When your machine has more than one CPU core, it's good to have an ability to utilize all of them during the optimization process because it will reduce overall time needed for optimization of all files. This setting defines how many CPUs the plugin will use for file optimization process. If set to 0 (default value) the plugin will read the number of available CPUs from system settings.

JPEG optimization

JPEG image file size optimizations are done using MozJPEG tool. As we can read on the project website:

MozJPEG

MozJPEG improves JPEG compression efficiency, achieving higher visual quality and smaller file sizes at the same time. It is compatible with the JPEG standard, and the vast majority of the world's deployed JPEG decoders.

Using this tool reduces JPEG image file size up to 30% with almost no visible quality degradation. You can always try to change it by modification of default settings. Please have in mind that default values were set after my personal experiments and not always can be the most optimal one. 

plugins:
  - pub-minifier:
    jpeg:
        cache_enabled: true
        enabled: true
        enabled_on_serve: false
        exclude: []
        extensions: [".[jJ][pP][gG]", ".[jJ][pP][eE][gG]"]
        djpeg_path: djpeg
        cjpeg_path: cjpeg
        jpegtran_path: jpegtran
        optimise: true
        progressive: true
        copy_meta: none
        smooth: 10
        quality: 85

Above you can find all possible settings with their default values. You don't have to provide them. Just use them if you want to change some settings. The description of the meaning of given setting, you can find below.

cache_enabled

Control if caching mechanism is enabled.

enabled

Control if JPEG minifier is enabled.

enabled_on_serve

Control if JPEG minifier is enabled while page is being served locally (mostly used for content creation).

exclude

Defines a list of exclusion patterns for files or directories that will not be minified.

exclude

Defines a list of file extensions that will be minified.

djpeg_path

Path to djpeg tool (part of MozJPEG package).

cjpeg_path

Path to cjpeg tool (part of MozJPEG package).

jpegtran_path

Path to jpegtran tool (part of MozJPEG package).

optimise

Optimize Huffman table (smaller file, but slow compression).

progressive

Create progressive JPEG file.

copy_meta

Defines what metadata to copy: none , comments , icc or all .

smooth

Level of image smoothness: 0 (disabled, smallest) - 100 (biggest) [default: 10 ].

quality

Level of compression: 0 (disabled, worst) - 100 (best) [default: 85 ].

PNG optimization

PNG image file size optimizations are done using a combination of 2 tools:

  1. pngquant - this is a tool that reduces PNG file size by changing a color palette and alpha channel. Despite those optimizations, generated images are compatible with all web browsers and operating systems.
  2. oxipng - this is a tool that reduces PNG file size by a lossless optimized compression algorithm.

Using those tools together, can reduce PNG image file size by up to 70% with almost no visible quality degradation. You can always try to change it by modifying of default settings. Please have in mind that default values were set after my personal experiments and not always can be the most optimal one. 

plugins:
  - pub-minifier:
    png:
        cache_enabled: true
        enabled: true
        enabled_on_serve: false
        exclude: []
        extensions: [".[pP][nN][gG]"]
        pngquant_enabled: true
        pngquant_path: ongquant
        pngquant_speed: 1
        pngquant_quality: 95
        oxipng_enabled: true
        oxipng_path: oxipng
        oxipng_max_compression: true
        strip: true

Above you can find all possible settings with their default values. You don't have to provide them. Just use them if you want to change some settings. The description of the meaning of given setting, you can find below.

cache_enabled

Control if caching mechanism is enabled.

enabled

Control if PNG minifier is enabled.

enabled_on_serve

Control if PNG minifier is enabled while page is being served locally (mostly used for content creation).

exclude

Defines a list of exclusion patterns for files or directories that will not be minified.

exclude

Defines a list of file extensions that will be minified.

pngquant_enabled

Control if pngquant tool is enabled.

pngquant_path

Path to pnquant tool.

pngquant_speed

Compression speed: 1 (slow but best quality) - 12 (fast but rough) [default: 1 ].

pngquant_quality

Image quality: 0 (worst) - 100 (best) [default: 95 ]

oxipng_enabled

Control if oxipng tool is enabled.

oxipng_path

Path to oxipng .

oxipng_max_compression

Use max possible compression.

strip

Strip metadata from file.

SVG optimization

SVG vector image file size optimizations are done using SVGO tool. This is a Node.js-based tool. As we can read on the project website:

SVGO

SVG files, especially those exported from various editors, usually contain a lot of redundant and useless information. This can include editor metadata, comments, hidden elements, default or non-optimal values and other stuff that can be safely removed or converted without affecting the SVG rendering result.

Using this tool reduces SVG vector image file size by up to 70% with no visible quality degradation. This tool has multiple plugins that impact the effectiveness of an optimization. At this time, the pub-minifier plugin doesn't allow changing the default settings of used SVGO plugins . 

plugins:
  - pub-minifier:
    svg:
        cache_enabled: true
        enabled: true
        enabled_on_serve: false
        exclude: []
        extensions: [".[sS][vV][gG]"]
        svgo_path: svgo
        multipass: true

Above you can find all possible settings with their default values. You don't have to provide them. Just use them if you want to change some settings. The description of the meaning of given setting, you can find below.

cache_enabled

Control if caching mechanism is enabled.

enabled

Control if SVG minifier is enabled.

enabled_on_serve

Control if SVG minifier is enabled while page is being served locally (mostly used for content creation).

exclude

Defines a list of exclusion patterns for files or directories that will not be minified.

exclude

Defines a list of file extensions that will be minified.

svgo_path

Path to svgo tool.

multipass

Do multiple passes during compression to ensure all optimizations are apllied.

HTML optimization

HTML file size optimizations are done using html-minifier tool. This is a Node.js-based tool. As we can read on the project website:

HTMLMinifier

HTMLMinifier is a highly configurable , well-tested , JavaScript-based HTML minifier.

Using this tool reduces HTML file size by up to 30%. You can always try to change it by modification of default settings. Please have in mind that default values were set after my personal experiments and not always can be the most optimal one. 

plugins:
  - pub-minifier:
    html:
        cache_enabled: true
        enabled: true
        enabled_on_serve: false
        exclude: []
        extensions: [".[hH][tT][mM]", ".[hH][tT][mM][lL]"]
        postcss_path: postcss
        case_sensitive: true
        minify_css: true
        minify_js: true
        remove_comments: true
        remove_tag_whitespace: false
        collapse_whitespace: true
        conservative_collapse: true
        collapse_boolean_attributes: true
        preserve_line_breaks: true
        sort_attributes: true
        sort_class_name: true
        max_line_length: 1024

Above you can find all possible settings with their default values. You don't have to provide them. Just use them if you want to change some settings. The description of the meaning of given setting, you can find below.

cache_enabled

Control if caching mechanism is enabled.

enabled

Control if HTML minifier is enabled.

enabled_on_serve

Control if HTML minifier is enabled while page is being served locally (mostly used for content creation).

exclude

Defines a list of exclusion patterns for files or directories that will not be minified.

exclude

Defines a list of file extensions that will be minified.

html_minifier_path

Path to html-minifier tool.

case_sensitive

Treat attributes in case sensitive manner.

minify_css

Minify CSS that is inside HTML (using celan-css )

minify_js

Minify JS that is inside HTML (using uglify-js ).

remove_comments

Strip HTML comments.

remove_tag_whitespace

Remove space between attributes whenever possible.

Danger !!!

Enabling this setting may lead to problems with code blocks, etc.

collapse_whitespace

Collapse white space that contributes to text nodes in a document tree.

conservative_collapse

Always collapse to 1 space (never remove it entirely).

collapse_boolean_attributes

Omit attribute values from boolean attributes.

preserve_line_breaks

Always collapse to 1 line break (never remove it entirely) when whitespace between tags include a line break.

sort_attributes

Sort attributes by frequency.

sort_class_name

Sort style classes by frequency.

max_line_length

Define max line length after optimization: 80 - 4096 [default: 1024 ].

CSS optimization

CSS file size optimizations are done using PostCSS tool and some plugins:

This is a Node.js based tool. As we can read on the project website:

CSSnano

CSSnano takes your nicely formatted CSS and runs it through many focused optimisations, to ensure that the final result is as small as possible for a production environment.

Using this tool reduces CSS file size by up to 30%. At this time, the pub-minifier plugin doesn't allow changing the default settings of cssnano . 

plugins:
  - pub-minifier:
    css:
        cache_enabled: true
        enabled: true
        enabled_on_serve: false
        exclude: []
        extensions: [".[cC][sS][sS]"]
        postcss_path: postcss
        skip_minified: true

Above you can find all possible settings with their default values. You don't have to provide them. Just use them if you want to change some settings. The description of the meaning of given setting, you can find below.

cache_enabled

Control if caching mechanism is enabled.

enabled

Control if CSS minifier is enabled.

enabled_on_serve

Control if CSS minifier is enabled while page is being served locally (mostly used for content creation).

exclude

Defines a list of exclusion patterns for files or directories that will not be minified.

exclude

Defines a list of file extensions that will be minified.

postcss_path

Path to postcss tool.

skip_minified

Skip files that are already minified (usually one with .min.css extension).

JS optimization

JS file size optimizations are done using UglifyJS tool. This is a Node.js-based tool. As we can read on the project website:

UglifyJS

UglifyJS is a JavaScript parser, minifier, compressor and beautifier toolkit.

Using this tool reduces JS file size by up to 20%. At this time, the pub-minifier plugin doesn't allow changing the default settings. 

plugins:
  - pub-minifier:
    js:
        cache_enabled: true
        enabled: true
        enabled_on_serve: false
        exclude: []
        extensions: [".[jJ][sS]"]
        uglifyjs_path: uglifyjs
        skip_minified: true

Above you can find all possible settings with their default values. You don't have to provide them. Just use them if you want to change some settings. The description of the meaning of given setting, you can find below.

cache_enabled

Control if caching mechanism is enabled.

enabled

Control if JS minifier is enabled.

enabled_on_serve

Control if JS minifier is enabled while page is being served locally (mostly used for content creation).

exclude

Defines a list of exclusion patterns for files or directories that will not be minified.

exclude

Defines a list of file extensions that will be minified.

uglifyjs_path

Path to uglifyjs tool.

skip_minified

Skip files that are already minified (usually one with .min.js extension).

Backlinks:

Home

- file size optimizations, that is beneficial for site download speed and SEO ( pub-minifier plugin - 06_blog/v040-minifier-and-autonav.md),

v1.2.0 - 2023-10-17

This release adds some more control over minifier plugin by adding the following settings: