image compression

A leaner image pipeline for static documentation sites

Compress source images before the site generator copies them, then review the built output before deployment.

By Maliah Jennings·November 13, 2026·4 min read
What matters here
  1. Compressing source assets before the site build prevents the generator from copying oversized originals into output.
  2. PiPic’s CLI sends selected images for remote processing; it is not a local-only compressor.
  3. Compression leaves dimensions unchanged, so it cannot fix oversized pixel dimensions or replace visual review.

Documentation sites collect images quietly. A few screenshots land in a guide, then more arrive with each release. The generator copies them into the published site, and the output folder grows even when the text barely changes.

A reliable fix is to compress selected source images before the site build. PiPic’s open-source CLI can fit into that step, but there is an important distinction: the command runs from your development environment; compression itself is remote. PiPic says it deletes uploaded files immediately after processing. Treat the images as uploads, not as files that never leave your machine.

Start with the source assets

Find the directory that holds images tracked with the documentation: perhaps a shared assets folder or images beside individual pages. Do not begin by compressing the generated output directory. Most static generators recreate that directory during a build, so a change there may disappear on the next run. It can also leave you with a build whose media differs from the source files in the repository.

Make a list of eligible files in that source location. PiPic supports JPG, PNG, WebP and AVIF images up to 8 MB per file. Leave other formats out of the compression step. Be selective: diagrams with fine text and screenshots used to demonstrate interface details deserve a closer check than decorative photos.

Put compression before the build

  1. Keep a clean source. Work from the original images, or keep an untouched copy outside the directory that the compression step modifies. Repeatedly compressing an already compressed image can reduce quality without giving you a useful new baseline.
  2. Install the documented CLI. PiPic publishes its open-source client as @pipic/cli on npm. Use the current CLI documentation for the exact command and arguments; do not assume flags or directory behavior from another image tool.
  3. Choose where results go. PiPic’s CLI supports replacing files in place or writing to a fresh directory. A fresh directory makes comparison and rollback easier. If the generator already reads from a dedicated public-asset directory, you can direct the prepared files there using your existing project setup. Otherwise, compress in place only on a branch or with a recoverable copy.
  4. Build after compression. Run the usual documentation build after the selected source images are ready. Then inspect the generated asset folder and confirm that the expected files made it into the output. Deploy only after that check passes.

The exact wiring depends on the generator and repository layout. Keep the compression step narrow: target the documentation image directory, not every image the build happens to produce. That makes it easier to see what changed and avoids processing logos, generated charts or unrelated assets by accident.

Review the trade-offs, not just the byte count

Compression is not resizing. PiPic preserves image dimensions, so a screenshot exported at several thousand pixels wide will remain that size. Resize oversized source images separately when the page does not need their full dimensions. Also compare important images in the rendered documentation. A smaller file is not a win if small labels or diagram edges become hard to read.

Remember that PiPic’s CLI sends the chosen image to PiPic for processing. PiPic says files are deleted immediately after compression, and its homepage says the CLI sends the image requested and no telemetry. That is a stated handling policy, not the same as local-only processing. Check whether your documentation images are suitable for that workflow before adding it to an unattended build. Our earlier guide to scoping a zero-retention image step in a publishing pipeline covers the distinction between remote processing and local build artifacts.

There is also a quota to plan around. PiPic’s CLI tier includes 100 free images per month, with a Pro plan for 5,000. Avoid recompressing the entire library on every build. Run the step when eligible source images change, and retain the uncompressed originals so a future edit does not start from a lossy copy. If the project’s asset volume exceeds the available allowance, decide which images merit the step rather than sending the whole repository.

Make the build output the check

After a trial run, compare the generated asset folder with a clean build from the same commit. Check that pages still reference the intended paths, that formats remain usable in the target browsers, and that the visuals hold up at their displayed size. Track the output size over time if asset bloat is a recurring problem; a single successful compression run does not prevent future uploads from growing the folder again.

This approach works because it puts image-size reduction at the boundary between source assets and generated site output. The generator and hosting platform can stay unchanged. PiPic handles selected files; the project’s build remains responsible for copying and publishing them. Keep the target narrow, protect the originals, and make the rendered site—not the compression percentage—the final test.

More from PiPic News

Use changed paths to protect monorepo image quotas

A diff-based workflow sends only eligible, modified images to PiPic, keeping routine monorepo work from spending a monthly compression allowance on untouched assets.

By Vespera Almonte·November 8, 2026