Convert all images to avif file format

[Eric-Arellano]

Why migrate

avif is much more efficient than jpg, png, and gif. It's better than webp. (SVG is already great.)

Note that currently Next.js has been automatically upscaling our images already to webp. This upscaling happens on the server, although is cached, so has some hit to our server resource usage & initial page load on a cold cache.

We should migrate all our source images to AVIF for a few reasons:

1. Avoid the server resource usage because the image will already be optimized.
2. Use AVIF rather than Next.js's default of upscaling to webp. AVIF is ~20% smaller and more useful when downloaded.
3. Reduce Git repo size bloat. AVIF is ~10% the size of our PNG/JPG images.

Next.js will fallback to JPEG if the browser doesn't support AVIF, so there is no risk to our end-users.

How to migrate

The best way I've found to convert images is using magick: magick my-img.png my-img.avif

API docs

Sphinx outputs PNG; having it output AVIF is not feasible. So, our conversion pipeline needs to convert the images. It also needs to update the markdown.

Unfortunately, this will slow down our pipeline.

Guides MDX files

These images are controlled by us. We don't normally run a build process, so we would need to add a new workflow step.

Notably, we want to avoid introducing the PNG/JPG files in the first place because once they're in Git, the blob stays there forever. So, we should block PRs.

We probably want a script that will automatically scan every non-API image and convert them to AVIF. However, one tricky thing with this script is we would need to also update the markdown link to use .avif in the file. A simpler approach would be to only lint then tell the person how to run magick and update the markdown. I'm not sure how much automation to have; we could start with the easiest implementation (lint only) and then if it is annoying to writers, invest the time later to automate more.

Jupyter notebook output

See #1672. Jupyter notebooks are tricky because they store their images inline in the file. #1672 stores how we could instead store the images outside of the file so we can use Next.js's <Image> component; however, that optimization would only apply in closed source, which may require duplicating this AVIF logic in both repositories.

One other nuance is that our notebooks normally generate SVGs (which can be quite large! See #1678). Would it be better if we generated PNGs, then converted those PNGs into AVIF? Does that reduce file size? Does that negatively impact user experience too much?

Update: looking at some sample images in our guides, I don't think it's much benefit; the circuit output SVGs are pretty small, 5-25KB. They are higher quality than AVIF also. We should convert PNGs to AVIF, though, like the notebook from #1673 using PNGs to minimize file size.

Alternative: open source sync

Rather than converting images for MDX Guides and Jupyter notebooks in this repository, we could migrate them during the open source sync in the closed source repository. That keeps the workflow much simpler in qiskit/documentation. The only downside to this approach is it doesn't help with Git repository bloat in qiskit/documentation.

We could also handle MDX differently than Jupyter. Maybe MDX images need to be converted in qiskit/documentation, but we don't convert Jupyter notebooks because a) we don't want to add the workflow with storing images externally #1672 and b) usually we will stick with SVGs anyways. If we stick with SVGs anyways, then the downside of Git repository bloat is irrelevant.

[Eric-Arellano]

@arnaucasau and I agreed on a few things:

• API docs should indeed be automated. The slowdown is acceptable
• For MDX, start with a linter. Only spend the time automating if this ends up being too annoying
• For Jupyter notebooks, only convert in closed source as part of Investigate storing notebook images as files, rather than inline #1672.
  • Indeed, the hit to Git repo size is acceptable because most the files anyways are SVGs so they don't even benefit from AVIF

We cannot start using AVIF in this repository until we merge a config change in closed source. However, we don't want to merge that change until most of our images are converted. So, we should do all these changes around the same time.