BookStack Release v24.12

Dan Brown posted on the 23rd of December 2024

For this Christmas time period we have BookStack v24.12 which includes the gift of a new import & export format, while improving upon the new editor introduced in the last release.

• Update instructions
• GitHub release page

Upgrade Notices

• Requirements Change - The PHP “zip” extension is now a requirement for BookStack. If you installed via our Ubuntu scripts, this should already be installed.

New Importable Export Format

A new “Portable ZIP” export option is now available for books, chapters & pages:

This exports your content within a compressed ZIP file, containing common related data including tags, attachments and images.

These ZIP files can then be imported back into your instance, or you could even import these into other BookStack instances (if they’re on v24.12 or greater). During the import process, you’re provided an overview of the content you’re due to import and are able to choose the target parent location (for chapter and page imports):

Upon import, all the content of the ZIP will be added to the target BookStack instance, with attachments & images uploaded into the system, and links between items in the import handled to point to the correct location in the target instance.

To support this addition, A new “Import content” role permission has been added which will only be assigned to admin level roles by default (those who can change app settings). With this permission assigned, a user can access the “Import” area via the actions on the Books page.

On this page you can upload a ZIP to start an import, or see existing pending imports. Users will only see their own import uploads by default, but users with permission to change app settings will be able to see all pending imports from all users.

The ZIP format & structure has been specifically designed to be simple and easy to understand, and it’s fully documented here to ensure the format is accessible to developers.

To be clear, this is not intended as a backup format. There’s a lot of metadata that is not part of these exports, so backups should still be done at an instance level following our guidance. That said, I’m excited about the wide array of possibilities for such a portable and stable common import/export format. Here’s some ideas in how this new format could be potentially used:

• Export & import of template books.
• Sharing books between different BookStack instances.
• A target format for building migration tools.
• Easier access/display of content in external applications.
• A way to “Promote” content from a “Staging” instance to a “Production” instance.

One notable limitation is that there’s not yet any export/import API endpoints provided for this format. This was initially planned, but I want delay that for a while to ensure the process we have works, before adding API support since there’d otherwise be a significant chance of API breaking changes.

New WYSIWYG Editor Updates

In the last release we introduced the new WYSIWYG editor in alpha testing. It remains in an alpha-testing state for this release, but it’s received a number of significant improvements:

• Dark mode is now supported.
• The UI will now properly adapt for mobile screen sizes.
• URLs will auto-link on enter/space.
• An “About/help” modal & button have been added.
• Behaviour of collapsible blocks has been improved & made consistent.
• Selection and nesting behaviour of lists has been improved.

Upon these user-facing improvements, more work has gone into merging & developing the underlying codebase for this editor since I decided to fork in the Lexical editor core code late in the last development cycle.

API Improvements

A couple of existing API endpoints have received enhancements for this release:

• The /api/search endpoint will now include parent chapter/book names for easier access & display in search results lists.
• Cover image details are now provided on the /api/books and /api/shelves endpoints.

Thanks to @rashadkhan359 for their contributions as part of these improvements.

LDAP: Support for multiple name attributes

For those using LDAP for authentication, it’s now possible to make use of multiple LDAP attributes for a user’s name. To do this, you can just define multiple attributes in the LDAP_DISPLAY_NAME_ATTRIBUTE setting separated with a pipe like so:

1

LDAP_DISPLAY_NAME_ATTRIBUTE="firstname|lastname"

Values of those properties will then be combined with a space. In the above example, upon first login, if the LDAP user data has a firstname of Barry and a lastname of Chuckle, their name in BookStack would be Barry Chuckle as a result.

Thanks to @MatthieuLeboeuf for working on this one!

Translations

A big thanks to all the below terrific textual transformers who have helped translate the BookStack UI into a range of different languages since our last feature release:

