BookStack Release v25.05

Dan Brown posted on the 31st of May 2025

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

• Update instructions
• GitHub release page

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:

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:

Clicking the comment marker will then open up that comment 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 as needed.

When viewing the comments below the page, those 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.

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; there the indicators will instead remain gray to represent being inactive.

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:

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.

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 equivalent quality. 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:

1

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 to save it 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 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:

1
2
3
4
5
6
7

{
  "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, 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 during this alpha stage. I’ve started a new fresh thread here to gain feedback for this beta stage.

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.
• Fixes table selection/navigation issues when a caption is present or when changes are made to the table.

Translations

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

• mabdullah - Arabic - 3862 words
• Leonardo Mario Martinez (leonardo.m.martinez) - Spanish, Argentina - 1678 words
• m4z - German Informal; German - 1116 words
• toras9000 - Japanese - 766 words
• Qxlkdr - Swedish - 757 words
• Martins Pilsetnieks (pilsetnieks) - Latvian - 682 words
• Hari (muhhari) - Indonesian - 597 words
• Vitaliy (gviabcua) - Ukrainian - 541 words
• Jeff Huang (s8321414) - Chinese Traditional - 506 words
• cbridi - Portuguese, Brazilian - 363 words
• 仙君御 (xjy) - Chinese Simplified - 336 words
• Skrabák Csaba (kekcsi) - Hungarian - 308 words
• matthias4217 - French - 300 words
• Evert Meulie (Evert) - Norwegian Bokmal - 263 words
• neodvisnost - Slovenian - 167 words
• Jasper Backer (jasperb) - Dutch - 124 words
• Alexandar Cavdarovski (ace.200112) - Swedish - 86 words
• Ilya Shaulov (ishaulov) - Russian - 85 words
• Soubi Agatsuma (bisouya) - Hebrew - 81 words
• Igor V Belousov (biv) - Russian - 71 words
• Indrek Haav (IndrekHaav) - Estonian - 57 words
• 周盛道 (zhoushengdao) - Chinese Simplified - 56 words
• 구닥다리TV (yjj8353) - Korean - 54 words
• Konstantin Bobkov (b.konstantv) - Russian - 46 words
• scureza - Italian - 40 words
• Onur Oskay (o.oskay) - Turkish - 38 words
• Sébastien Merveille (SebastienMerv) - French - 37 words
• Honza Nagy (honza.nagy) - Czech - 32 words
• Maxim Kouznetsov (masya.work) - Hebrew - 15 words
• nutsflag - French - 13 words
• Guttorm Hveem (guttormhveem) - Norwegian Nynorsk - 9 words
• Ruben Sutter (rubensutter) - German - 2 words
• Michał Lipok (mLipok) - Polish - 2 words
• jellium - French - 2 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 implementation, 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, #1265)
• Added comment archive support. (#5584)
• Added AVIF image support. (#5625, #5474)
• Added new system info API endpoint. (#5607, #5603)
• Added user avatar image fetching for OIDC authentication. Thanks to @rubentalstra. (#5626, #5429, #4271)
• Updated new WYSIWYG editor with further fixes. (#5627)
• Updated page-edit redirect to page-view if permission failed on edit. (#5568)
• Updated translations with latest Crowdin changes. (#5622)
• Update codebase and packages to address php 8.4 depreactions. (#5358)

Released in v24.02.5

• Fixed incorrect image directory permissions. (#5609, #5605)
• Updated translations with latest Crowdin changes. (#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, #5269)
• Fixed style issues in exports due to CSS variables being ignored. (#5576)
• Updated translations with latest Crowdin changes. (#5566)
• Updated PHP dependency package versions.

Released in v24.02.2

• Updated name sort rule handling to consider accented characters. Thanks to @bernardo-campos. (#5550, #5542)
• Updated translations with latest Crowdin changes. (#5537)
• Updated PHP dependency package versions.
• Fixed a range of issues for the new WYSIWYG editor: (#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)

Released in v24.02.1

• Added ipv6 database host address support. (#5464)
• Updated translations with latest Crowdin changes. (#5505)
• Updated revisions list to hide changes link for oldest revision. (#5454)
• Updated system CLI:
  • Added new download-vendor command.
  • Updated restore command to take environment variables into account. (#5489)
  • Updated backup command to use mariadb-dump where available. (#5373)
  • Updated update command to check, warn and exit early if the CLI is making changes to itself. (#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.

Header Image Credits: Photo by Karen Roe (CC-BY-2) - Image Modified