Skip to main content

Pre-compress your Pelican site using gzip, brotli, zstandard, and zopfli!

Project description

Pre-compress your Pelican site using gzip, brotli, zstandard, and zopfli!


Are you using Pelican, the static site generator? If so, great! Are you pre-compressing your static files to have the fastest site possible? If not, install pelican_precompress today! It’s the plugin that makes your visitors happy and saves you money!

Installation

There are three steps required to start using static compression:

  1. Install the plugin and any supporting Python packages you want.

  2. Configure Pelican to use the pelican_precompress plugin.

  3. Configure your web server to use static, pre-compressed files.

1. Install the Python modules

At minimum, you’ll need to install the pelican_precompress plugin. It will automatically generate gzip files because gzip is built into the Python standard library.

However, if you want better compression you’ll need to install additional packages. pelican_precompress exposes each compression algorithm by name as a package extra:

  • brotli

  • zopfli

  • zstandard

These can be selected as a comma-separated list during install:

$ pip install pelican_precompress[zstandard]
$ pip install pelican_precompress[zstandard,brotli,zopfli]

Further reading: brotli package, pyzstd package, zopfli package

2. Configure Pelican

pelican_precompress supports Pelican’s namespace plugin architecture and will be automatically detected and loaded when Pelican runs.

However, if you’re maintaining a list of plugins for Pelican to use then you’ll need to add pelican_precompress to the list of active plugins.

Feel free to copy and paste the code below into your Pelican configuration file. Just uncomment and edit the configuration lines to your liking…or leave them alone because the defaults are awesome!

# You only need to add pelican_precompress to your PLUGINS list
# if your configuration file already has a PLUGINS list!
#
# PLUGINS = ['pelican.plugins.precompress']

# These options can be customized as desired.
#
# PRECOMPRESS_GZIP = True or False
# PRECOMPRESS_BROTLI = True or False
# PRECOMPRESS_ZSTANDARD = True or False
# PRECOMPRESS_ZOPFLI = True or False
# PRECOMPRESS_OVERWRITE = False
# PRECOMPRESS_MIN_SIZE = 20
# PRECOMPRESS_TEXT_EXTENSIONS = {
#     '.atom',
#     '.css',
#     '.html',
#     '.but-the-default-extensions-are-pretty-comprehensive',
# }

Further reading: Pelican plugins

3. Configure nginx

nginx supports gzip compression right out of the box. To enable it, add something like this to your nginx configuration file:

http {
    gzip_static on;
    gzip_vary on;
}

At the time of writing, nginx doesn’t natively support brotli or zstandard compression.

To serve pre-compressed brotli files, you’ll need the static brotli module. To serve pre-compressed zstandard files, you’ll need the static zstandard module. When either or both of those are installed, you’ll add something like this to your nginx configuration file:

load_module modules/ngx_http_brotli_static_module.so;
load_module modules/ngx_http_zstd_static_module.so;

http {
    brotli_static on;
    zstd_static on;
}

Further reading: gzip_static, gzip_vary, nginx brotli module, nginx zstd module

Configuration

There are a small number of configuration options available. You set them in your Pelican configuration file.

  • PRECOMPRESS_GZIP (bool, default is True)

    This is always True unless you set this to False. For example, you might turn this off during development.

  • PRECOMPRESS_BROTLI (bool, default is True if brotli is installed)

    If the brotli module is installed this will default to True. You might set this to False during development. If you set this to True when the brotli module isn’t installed then nothing will happen.

  • PRECOMPRESS_ZSTANDARD (bool, default is True if pyzstd is installed)

    If the pyzstd module is installed this will default to True. You might set this to False during development. If you set this to True when the pyzstd module isn’t installed then nothing will happen.

  • PRECOMPRESS_ZOPFLI (bool, default is True if zopfli is installed)

    If the zopfli module is installed this will default to True. You might set this to False during development. Note that if you try to enable zopfli compression but the module isn’t installed then nothing will happen.

  • PRECOMPRESS_OVERWRITE (bool, default is False)

    When pelican_precompress encounters an existing compressed file it will refuse to overwrite it. If you want the plugin to overwrite files you can set this to True.

  • PRECOMPRESS_TEXT_EXTENSIONS (Set[str])

    This setting controls which file extensions will be pre-compressed.

    If you modify this setting in the Pelican configuration file it will completely replace the default extensions!

  • PRECOMPRESS_MIN_SIZE (int, default is 20)

    Small files tend to result in a larger file size when compressed, and any improvement is likely to be marginal. The default setting is chosen to avoid speculatively compressing files that are likely to result in a larger file size after compression.

    To try compressing every file regardless of size, set this to 0.

Development

If you’d like to develop and/or test the code yourself, clone the git repository and run these commands to set up a Python virtual environment, install dependencies, and run the test suite:

python -m venv .venv

# Activate the virtual environment (Linux)
source .venv/bin/activate

# Activate the virtual environment (Windows)
& .venv/Scripts/Activate.ps1

python -m pip install poetry pre-commit tox
pre-commit install
poetry install

# Run the test suite
tox

The test suite uses tox to setup multiple environments with varying dependencies using multiple Python interpreters; pytest allows the test suite to have parametrized tests; pyfakefs creates a fake filesystem that the tests safely create and erase files in; and coverage keeps track of which lines of code have been run.

pelican_precompress has 100% test coverage, but there may still be bugs. Please report any issues that you encounter.

Further reading: poetry, tox, venv, pytest, pyfakefs, coverage

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pelican_precompress-2.3.0.tar.gz (7.2 kB view details)

Uploaded Source

Built Distribution

pelican_precompress-2.3.0-py3-none-any.whl (7.6 kB view details)

Uploaded Python 3

File details

Details for the file pelican_precompress-2.3.0.tar.gz.

File metadata

  • Download URL: pelican_precompress-2.3.0.tar.gz
  • Upload date:
  • Size: 7.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.13.2

File hashes

Hashes for pelican_precompress-2.3.0.tar.gz
Algorithm Hash digest
SHA256 ee7ef52b7f3645580ca972e54f1760a79c3d04a946fa1e072ab75429907bd03d
MD5 ddf3ee5f619d1955cecd3948ccc2ade3
BLAKE2b-256 8b53a2f96b1d80770e519f695f603886d1eb7e18b5c85c00e58cf750c3bd3265

See more details on using hashes here.

File details

Details for the file pelican_precompress-2.3.0-py3-none-any.whl.

File metadata

File hashes

Hashes for pelican_precompress-2.3.0-py3-none-any.whl
Algorithm Hash digest
SHA256 44a241befa75c1856dd520f6c4aad578d4089d80b04c03f0cca8430850d95d4a
MD5 3833c055b0a6d56f4279811796491c58
BLAKE2b-256 1d3c24bc571545cfeffce13a51ad6d7436e2488000339e81d54e454ecf6828f3

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page