• Ásgeir Shiny Ásgeirsson (AsgeirShiny) - Icelandic - 4580 words
• Michele Bastianelli (makoblaster) - Italian - 1090 words
• Avishay Rapp (AvishayRapp) - Hebrew - 699 words
• Mohammad Aftab Uddin (chirohorit) - Bengali - 1683 words
• Yannis Karlaftis (meliseus) - Greek - 547 words
• felixxx - German Informal - 315 words
• Jeff Huang (s8321414) - Chinese Traditional - 515 words
• Jøran Haugli (haugli92) - Norwegian Bokmal - 312 words
• m0uch0 - Spanish - 332 words
• sarahalves7 - Portuguese, Brazilian - 301 words
• Tim (thegatesdev) - Dutch - 183 words
• randi (randi65535) - Korean - 95 words
• Ngoc Lan Phung (lanpncz) - Vietnamese - 52 words
• Maciej Lebiest (Szwendacz) - Polish - 49 words
• ka_picit - Danish - 36 words
• Guttorm Hveem (guttormhveem) - Norwegian Nynorsk - 35 words
• Mohammed srhiri (m.sghiri20) - Arabic - 21 words
• YongMin Kim (kym0118) - Korean - 22 words
• Mykola Ronik (Mantikor) - Ukrainian - 20 words
• scureza - Italian - 20 words
• Martin Sebek (sebekmartin) - Czech - 20 words
• toras9000 - Japanese - 56 words
• grobert63 - French - 22 words
• Rivo Zängov (Eraser) - Estonian - 15 words
• ИEØ_ΙΙØZ (NEO_IIOZ) - Chinese Traditional - 21 words
• madnjpn (madnjpn.) - Georgian - 4 words
• 10935336 - Chinese Simplified - 4 words
• test65428 - Greek - 5 words
• petr.husak - Czech - 2 words
• Francisco Rafael Fonseca (chicoraf) - Portuguese, Brazilian - 2 words

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

Next Steps

Our next main release will probably be a maintenance release. With PHP 8.4 we’re hitting a lot of PHP deprecations which we can’t overcome without updating our framework and minimum PHP version, so we’ll probably get our yearly update in that regard out the way a bit sooner, but dropping PHP 8.1 support will need a little extra work due to its widespread use.

I’d also like to tie up some loose ends, like provide some more options for the PDF export command we added this year.

Lastly I’m planning to spend a bit more time on the new editor so it can move into a more “Beta” status for the next release to continue it’s journey to eventually becoming the default option.

Full List of Changes

Released in v24.12

• Added new portable ZIP import/export format. (#5260, #43)
• Added support for concatenating multiple LDAP attributes in displayName. Thanks to @MatthieuLeboeuf. (#5295, #1684)
• Added book and chapter titles to search API results. Thanks to @rashadkhan359. (#5280, #5140)
• Added cover image details to book/shelf API list responses. (#5180)
• Updated dev dockerfile setup to simplify things. Thanks to @johnroyer. (#5293)
• Updated guest account form to hide language preference to prevent confusion. (#5356)
• Updated new WYSIWYG editor codebase to merge nodes & re-organise code. (#5349)
• Updated notification handling to not block user with errors on send failures. (#5315)
• Updated our JavaScript service files to TypeScript. (#5259)
• Updated project NPM package & SASS deprecations/changes. (#5354)
• Updated the new WYSIWYG editor with a range of fixes/updates. (#5365)
• Updated translations with latest Crowdin changes. (#5345)
• Fixed API attachment update issue when name not provided. (#5353)
• Fixed attachment actions showing when lacking permissions. (#5323)
• Fixed missing book description and formatting in markdown exports. Thanks to @czemu. (#5313)
• Fixed page indexing breaking with very large pages. (#5322)

Released in v24.10.3

• Updated PHP dependency package versions.
• Updated translations with latest Crowdin changes. (#5331)
• Fixed attachment stream handling for better Chrome video support. (#5342, #5088)
• Fixed page include issue caused by PHP 8.3.14 bug. (#5341)
• Fixed OIDC userinfo handling when response included charset content type. Thanks to @wesbiggs. (#5337)
• Fixed differing code line height between dark/light modes. (#5146)

Released in v24.10.2

• Updated application PHP dependencies.
• Updated translations with latest Crowdin changes. (#5317)

Released in v24.10.1

• Updated System CLI with fixes and updated dependencies. (#5312)
• Fixed update-url command not updating revisions & drafts. (#5292)
• Fixed the namespaces of some tests. Thanks to @LordSimal. (#5291, #5071)
• Fixed misaligned user input validation. (#5263)
• Updated setting categories to validate by for existing views, allowing custom categories to be used via the theme system. Thanks to @LachTrip. (#5255, #5251)
• Updated translations with latest Crowdin changes. (#5250)

Header Image Credits: Photo by Tagooty (Timothy A. Gonsalves) (CC-BY-SA-4) - Image Modified