A safer image-compression step for Docusaurus and MkDocs

Documentation repositories collect images quietly. A few large screenshots, diagrams and product captures can make clones slower and keep page downloads heavier than they need to be. Adding image compression to a Docusaurus or MkDocs workflow is useful, but it is not a substitute for a repository cleanup plan.

PiPic’s CLI, published as @pipic/cli on npm, compresses JPG, PNG, WebP and AVIF images. The CLI has a free tier of 100 images per month and a Pro tier of 5,000 images per month. Its source is open on GitHub. The central workflow choice is whether to replace images in place or write compressed copies to a fresh directory. For documentation, the second option is often easier to review.

Start with a small, deliberate asset set

Pick a directory that contains images used by the documentation, rather than pointing a compression run at the whole repository. Keep source files out of generated output directories, and exclude files that are not ordinary web assets. PiPic accepts files up to 8 MB each, with a maximum of 100 images in a batch. Larger collections need separate batches, and the monthly CLI quota is a different limit from the per-batch limit.

Before changing anything, check how the site references images. Docusaurus projects commonly keep content and static assets in repository directories; MkDocs projects often reference images from documentation folders. Preserve the relative paths expected by those references. PiPic returns the same format it receives and does not change image dimensions, which helps avoid extension and layout changes, but it does not decide which images belong in the published site.

Choose a representative sample first: a screenshot with small text, a photographic image, a transparent graphic and a diagram if those appear in the repository. Compare the originals and compressed results at the size readers will see. Compression can reduce weight, but a small file is not automatically a better asset if labels or fine detail become hard to read. For PNG-specific decisions around transparency and palette reduction, see the guide to preserving transparent UI assets.

Make compression a build input, not a surprise

Install @pipic/cli in the project or in the environment that runs the build, then use the invocation documented for the current CLI release. The available product facts do not specify command syntax, so do not copy guessed flags from a shell example. Record the actual command in a small repository script and make its input and output directories explicit.

For Docusaurus, connect that script to the project’s build flow so asset preparation runs before the site is built. For MkDocs, use a wrapper script or build job that runs asset preparation and then invokes the existing MkDocs build. In either case, keep compression as a distinct step. That makes it possible to inspect its output and see whether the build is using the intended directory, rather than silently modifying assets as a side effect of publishing.

A practical pattern is to compress a staging copy, then build from that copy while retaining the originals in the working tree. If your setup instead uses PiPic’s in-place replacement option, run it on selected files before committing and review the resulting diffs. Do not assume that running compression on every build is harmless: repeated writes can create noisy changes, and a build should not leave tracked files unexpectedly modified.

Review changes and measure the right thing

After compression, compare file sizes and inspect visual quality before accepting the output. Keep image dimensions and filenames stable unless you intend to update references. Then build the documentation site and check representative pages in a browser. The meaningful result is a smaller set of assets that still renders correctly, not a successful compression command by itself.

For Docusaurus and MkDocs alike, make the script fail visibly if its compression step fails; otherwise, a broken preparation step can be mistaken for a successful build. Keep a record of which paths are inputs and which are generated outputs. Avoid feeding a generated directory back into the next run. If you automate compression in CI, scope it to new or changed assets and account for the CLI’s monthly image quota. The earlier workflow for checking changed image assets covers that quota and repeat-run problem.

Know what repository size means

Compressing and committing an image reduces the size of the current file and can make future checkouts lighter. It does not remove the older, larger version from existing Git history. Rewriting history is a separate operation with consequences for collaborators, so do not treat routine build-time compression as a way to reclaim space already stored in old commits. If historical blobs dominate repository size, measure that problem separately before deciding whether a history rewrite is justified.

There is also a trust boundary to consider: the CLI sends the image being compressed over the wire, and PiPic says files are deleted immediately after processing. The CLI source is public for inspection. That may fit published documentation assets, but teams should still apply their own rules to unpublished screenshots or confidential material.

The dependable setup is modest: select the assets that belong on the site, compress them in a reviewable step, preserve expected paths, and test the rendered pages. That gives documentation teams a way to reduce new asset weight and limit future Git growth without pretending a build script can fix the repository’s entire past.