categories = ["Releases"]
tags = ["Releases"]
title = "BookStack Release v25.11"
-date = 2025-11-05T08:47:00Z
+date = 2025-11-09T13:00:00Z
author = "Dan Brown"
image = "/images/blog-cover-images/cc-by-sa-4/autumn-train-david-gubler.jpg"
slug = "bookstack-release-v25-11"
-draft = true
+draft = false
+++
Today arrives BookStack v25.11 which makes some significant changes to the
**Upgrade Notices**
- **Large Database Changes** - Significant changes have been made to the database structure. It's essential you have good backups for your instance before updating, and that you allow extra time for the database to migrate during the update process. On large instances this could be in the range of minutes rather than seconds.
-- **Caching** - The `APP_NAME` env option is now not used for the cache key. This option was never documented at all, but if you used this to prevent cache collisions please instead use the `CACHE_PREFIX` option.
+- **Caching** - The `APP_NAME` env option is no longer used for the cache key. This option was never documented at all, but if you used this to prevent cache collisions please instead use the `CACHE_PREFIX` option.
-TODO - Check/review text
-
-TODO - Video
-
-<!-- {{<pt ffZqEoZHLwzVwmKaGYsA3A>}} -->
+{{<pt gGtybS3iP7H8kAYRWvjEUo>}}
### Database Changes
-For each version of BookStack before today, each element of the content
-hierarchy (Shelves, Books, Chapters and Pages) had their own table in the database
-which does afford simplicity and ease-of-use for most developer scenarios.
-This separate table format is not so great though if we need to query across different
+For every version of BookStack before today, each element of the content
+hierarchy (Shelves, Books, Chapters and Pages) had their own database table
+which affords simplicity and ease-of-use for most developer scenarios.
+This separate table format is not so great when we need to query across different
types of items which is very common in BookStack, in areas such as activity lists, book contents,
search results, and many other areas.
-This would result in inefficient unions across tables or making extra queries per item type.
+This would result in making extra queries per item type or performing inefficient unions across tables.
In some cases, this would present as quirks to the end-user. An example of this
is the BookStack search results, which do not have a stable page-count (including via the API) while
not being able to sort relevancy across item types and result pages as we'd really like.
In this release the structure has changed significantly, merging the core information of
all hierarchy elements into a single table, where they can be indexed & queried as one set of data,
-while more unique item-specific data is placed into one of two tables.
+while more unique item-specific data is placed into one of two secondary tables.
-The results of this are fewer database queries in many areas, leading to faster and more
-responsive system. This also allows us to have better search result quality, stability, and
-enables us to have proper stable paging of search results:
+The results of this are fewer database queries in many areas, leading to a faster and more
+responsive system. This also allows us to have better search result quality, stability, and paging of search results:
-As development goes on we'll update more areas of the application to make use
-of this more efficient structure. This newer structure also has the benefit of
+As development goes on we'll update further areas of the application to make use
+of this more efficient structure. This approach also has the benefit of
fewer database changes and performance implications in the event we add a new hierarchy item
in the future.
### App Time-zones
This release adds a new `APP_DISPLAY_TIMEZONE` option, which allows you to define a separate
-time-zone which will be used for absolute dates shown in-app.
-This will default to the existing `APP_TIMEZONE`, can now be used to define
+time-zone which will be used for absolute dates shown within the user interface.
+This will default to the existing `APP_TIMEZONE`, but that can now be instead used to define
just the storage time-zone format for date-times in the database.
-Generally, it's a good idea to set `APP_TIMEZONE` UTC, to keep it stable & standard, then
+Generally it's a good idea to set `APP_TIMEZONE` to UTC, so it's stable & standard, then
use `APP_DISPLAY_TIMEZONE` to configure the time-zone for which most users would be considered within.
As part of these changes, we've also gone through all the locations where absolute times are shown
-As seen above, display of absolute times will now include the short-hand time-zone so the reader can be sure to understand exactly what time it represents, regardless
-of if they're in the same time-zone as configured at an application-level or not.
+As seen above, display of absolute times will now include a short-hand time-zone indicator so the reader can be sure to understand exactly what time it represents, regardless
+of if they're in the same time-zone or not.
Further details about these options can be [found in our documentation here](/docs/admin/language-config/#time-zones).
-### New Code Language Highlighting: Groovy
+### Groovy Code Language Highlighting
-This release adds code syntax highlight support for Groovy,
+This release adds code syntax highlighting support for Groovy,
a Java-syntax-compatible object-oriented programming language for the Java platform:
-### New Flags for the "Create Admin" command
+This will show as an option in the WYSIWYG code editor, or can be utilised in the markdown editor by using `groovy` in the opening code block tag.
+
+### New Flags for the "Create Admin" Command
-The [create admin command](/docs/admin/commands/#create-an-admin-user) has received a couple of additional options
+The [create admin command](/docs/admin/commands/#create-an-admin-user) has received a couple of new options
in this release:
* `--generate-password`: Generate a random password, and echo it back out as the only output on success.
-* `--initial`: Update the default admin@admin.com user if an existing admin, otherwise create a new admin user if there's no existing admin accounts.
+* `--initial`: Update the default admin@admin.com user if it exists, otherwise create a new admin user if there's no existing admin accounts, otherwise do nothing.
These new options provide the components needed to allow automation & scripts to have some control over the initial admin
user account in BookStack. This should allow our installation scripts, and any other third-party use/install method,
-to safely migrate over to having more secure initial accounts rather than having globally known default admin credentials.
+to safely migrate over to having more secure initial accounts rather than globally known default admin credentials.
This will be an ongoing change, as I reach-out to other projects to assist in using these more secure approaches, before
eventually removing the default user account creation entirely.
-### API - Docs Navigation Improvements
+### API: Docs Navigation Improvements
The API documentation, found at `/api/docs` within a BookStack instance, has a sidebar
-which was becoming quite long with all the endpoints & models being supported over time which
-was starting to make it more difficult to find what's needed.
+which was becoming quite long with all the endpoints & models being supported over time, making it more difficult to find what's needed.
In this release, the sidebar has now been organised with the main hierarchy elements
(pages, chapters, books and bookshelves) at the start, and everything below that in
-### API - Comments
+### API: Comments
Comments are now available as part of the BookStack REST API.
There's full create, read, update and delete actions available:
all comments for that page, formatted in the same thread-tree style as seen in the UI
to prevent extra client-side handling needed to replicate this format.
-### API - Image Data
+### API: Image Data
We've had image API endpoints for a while, but there was a limitation that the actual data could not be
-read via the API, outside of within exports, leaving images inaccessible in environments
-such as those using local_secure_restricted images.
+read via the API, outside of exports, leaving images inaccessible in environments
+such as those using `local_secure_restricted` image storage.
To address this, we have a couple of new endpoints:
Both of these endpoints will simply return the image data for the requested image, with one allowing
you to look-up image by ID, and the other by URL; the latter added as a convenience helper for direct
-data fetched based on image links within content.
+data fetching based on image links within content.
### Translations
### Codebase Updates
-In this release we upgrade the core framework used from Laravel 11 to Laravel 12.
-This is much earlier than usually, mostly thanks to being a minor upgrade which does
-not impose PHP minimum version changes.
+In this release we upgraded the core framework used from Laravel 11 to Laravel 12.
+This was done much earlier than usual, mostly thanks to being a minor upgrade which does
+not impose PHP minimum version changes and therefore doesn't impact BookStack's requirements.
Along with this, other codebase changes have been made such as:
-- Upgrading our static analysis to be more strict, and address a range of existing lack of typing.
+- Upgrading our static code analysis to be more strict, and address a range of existing lack of typing.
- Upgraded BookStack's PHP dependencies across major versions where needed.
- Updated permission checks to use enums instead of strings to avoid string-based-errors.
- Removed some redundant columns from the database, and added better clean-up & nullification of old IDs.
Since this release was so heavy on large back-end changes, I'd like the next one to be a
lighter release of little improvements which hopefully I can provide as a bit of a
-Christmas present for the end of December
+Christmas present for the end of December.
One of these improvements will be focused on building a more robust and focused slug/URL
tracking solution to further assist URL change resolution.
-Since it was skipped for this release due to time, I'll also look to include an initial
+Since it was skipped for this release cycle due to time, I'll also look to include an initial
developer API implementation for our new WYSIWYG editor.
### Full List of Changes
projects / website / commitdiff
