Completed first writing pass on blogpost and docs text

[website] / content / blog / 2025 / bookstack-release-v25-05.md

+++
categories = ["Releases"]
tags = ["Releases"]
title = "BookStack Release v25.05"
date = 2025-05-31T14:30:00Z
author = "Dan Brown"
image = "/images/blog-cover-images/cc-by-2/karen-roe-pond.jpg"
slug = "bookstack-release-v25-05"
draft = false
+++

Today we have the May 2025 release of BookStack. The headline features
of this release are focused on new comment features but we have some other goodies
packaged in also!

* [Update instructions](/docs/admin/updates)
* [GitHub release page](https://github.com/BookStackApp/BookStack/releases/tag/v25.05)

**Upgrade Notices**

TODO

- **Title** - Detail

TODO - Video
<!-- {{<pt iUZWrk4oxLYc2dFsAPjDyY>}} -->

### Content Comments

In a platform like BookStack it's quite likely that page comments will be referring
to a specific part of the page content, which you'd previously need to describe
as part of the comment text.
With this release, it's now possible to directly & visually reference a part of the 
page content in a comment.
This is achieved via a new button in the content popover, which is shown when part of the page text
is selected:

TODO - image of popover with comment

Clicking this will start a new comment with a reference to the selected area & text range.
When viewing the page, this will then show as a highlight and marker for that content:

TODO - Image of inline comment display

Clicking the comment marker will then open up that comment thread:

TODO - Image of inline thread

From there you can close or read the thread within this inline display, or click the "Jump to thread"
action to jump to the full thread in the comments area, where you can edit or reply where desired.

When viewing the comments area, comments which reference content will have an indicator to reflect their connection
to specific content. This may show as outdated if the referenced content has changed since the comment
was made. Clicking on this indicator will jump the user to the relevant section on the page.
If the referenced section no longer exists at all, this indicator will become orange and can't be clicked.

TODO - Image of range of indicator presentations

Some of these features are also supported in the page editor.
When using the new WYSIWYG editor, opening the comments sidebar will show the inline comments 
(where possible) and the reference indicators will be active as explained above.
This isn't supported in the markdown or the old default WYSIWYG editor, where the 
indicators will instead remain gray to represent being inactive.

TODO - Image of editor with comments

One thing to note is that only the starting comment of a thread can reference content in this way.
This is to avoid a range of confusing user experience scenarios, like having parts of threads duplicated across
various inline comment markers.

### Comment Archiving

With the addition of content comments, I thought that comments would now be much more useful
for creating todo-like actions regarding the page content.
In such usage, it would really help to have a way to close-off and hide comments.
While you could delete comments, from a user perspective that seems quite dangerous, and in 
most scenarios you'd want to retain that context that led to changes.

To support these kind of scenarios, this release adds the ability to archive comments.
This is an action which shows on a comment like the existing options:

TODO - Image of archive option, with comment tabs showing

In the comments area, you'll now see tabs for jumping between active and archived threads.
Inline comment markers, introduced above, will show based upon which tab is active.
Within the page editor, archived threads can be accessed via a dropdown below active 
comment threads.

TODO - Image in editor sidebar

Only the top-most comments have the ability to be archived or unarchived,
to keep management thread-based otherwise you will have parts of threads
split between tabs.
In terms of permissions, the ability to archive is currently just based
on the ability to edit or delete the comment.

### AVIF Image Support

BookStack will now support the use of AVIF images for all 
places you can upload images!
AVIF, which is the image version of the AV1 video standard,
is a modern image format which can achieve great compression 
for smaller image file sizes at equivilent quility.
It's also quite featureful, with support for transparency, animation,
HDR, and lossless compression.

The only area which won't currently support AVIF images is 
our default PDF export option, but hopefully support in this
area will be here soon.

For an in-depth look & comparison of AVIF I'd strongly recommend reading
this blog post by Jake Archibald: https://jakearchibald.com/2020/avif-has-landed/

### OIDC User Avatar Support

From this release it's now possible for instances using OIDC
authentication to assign user avatar images from the data
given from the OIDC system.
This can be enabled through the following `.env` option:

```bash
OIDC_FETCH_AVATAR=true
```

**Warning:** This should only be enabled where you trust the connected
OIDC system to provide safe URLs for user images otherwise this can 
present a server-side-fetching risk.

With this option enabled, upon login, BookStack will use the `picture` claim provided
in OIDC user data, and fetch that image and save that as the user's avatar.
This will only be done if the user does not already have a user avatar image set.

A big thanks to [@rubentalstra](https://github.com/BookStackApp/BookStack/pull/5429)
for contributing this feature.

### System Info API Endpoint

A new api endpoint has been added in this release which provides some high-level
details of the system. The endpoint can be accessed at `GET /api/system` and
returns data like that shown below:

```json
{
  "version": "v25.02.4",
  "instance_id": "1234abcd-cc12-7808-af0a-264cb0cbd611",
  "app_name": "My BookStack Instance",
  "app_logo": "https://docs.example.com/uploads/images/system/2025-05/cat-icon.png",
  "base_url": "https://docs.example.com"
}
```

This can be useful in integration scenarios where you need specific details
to make decisions or display elsewhere.

### New WYSIWYG Editor Updates, Now in Beta

The new WYSIWYG editor, [introduced back in v24.10](/blog/bookstack-release-v24-10/#new-alpha-wysiwyg-editor-option),
is moving from Alpha to Beta status in this release!
We've now been through many patch and feature releases where fixes and
improvements have been made to this editor, so I'm happy to move it
a little further along the journey to becoming the default editor option.

During this stage I'll open up feedback to customization requirements while
also maybe switching over the comment WYSIWYG editor to use the same new framework
we've built here.

A big thanks to everyone that has [provided feedback](https://github.com/BookStackApp/BookStack/issues/5245)
during this alpha stage. I've started a new fresh thread to gain feedback for this beta stage:

TODO - Insert new thread link

This release does bring a range of fixes and improvements itself:

- Updated dropdown behaviour to align with existing editor.
- Made it easier to escape above/below tables, code blocks and diagrams.
- Added auto-conversion of links to images on paste to align with existing editor behaviour.
- Fixed buggy diagram selection and keyboard interaction.
- Fixed table column size changes not showing until after page save.

### Translations

Once again a massive thanks to all the below precise prose professionals who have 
kindly contributed translations since our last feature release:

- Name - *Lang - 2633 words*

*Word counts are those tracked by Crowdin, indicating original EN words translated.*

### Next Steps

As referenced above, with the new editor moving to beta I may look to update the comment
editor to this new editor, to get it used in more production scenarios, yet in a limited scope.
Regardless, I'm sure more fixes and improvements will be made in this area.

In July we'll see the 10 year anniversary since the start of the project.
I was aiming to build one of the very complicated & highly requested features in our backlog
for this event, but I burnt out on that after various attempts in this release cycle,
so I'm not keen on doing that again. 
I'm not one for a lot of fanfare, but I'm going to try and think about some different things
we can do to celebrate this milestone.

### Full List of Changes

**Released in v25.05**

* Added support for comments to reference page sections. ([#5584](https://github.com/BookStackApp/BookStack/pull/5584), [#1265](https://github.com/BookStackApp/BookStack/issues/1265))
* Added AVIF image support. ([#5625](https://github.com/BookStackApp/BookStack/pull/5625), [#5474](https://github.com/BookStackApp/BookStack/issues/5474))
* Added new system info API endpoint. ([#5607](https://github.com/BookStackApp/BookStack/pull/5607), [#5603](https://github.com/BookStackApp/BookStack/issues/5603))
* Added user avatar image fetching for OIDC authentication. Thanks to [@rubentalstra](https://github.com/BookStackApp/BookStack/pull/5429). ([#5626](https://github.com/BookStackApp/BookStack/pull/5626), [#5429](https://github.com/BookStackApp/BookStack/pull/5429), [#4271](https://github.com/BookStackApp/BookStack/issues/4271))
* Updated new WYSIWYG editor with further fixes. ([#5627](https://github.com/BookStackApp/BookStack/pull/5627))
* Updated page edit redirect to view if permission failed on edit. ([#5568](https://github.com/BookStackApp/BookStack/issues/5568))
* Updated translations with latest Crowdin changes. ([#5622](https://github.com/BookStackApp/BookStack/pull/5622))
* Update codebase and packages to address php 8.4 depreactions. ([#5358](https://github.com/BookStackApp/BookStack/issues/5358))

**Released in v24.02.5**

* Fixed incorrect image directory permissions. ([#5609](https://github.com/BookStackApp/BookStack/pull/5609), [#5605](https://github.com/BookStackApp/BookStack/issues/5605))
* Updated translations with latest Crowdin changes. ([#5608](https://github.com/BookStackApp/BookStack/pull/5608))
* Updated PHP packages.
* Updated system CLI:
  - Fixed handling of database credentials with escaped special characters.
  - Updated download-vendor command with extra clean-up handling.


**Released in v24.02.4**

* Updated PHP dependency package versions to fix compatibility issue on systems with recent libxml versions (eg. Arch Linux).

**Released in v24.02.3**

* Updated image file permission error handling for images to log instead of fail. ([#5601](https://github.com/BookStackApp/BookStack/pull/5601), [#5269](https://github.com/BookStackApp/BookStack/issues/5269))
* Fixed style issues in exports due to CSS variables being ignored. ([#5576](https://github.com/BookStackApp/BookStack/issues/5576))
* Updated translations with latest Crowdin changes. ([#5566](https://github.com/BookStackApp/BookStack/pull/5566))
* Updated PHP dependency package versions.

**Released in v24.02.2**


* Updated name sort rule handling to consider accented characters. Thanks to [@bernardo-campos](https://github.com/BookStackApp/BookStack/pull/5550). ([#5550](https://github.com/BookStackApp/BookStack/pull/5550), [#5542](https://github.com/BookStackApp/BookStack/issues/5542))
* Updated translations with latest Crowdin changes. ([#5537](https://github.com/BookStackApp/BookStack/pull/5537))
* Updated PHP dependency package versions.
* Fixed a range of issues for the new WYSIWYG editor: ([#5558](https://github.com/BookStackApp/BookStack/pull/5558))
  - Fixed content saving issues, specifically on save shortcut usage.
  - Fixed list conversion & parsing which was mishandling tasks lists.
  - Fixed a range of list selection and nesting scenarios.
  - Updated keyboard navigation to be more reliable around images & media embeds.
* Fixed comment times not being shown. ([#5555](https://github.com/BookStackApp/BookStack/issues/5555))

**Released in v24.02.1**

* Added ipv6 database host address support. ([#5464](https://github.com/BookStackApp/BookStack/issues/5464))
* Updated translations with latest Crowdin changes. ([#5505](https://github.com/BookStackApp/BookStack/pull/5505))
* Updated revisions list to hide changes link for oldest revision. ([#5454](https://github.com/BookStackApp/BookStack/issues/5454))
* Updated system CLI:
  * Added new `download-vendor` command.
  * Updated restore command to take environment variables into account. ([#5489](https://github.com/BookStackApp/BookStack/issues/5489))
  * Updated backup command to use mariadb-dump where available. ([#5373](https://github.com/BookStackApp/BookStack/issues/5373))
  * Updated update command to check, warn and exit early if the CLI is making changes to itself. ([#5335](https://github.com/BookStackApp/BookStack/issues/5335))
  * Updated MySQL handling to use option files to pass details to CLI executions.
  * Updated MySQL handling to consider common xampp directory.
* Updated PHP dependencies.

----

<span style="font-size: 0.8em;opacity:0.9;">Header Image Credits: <span>Photo by <a href="https://www.flickr.com/photos/karen_roe/8247172011">Karen Roe (CC-BY-2)</a> - Image Modified</span></span>