BookStack Release v25.02
Dan Brown posted on the 26th of February 2025
Today we release BookStack v25.02! This aimed to be a maintenance release with the primary goal of upgrading our core framework, but it grew a little to include some goodies like automatic sorting, theme system additions, and editor improvements.
Upgrade Notices
- PHP Version Requirement Change - The minimum supported PHP version has changed from PHP 8.1 to PHP 8.2 in this release. Please see our “Updating PHP & Composer” documentation page for guidance on updating PHP where needed.
- Sorting - Basic sort order changes for chapters and pages will no longer affect the “updated” time for these items. Wider changes during sorting (moving to a new parent) will still increment the “updated” time.
- Theme System - A
public/folder within an active theme folder will now be exposed for public access. If for some reason you already have such a folder that you don’t want exposed, rename it before upgrading.
Automatic Sorting with Sort Rules
It’s now possible to automatically sort pages & chapters within a book! This is done using “Sort Rules” which are centrally managed via a new “Sorting” page in the application settings:
Within a sort rule, you can configure a range of sort operations which will be applied in the configured order:
Created rules can then be assigned to books via an option in the “Sort” view for a book:
It’s also possible to configure a default sort rule to assign to any new created books. This is part of the new “Sorting” settings page.
These sort rules will then automatically run on events which may alter the sort order, like page/chapter create/update events. The operations within a sort rule can be updated as needed, and upon save any assigned books will be automatically re-sorted to use the new order.
For those that want to assign a sort rule to their existing books, a new command has been added to make this easy. This has various options for batch assigning sort rules to books.
Search Indexing Improvements
The way BookStack indexes content for search now follows more advanced logic
for this release to address some common limitations faced.
Specifically, single terms containing certain punctuation like . periods
would have previously been split, leaving any searches for terms like “24.5”
falling back to slower (and non-score based) exact matches.
As of v25.02, BookStack will now index the non-split term in addition to the split term,
allowing both to match with indexed and scored results.
In additions to . periods, this is also done for - hyphens which we previously did not
consider before.
Lastly, «giullemets» are now considered as punctuation in the same manner as other brackets.
Note that to receive this improvements for existing content, you’ll need to regenerate the search index after upgrading.
Improvements for the New WYSIWYG Editor
The new alpha WYSIWYG editor, introduced in v24.10, received another bunch of additions of fixes for this release:
- Added custom color select/management to color picker controls.
- Added color pickers to relevant form fields.
- Added table caption support.
- Added src conversions for YouTube urls via media insert.
- Added additional test helpers and documentation.
- Fixed issues with auto-url on space/enter, when at the end of a line.
- Fixed error importing code blocks in some cases.
The editor is now pretty much feature complete compared to the existing WYSIWYG editor, but I want to develop a few key area into better stability before moving it into beta.
Public Files via Theme System
A common challenge for BookStack customization was how to expose files that need to be loaded via the browser, like CSS and JavaScript files.
While there were some methods to work around this, BookStack now provides a
direct way using the theme system via simply creating a public directory
within your theme folder.
Any files within this folder will then be served at the theme/<theme_name>/
url path of your BookStack instance.
For full details, see the added “Publicly Accessible Files” section of the visual theme system documentation.
Framework Upgrade
The core aim for this release was to update the underlying framework. We updated from Laravel 10 to Laravel 11, which also required a change of our minimum required PHP version from PHP 8.1 to PHP 8.2. This is something we generally do yearly to ensure we’re staying on supported versions of the software we depend on. Hopefully there’ll be no negative impact outside of some users needing to update their installed PHP version.
Translations
A big thanks to the following ingenious interlingual interpreters that have helped to translate BookStack since our last feature release:
- HrCalmar - Danish - 2633 words
- cbridi - Portuguese, Brazilian - 1083 words
- zeronell - Chinese Simplified - 628 words
- Indrek Haav (IndrekHaav) - Estonian - 447 words
- m0uch0 - Spanish - 373 words
- julien Vinber (julienVinber) - French - 370 words
- randi (randi65535) - Korean - 367 words
- KateBarber - Welsh - 356 words
- David Bauer (davbauer) - German - 329 words
- scureza - Italian - 303 words
- Tim (thegatesdev) - Dutch - 251 words
- Honza Nagy (honza.nagy) - Czech - 248 words
- Hyunwoo Park (oksure) - Korean - 242 words
- aram.rafeq.7 (aramrafeq2) - Kurdish - 75 words
- Raphael Moreno (RaphaelMoreno) - Portuguese, Brazilian - 70 words
- Antti-Jussi Nygård (ajnyga) - Finnish - 37 words
- Mohammad Aftab Uddin (chirohorit) - Bengali - 36 words
- felixxx - German Informal - 18 words
- Filip Antala (AntalaFilip) - Slovak - 15 words
- Pavel Zlatarov (pzlatarov) - Bulgarian - 14 words
- ingelres - French - 4 words
Word counts are those tracked by Crowdin, indicating original EN words translated.
Next Steps
We have the 10 year anniversary of BookStack coming up later this year. I may stretch out this release cycle, to work on a chunkier feature, but I’m not decided on that yet.
I will continue to work on the new WYSIWYG editor with the aim to get it in more of a “beta” state for the next feature release. If I do stretch out the release cycle, I’ll look to get editor fixes & enhancements out via patch releases instead of waiting for a full release.
Full List of Changes
Released in v25.02
- Added sort rules with automatic book sorting. (#5457, #2065)
- Added method to serve public files via the theme system. (#5405, #3904)
- Updated app framework to Laravel 11. (#5400)
- Updated codebase minimum PHP version from 8.1 to 8.2. (#5397)
- Updated codebase to address various PHP 8.4 deprecations. (#5491)
- Updated new WYSIWYG editor with a range of fixes. (#5415)
- Updated search indexing to handle guillemets. Thanks to @inv-hareesh. (#5475, #5471)
- Updated search indexing with advanced tokenization along with hyphen handling. (#5488, #2095)
- Updated sort handling to not increment the updated date for sorted content. (#1777)
- Updated translations with latest Crowdin changes. (#5409, #5399)
- Fixed incorrect image orientation handling. (#5462)
- Fixed layout issues at specific breakpoints. (#5396)
- Fixed LDAP error thrown when server does not provide a cn value. (#5443)
- Fixed wrong condition for showing new books list. Thanks to @Silverlan. (#5470)
Released in v24.12.1
- Updated export logic to have better temp file clean-up. (#5374, #5379)
- Updated in-app export endpoints to have rate limits. (#5379)
- Updated translations with latest Crowdin changes. (#5370)
- Updated PHP dependency package versions.
- Fixed markdown editor focus jumping on image insert. (#5384)
Header Image Credits: Photo by Julian Herzog (CC-BY-4) - Image Modified
