📝 Introduction

This guide shows you how to minify (compress) your HTML output in Jekyll so your site loads faster. You’ll learn three approaches, from the most compatible to the most automated. Each step has a short explanation and copy–paste commands.

⚡ Why minify HTML?

  • Smaller pages: Removes whitespace and comments to reduce file size.
  • Faster loads: Less to download, quicker Time-to-First-Byte and render.
  • SEO boost: Performance is a ranking signal. Faster sites help users and search engines.

✅ Method 1: Post-build minify (GitHub Pages–friendly)

What it is: Build your site normally, then run a standalone minifier over the generated _site folder. Works locally and with CI (e.g., GitHub Actions). No Jekyll plugins required.

Step 1 — Build your site

What it does: Creates the final HTML files under _site/.

bundle exec jekyll build

Step 2 — Minify the HTML in _site/

What it does: Uses html-minifier-terser to compress HTML (also minifies inline CSS/JS).

npx html-minifier-terser \
  --input-dir _site \
  --output-dir _site \
  --file-ext html \
  --collapse-whitespace \
  --remove-comments \
  --remove-redundant-attributes \
  --remove-script-type-attributes \
  --remove-style-link-type-attributes \
  --minify-css true \
  --minify-js true

Optional — Add an npm script

What it does: Saves the options so you can run everything with one command.

{
  "name": "my-jekyll-site",
  "private": true,
  "scripts": {
    "build": "bundle exec jekyll build",
    "minify:html": "html-minifier-terser --input-dir _site --output-dir _site --file-ext html --collapse-whitespace --remove-comments --remove-redundant-attributes --remove-script-type-attributes --remove-style-link-type-attributes --minify-css true --minify-js true",
    "build:prod": "npm run build && npm run minify:html"
  },
  "devDependencies": {
    "html-minifier-terser": "^7.2.0"
  }
}

Run it:

npm run build:prod
Tip: On first use, run npm init -y to create package.json, then npm i -D html-minifier-terser.

🧩 Method 2: Jekyll plugin (jekyll-minifier)

What it is: A Ruby gem that minifies HTML (and optionally CSS/JS) during the Jekyll build. Note: Most third-party plugins are not allowed on GitHub Pages’ default build. Use this if you build locally and deploy the generated files, or if you use CI to build and publish.

Step 1 — Add the gem

What it does: Registers the plugin with Bundler so Jekyll can use it.

# Gemfile
gem "jekyll", "~> 4.3"
gem "jekyll-minifier", "~> 0.1"

Step 2 — Enable the plugin in Jekyll

What it does: Tells Jekyll to load the plugin during builds.

# _config.yml
plugins:
  - jekyll-minifier

# Optional (defaults shown)
jekyll-minifier:
  exclude:    # files or globs to skip
    - "sitemap.xml"
    - "feed.xml"

Step 3 — Install and build

bundle install
bundle exec jekyll build

Optional — Build on GitHub Actions

What it does: Builds with plugins enabled, then publishes the generated site (works with Pages when you deploy the output).

# .github/workflows/build.yml
name: Build Jekyll with Minify
on: { push: { branches: [ main ] } }

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.2'
          bundler-cache: true
      - run: bundle exec jekyll build --trace
      - uses: actions/upload-pages-artifact@v3
        with:
          path: _site
  deploy:
    needs: build
    permissions:
      pages: write
      id-token: write
    runs-on: ubuntu-latest
    steps:
      - uses: actions/deploy-pages@v4
Note: Configure your repo to serve from the uploaded artifact (GitHub Pages “GitHub Actions” option).

🪄 Method 3: Simple Liquid include (drop-in)

What it is: A tiny Liquid include that trims newlines and spaces in your rendered HTML. Easiest to set up, but less powerful than a real minifier. Works on GitHub Pages because it uses only Liquid.

Step 1 — Create an include

What it does: Captures page output, removes extra whitespace and comments, and prints the result.

{% raw %}{% comment %}
_includes/compress.html
A very simple compressor: removes HTML comments and collapses whitespace.
May not be safe for pages that rely on exact whitespace (e.g., <pre>).
{% endcomment %}
{% capture _html %}{{ include.content }}{% endcapture %}
{% assign _html = _html | replace: '<!--', '<!~~' %} {# protect conditional comments by altering marker #}
{% assign _html = _html | replace: '<!--', '' | replace: '-->', '' %}
{% assign _html = _html | replace: '  ', ' ' | replace: '  ', ' ' %}
{% assign _html = _html | strip_newlines | replace: '> <', '><' %}
{{ _html | replace: '<!~~', '<!--' }}{% endraw %}

Step 2 — Use it in your layout

What it does: Feeds your page’s HTML into the include before sending it to the browser.

<!-- _layouts/default.html -->
<!DOCTYPE html>
<html lang="en">
<head>
  ... your head ...
</head>
<body>
  {% raw %}{% include compress.html content=content %}{% endraw %}
</body>
</html>
Important: This lightweight approach can break pages that depend on whitespace (e.g., preformatted blocks). Test carefully; exclude such pages if needed.

💡 Tips & Notes

  • Exclude feeds/sitemaps/JSON: If you minify post-build, skip machine-readable files with tool options or globs.
  • Debug vs production: Minify only for production builds to keep readable output in development.
  • Combine with gzip/brotli: Your host/CDN usually compresses responses automatically—minify + gzip is ideal.
  • Test thoroughly: After minifying, click around the site and verify pages render as expected.

🛠 Troubleshooting

“command not found: npx”
→ Install Node.js (which includes npm/npx), then re-run the post-build step.

GitHub Pages ignores the plugin
→ Expected. GitHub Pages’ default build allows only approved plugins. Use Method 1 or build with Actions and deploy the generated _site.

Layout breaks after minify
→ Exclude the affected pages from minification, or use a more conservative configuration (don’t remove comments/whitespace aggressively).

Minifier altered inline JS/CSS
→ Disable --minify-js/--minify-css, or fix syntax issues (e.g., stray // in inline scripts).

📚 Resources & Further Reading