mkdocs-minify-plugin

mkdocs-minify-plugin is an MkDocs plugin that shrinks the HTML, JavaScript, and CSS of your documentation site as it is built. By minifying each page before it is written to disk, it reduces payload size and speeds up load times for the generated static site.

It wires together battle-tested minifiers — htmlmin2 for HTML, jsmin for JavaScript, and csscompressor for CSS — behind a single MkDocs plugin configuration. A cache-safe option appends content hashes to asset filenames so browsers always fetch the latest minified files.

What You Get

• HTML minification via htmlmin2 with configurable options like comment removal
• JavaScript minification via jsmin for listed JS files
• CSS minification via csscompressor for listed CSS files
• Cache-safe hashing that appends content hashes to asset filenames

Common Use Cases

• Reducing the size of a documentation site built with MkDocs
• Speeding up page loads by stripping whitespace and comments from HTML
• Ensuring browsers pick up updated CSS/JS via cache-safe filenames

Under The Hood

Architecture - The plugin implements the MkDocs BasePlugin interface and hooks the build lifecycle events. On on_post_page it runs the page HTML through htmlmin2; on on_post_build it processes the configured JS and CSS files through jsmin and csscompressor, optionally rewriting references with content-hashed filenames when cache_safe is enabled.

Tech Stack - Written in Python and packaged as an MkDocs plugin entry point. It delegates the actual minification to three focused dependencies — htmlmin2, jsmin, and csscompressor — rather than reimplementing minifiers, keeping the plugin itself thin.

Code Quality - The plugin is a small, single-purpose codebase with a clear options schema validated against MkDocs’ config framework. It is mature and widely used across MkDocs sites, though recent development activity is low.

API Design - Configuration lives entirely in mkdocs.yml: boolean toggles for each asset type, an htmlmin_opts passthrough, explicit js_files/css_files lists, and a cache_safe flag. This declarative surface means no code changes are needed to adopt it.