BookStack Code Mirror - website/blob - content/blog/2024/bookstack-release-v24-12.md

   1 +++
   2 categories = ["Releases"]
   3 tags = ["Releases"]
   4 title = "BookStack Release v24.12"
   5 date = 2024-12-24T13:00:00Z
   6 author = "Dan Brown"
   7 image = "/images/blog-cover-images/cc-by-sa-4/mountains-timothy-a-gonsalves.jpg"
   8 slug = "bookstack-release-v24-12"
   9 draft = false
  10 +++
  11
  12 For this Christmas time holiday season we have BookStack v24.12 which includes the gift of a
  13 new import & export format, while improving upon the new editor introduced in the last release.
  14
  15 * [Update instructions](/docs/admin/updates)
  16 * [GitHub release page](https://github.com/BookStackApp/BookStack/releases/tag/v24.12)
  17
  18 TODO - Peertube
  19
  20 **Upgrade Notices**
  21
  22 - **Requirements Change** - The "zip" PHP extension is now a requirement for BookStack. If you installed via our Ubuntu scripts, this should already be installed.
  23
  24 ### New Importable Export Format
  25
  26 A new export option is now available for books, chapters & pages: "Portable ZIP"
  27
  28 TODO - Image of export options
  29
  30 This exports your content within a compressed ZIP file, containing common
  31 related data including tags, attachments and images.
  32
  33 These ZIP files can then be imported back into your instance, or you could even
  34 import these into other BookStack instances (as long as they're on v24.12 or greater).
  35 During the import process, you're provided an overview of the content you're due to import
  36 and are able to choose the target parent location (for chapter and page imports):
  37
  38 TODO - Image of in progress Import overview
  39
  40 Upon import, all the content of the ZIP will be added to the target BookStack instance, with attachments & images
  41 uploaded into the system, and links between items in the import handled to point to the correct location in the target instance.
  42
  43 To support this addition, A new "Import content" role permission has been added
  44 which will only be assigned to admin level roles by default (those who can change app settings).
  45 With this permission assigned, a user can access the "Import" view via the actions on the Books list view.
  46
  47 TODO - Image of import list
  48
  49 On this page you can upload a ZIP to start an import, or see existing pending imports.
  50 Users will only see their own import uploads by default, but users with permission to change app settings
  51 will be able to see all pending imports from all users.
  52
  53 The ZIP format & structure has been specifically designed to be simple and easy to understand for developers.
  54 The format is [fully documented here](https://github.com/BookStackApp/BookStack/blob/development/dev/docs/portable-zip-file-format.md)
  55 so ensure the format is accessible to developers.
  56
  57 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
  58 should still be done at an instance level following our guidance.
  59 That said, there's a lot of opportunity that I'm excited about in this portable and stable common import/export format.
  60
  61 Here's some ideas in how this new format could be potentially used:
  62
  63 - Export & import template books
  64 - Sharing books between different BookStack instances
  65 - Target format for building migration tools
  66 - Easier access/display of content in external applications
  67 - A way to "Promote" content from a "Staging" instance to a "Production" instance
  68
  69 One notable limitation is that there's not yet API endpoints provided for import/export of this format.
  70 This was initially planned, but I want delay that for a while to ensure the process we have works, before adding API
  71 support since there'd otherwise be a significant chance of API breaking changes.
  72
  73 ### New WYSIWYG Editor Updates
  74
  75 In the [last release we introduced](/blog/bookstack-release-v24-10/#new-alpha-wysiwyg-editor-option)
  76 the new WYSIWYG editor in alpha testing. It remains in an alpha-testing state for this release, but
  77 it's received a number of improvements:
  78
  79 - Dark mode is now supported.
  80 - The UI will now properly adapt for mobile screen sizes.
  81 - URLs will auto-link on enter/space.
  82 - An "About/help" modal & button have been added.
  83 - Behaviour of collapsible blocks has been improved & made consistent.
  84 - Selection and nesting behaviour of lists has been improved.
  85
  86 Upon these user-facing improvements, work has gone into further merge & develop the underlying
  87 codebase for this editor since we decided to fork in the [Lexical](https://lexical.dev/) editor core code late in the last
  88 development cycle.
  89
  90 ### API Improvements
  91
  92 A couple of existing API endpoints have received enhancements for this release:
  93
  94 - The `/api/search` endpoint will now include parent chapter/book names for easier access & display in search results lists.
  95 - Cover image details are now provided on the `/api/books` and `/api/shelves` endpoints.
  96
  97 Thanks to [@rashadkhan359](https://github.com/BookStackApp/BookStack/pull/5280) for their contributions as part of these improvements.
  98
  99 ### LDAP: Support for multiple name attributes
 100
 101 For users using LDAP for authentication, it's now possible to make of multiple LDAP
 102 attributes for a user's name. To do this, you can just define multiple
 103 attributes in the `LDAP_DISPLAY_NAME_ATTRIBUTE` setting separated with a pipe like so:
 104
 105 ```bash
 106 LDAP_DISPLAY_NAME_ATTRIBUTE="firstname|lastname"
 107 ```
 108
 109 Values of those properties will then be combined with a space.
 110 In the above example upon first login, if the LDAP user data has a `firstname` of `Barry` and a
 111 `lastname` of `Chuckle`, their name in BookStack would be `Barry Chuckle` as a result.
 112
 113 Thanks to [@MatthieuLeboeuf](https://github.com/BookStackApp/BookStack/pull/5295) for working on this one!
 114
 115 ### Translations
 116
 117 TODO
 118
 119 - User - *Lang - x words*
 120
 121 *\* Word counts are those tracked by Crowdin, indicating original EN words translated.*
 122
 123 ### Next Steps
 124
 125 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
 126 overcome without updating our framework and minimum PHP version, we we'll probably get our yearly update in that regard out the way a
 127 little sooner, but dropping PHP 8.1 support will need a little extra work due to its widespread use.
 128
 129 I'd also like to tie up some loose ends, like provide some more options for the [PDF export command we added this year](/blog/bookstack-release-v24-05/#command-based-pdf-export-option).
 130 Other than that I'd like to spend a fair bit more time on the new editor so it can move into a more "Beta" status for the next release
 131 to continue it's journey to eventually becoming the default option.
 132
 133 ### Full List of Changes
 134
 135 **Released in v24.12**
 136
 137 * Added new portable ZIP import/export format. ([#5260](https://github.com/BookStackApp/BookStack/pull/5260), [#43](https://github.com/BookStackApp/BookStack/issues/43))
 138 * Added support for concatenating multiple LDAP attributes in displayName. Thanks to [@MatthieuLeboeuf](https://github.com/BookStackApp/BookStack/pull/5295). ([#5295](https://github.com/BookStackApp/BookStack/pull/5295), [#1684](https://github.com/BookStackApp/BookStack/issues/1684))
 139 * Added book and chapter titles to search API results. Thanks to [@rashadkhan359](https://github.com/BookStackApp/BookStack/pull/5280). ([#5280](https://github.com/BookStackApp/BookStack/pull/5280), [#5140](https://github.com/BookStackApp/BookStack/issues/5140))
 140 * Added cover image details to book/shelf API list responses. ([#5180](https://github.com/BookStackApp/BookStack/issues/5180))
 141 * Updated dev dockerfile setup to simplify things. Thanks to [@johnroyer](https://github.com/BookStackApp/BookStack/pull/5293). ([#5293](https://github.com/BookStackApp/BookStack/pull/5293))
 142 * Updated guest account form to hide language preference to prevent confusion. ([#5356](https://github.com/BookStackApp/BookStack/issues/5356))
 143 * Updated new WYSIWYG editor codebase to merge nodes & re-organise code. ([#5349](https://github.com/BookStackApp/BookStack/pull/5349))
 144 * Updated notification handling to not block user with errors on send failures. ([#5315](https://github.com/BookStackApp/BookStack/issues/5315))
 145 * Updated our JavaScript service files to TypeScript. ([#5259](https://github.com/BookStackApp/BookStack/pull/5259))
 146 * Updated project NPM package & SASS deprecations/changes. ([#5354](https://github.com/BookStackApp/BookStack/pull/5354))
 147 * Updated the new WYSIWYG editor with a range of fixes/updates. ([#5365](https://github.com/BookStackApp/BookStack/pull/5365))
 148 * Updated translations with latest Crowdin changes. ([#5345](https://github.com/BookStackApp/BookStack/pull/5345))
 149 * Fixed API attachment update issue when name not provided . ([#5353](https://github.com/BookStackApp/BookStack/issues/5353))
 150 * Fixed attachment actions showing when lacking permissions. ([#5323](https://github.com/BookStackApp/BookStack/issues/5323))
 151 * Fixed missing book description and extra newlines in markdown exports. Thanks to [@czemu](https://github.com/BookStackApp/BookStack/pull/5313). ([#5313](https://github.com/BookStackApp/BookStack/pull/5313))
 152 * Fixed page content indexing breaking with very large amounts of content. ([#5322](https://github.com/BookStackApp/BookStack/issues/5322))
 153
 154 **Released in v24.10.3**
 155
 156 * Updated PHP dependency package versions.
 157 * Updated translations with latest Crowdin changes. ([#5331](https://github.com/BookStackApp/BookStack/pull/5331))
 158 * Fixed attachment stream handling for better Chrome video support. ([#5342](https://github.com/BookStackApp/BookStack/issues/5342), [#5088](https://github.com/BookStackApp/BookStack/issues/5088))
 159 * Fixed page include issue caused by PHP 8.3.14 bug. ([#5341](https://github.com/BookStackApp/BookStack/issues/5341))
 160 * Fixed OIDC userinfo handling when response included charset content type. Thanks to [@wesbiggs](https://github.com/BookStackApp/BookStack/pull/5337). ([#5337](https://github.com/BookStackApp/BookStack/pull/5337))
 161 * Fixed differing code line height between dark/light modes. ([#5146](https://github.com/BookStackApp/BookStack/issues/5146))
 162
 163 **Released in v24.10.2**
 164
 165 * Updated application PHP dependencies.
 166 * Updated translations with latest Crowdin changes. ([#5317](https://github.com/BookStackApp/BookStack/pull/5317))
 167
 168 **Released in v24.10.1**
 169
 170 * Updated System CLI with fixes and updated dependencies. ([#5312](https://github.com/BookStackApp/BookStack/pull/5312))
 171 * Fixed update-url command not updating revisions & drafts. ([#5292](https://github.com/BookStackApp/BookStack/issues/5292))
 172 * Fixed the namespaces of some tests. Thanks to [@LordSimal](https://github.com/BookStackApp/BookStack/pull/5291). ([#5291](https://github.com/BookStackApp/BookStack/pull/5291), [#5071](https://github.com/BookStackApp/BookStack/issues/5071))
 173 * Fixed misaligned user input validation. ([#5263](https://github.com/BookStackApp/BookStack/issues/5263))
 174 * Updated setting categories to validate by for existing views, allowing custom categories to be used via the theme system. Thanks to [@LachTrip](https://github.com/BookStackApp/BookStack/pull/5255). ([#5255](https://github.com/BookStackApp/BookStack/pull/5255), [#5251](https://github.com/BookStackApp/BookStack/issues/5251))
 175 * Updated translations with latest Crowdin changes. ([#5250](https://github.com/BookStackApp/BookStack/pull/5250))
 176
 177 ----
 178
 179 <span style="font-size: 0.8em;opacity:0.9;">Header Image Credits: <span>Photo by <a href="https://commons.wikimedia.org/wiki/File:Road_Padum_Zanskar_Range_Jun24_A7CR_00818.jpg">Tagooty (Timothy A. Gonsalves) (CC-BY-SA-4)</a> - Image Modified</span></span>