Skip to content

Image settings DX tweaks in documentation #13232

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+35 −2
Open

Image settings DX tweaks in documentation #13232

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Image settings DX tweaks
  • Loading branch information
@thibaudcolas
thibaudcolas committed Jul 12, 2025
commit 5066b4dda41497aecd7ecfe792a9e927693ccde9
35 changes: 34 additions & 1 deletion docs/reference/settings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -412,14 +412,47 @@ Custom storage classes should subclass `django.core.files.storage.Storage`. See
### `WAGTAILIMAGES_EXTENSIONS`

```python
WAGTAILIMAGES_EXTENSIONS = ['png', 'jpg']
WAGTAILIMAGES_EXTENSIONS = ['avif', 'svg']
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not precious about which extensions we have in there, was just trying to go some way towards avoiding #13127

```

A list of allowed image extensions that will be validated during image uploading.
If this isn't supplied, all of AVIF, GIF, JPG, JPEG, PNG, WEBP are allowed.
Warning: this doesn't always ensure that the uploaded file is valid as files can
be renamed to have an extension no matter what data they contain.

### `WAGTAILIMAGES_JPEG_QUALITY`

```python
WAGTAILIMAGES_JPEG_QUALITY = 75
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here and below – I chose to demo the settings with realistic values, that should work on all sorts of sites, and lead to smaller images than our defaults.

```

Change the global default for JPEG image encoding quality (default: 85).

### `WAGTAILIMAGES_WEBP_QUALITY`

```python
WAGTAILIMAGES_WEBP_QUALITY = 70
```

Change the global default for WebP image encoding quality (default: 80).

### `WAGTAILIMAGES_AVIF_QUALITY`

```python
WAGTAILIMAGES_AVIF_QUALITY = 65
```

Change the global default for AVIF image encoding quality (default: 80).

### `WAGTAILIMAGES_HEIC_QUALITY`

```python
WAGTAILIMAGES_HEIC_QUALITY = 60
```

Change the global default for HEIC image encoding quality (default: 80).


## Documents

### `WAGTAILDOCS_DOCUMENT_MODEL`
Expand Down
2 changes: 1 addition & 1 deletion docs/topics/images.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -537,7 +537,7 @@ See [](image_renditions).
Wagtail supports the use of Scalable Vector Graphics alongside raster images. To allow Wagtail users to upload and use SVG images, add "svg" to the list of allowed image extensions by configuring `WAGTAILIMAGES_EXTENSIONS`:

```python
WAGTAILIMAGES_EXTENSIONS = ["gif", "jpg", "jpeg", "png", "webp", "svg"]
WAGTAILIMAGES_EXTENSIONS = ["avif", "gif", "jpg", "jpeg", "png", "webp", "svg"]
```

SVG images can be included in templates via the `image` template tag, as with raster images. However, operations that require SVG images to be rasterized are not currently supported. This includes direct format conversion, e.g. `format-webp`, and `bgcolor` directives. Crop and resize operations do not require rasterization, so may be used freely (see [](available_resizing_methods)).
Expand Down