BookStack Code Mirror - website/blob - content/blog/2023/bookstack-release-v23-12.md

   1 +++
   2 categories = ["Releases"]
   3 tags = ["Releases"]
   4 title = "BookStack Release v23.12"
   5 date = 2023-12-28T11:43:00Z
   6 author = "Dan Brown"
   7 image = "/images/blog-cover-images/cc-by-sa-4/mountains-milan-bališin.jpg"
   8 slug = "bookstack-release-v23-12"
   9 draft = false
  10 +++
  11
  12 As a little Christmas-time treat we have BookStack v23.12 slipping in as the last
  13 release of the year. This release focuses on providing a simple WYSIWYG editor
  14 for description inputs, along with adding default page templates within books,
  15 in addition to some other additional gifts.
  16
  17 * [Update instructions](/docs/admin/updates)
  18 * [GitHub release page](https://github.com/BookStackApp/BookStack/releases/tag/v23.12)
  19
  20 **Upgrade Notices**
  21
  22 - **Page Includes** - The way page include content is fetched & merged has changed significantly in this release,
  23    which in some cases may alter how included content appears on the page.
  24 - **Prior Security Release** - Prior version v23.10.3 was a security release. If you missed this before, further details about that [can be found on the blog here](/blog/bookstack-release-v23-10-3/).
  25
  26 Video - TODO
  27 <!-- {{<pt 4YtVndveEVE6GuuGPV3Yn1>}} -->
  28
  29 ### WYSIWYG Editor for Descriptions
  30
  31 In BookStack we have description fields for chapters, books and shelves which allow a little bit of explanation & context to be provided for those items.
  32 These have always been simple plaintext fields, but as of v23.12 you'll now see a simple WYSIWYG input box instead with a few formatting controls:
  33
  34 ![A "description" part of a form, showing a WYSIWYG input box with some content that includes italic, bold and linked content, and a toolbar with 5 formatting buttons at the top of the input box](/images/2023/12/wysiwyg_description_input.png)
  35
  36 Formatting options include, and are limited to: bold, italic, links, bullet lists and numbered lists.
  37 The formatting is purposefully limited here to keep main content within pages, but allow a little formatting along with linking to relevant pages where required.
  38 Since links can now be placed within descriptions, references to other items will now be tracked via the existing reference system:
  39
  40 ![View of the "References" for a page, showing four incoming references, one each from a book, chapter, shelf and page](/images/2023/12/references_from_descriptions.png)
  41
  42 For API users, new `description_html` fields now exist on responses & requests to interact with this field in a HTML-aware manner, otherwise the pre-existing `description` fields will continue to work as before.
  43
  44 ### Default Template For New Book Pages
  45
  46 We've long since supported page [templates](/docs/user/page-templates/) within BookStack but to be used an editing user would have to access the relevant sidebar menu within the page editor, meaning they could be easy to miss or ignore. Additionally, it would be a common desire to use a template for all pages created within a certain context.
  47 In this release, a new option for books allows you to set a default page template:
  48
  49 ![A view of the form for editing a Book, focused on a "Default Page Template" section with a "Development Plan Template" item selected](/images/2023/12/book_default_page_template.png)
  50
  51 When set, this template page will be used as the default content for all new pages within that book, preventing the need to select the template within the editor each time you create something new. Note though, this is still permission controlled so the template will only be used if the page creator has view access to the template assigned.
  52
  53 A big thanks to [@lennertdaniels](https://github.com/BookStackApp/BookStack/pull/3918) for performing the initial implementation work to move this forward within BookStack!
  54
  55 ### OIDC RP-Initiated Logout
  56
  57 OpenID-Connect authentication in BookStack allows for easy login via an external system, but so far it's lacked any kind of logout support.
  58 That changes in this release thanks to efforts by [@joancyho](https://github.com/BookStackApp/BookStack/pull/4467) to introduce OIDC RP-Initiated logout support.
  59 This official [complementary part of the OIDC spec](https://openid.net/specs/openid-connect-rpinitiated-1_0.html) allows an application like BookStack to request logout of the external authentication system as part of the application's logout flow.
  60
  61 BookStack's support of this includes the use of autodiscovery to learn the logout endpoint.
  62 If you want to use RP-initiated logout you'll need to configure a `OIDC_END_SESSION_ENDPOINT` option for BookStack:
  63
  64 ```bash
  65 # Set to true to enable logout via a URL found via auto-discovery:
  66 OIDC_END_SESSION_ENDPOINT=true
  67
  68 # Or configure a specific URL to be used for RP-initiated logout:
  69 OIDC_END_SESSION_ENDPOINT="https://instance.authsystem.example.com/logout"
  70
  71 # Or disable RP-initiated logout (default):
  72 OIDC_END_SESSION_ENDPOINT=false
  73 ```
  74
  75 It's likely you'll need to also configure logout/sign-out URIs on your OIDC authentication system for your BookStack application instance.
  76 Our [OIDC documentation](/docs/admin/oidc-auth/#authentication-system-configuration) has been updated with details of these URIs.
  77
  78 During testing I've validated this system to work with Okta, KeyCloak, Azure, Authentik and Auth0; so support for this part of the
  79 standard by authentication services seems pretty widespread.
  80
  81 ### Page Context in Email Notifications
  82
  83 A couple of releases ago we added email notifications for certain page activities, and these notifications would include
  84 a name and link for the page interacted upon. Sometimes though, it may not be clear where the activity has occurred from the
  85 page name alone since it could be a page name used multiple times, or lacking context without knowing where that page is located.
  86 To help add that context, notifications will now reflect the page parent book, and chapter if within:
  87
  88 ![A screenshot of a BookStack notification message, showing a new "Page Path" detail with the text: "Accounts Department > Pension Providers"](/images/2023/12/notification_page_context.png)
  89
  90 A big thanks to [@Man-in-Black](https://github.com/BookStackApp/BookStack/pull/4629) for contributing this functionality.
  91
  92 ### Friendlier Buttons
  93
  94 For a long time BookStack has used buttons with forced upper-case text, the design of which was getting a bit long in the tooth
  95 while potentially coming across somewhat angry via their shouty appearance.
  96 For this release, the design of buttons has been tweaked a little to better fit them into the current design, rounding the corners
  97 a little more, tweaking the shadows upon hover and, most importantly, using the casing from the source translation text:
  98
  99 ![Four buttons, comparing the old and new design](/images/2023/12/button_design_update.png)
 100
 101 In most cases buttons will now appear as Title Case, although this can now change to suit different languages as needed as it's not forced
 102 by design.
 103
 104 ### Logical Theme System Events to Register Routes
 105
 106 This release I've added a couple of new events to the [logical theme system](https://github.com/BookStackApp/BookStack/blob/development/dev/docs/logical-theme-system.md)
 107 to allow easier registration of custom web routes/endpoints where desired. As an example of these:
 108
 109 ```php
 110 <?php
 111
 112 use BookStack\Theming\ThemeEvents;
 113 use BookStack\Facades\Theme;
 114 use Illuminate\Routing\Router;
 115
 116 // Register a custom "/counter" endpoint which increments each time accessed
 117 Theme::listen(ThemeEvents::ROUTES_REGISTER_WEB, function (Router $router) {
 118
 119     $router->get('/counter', function () {
 120         $count = session()->get('counter', 0) + 1;
 121         session()->put('counter', $count);
 122         return "Count: {$count}";
 123     });
 124 });
 125
 126 // Register a custom "/counter-auth" endpoint which increments each time accessed
 127 // like above but only if the user is logged in (or public access is enabled).
 128 Theme::listen(ThemeEvents::ROUTES_REGISTER_WEB_AUTH, function (Router $router) {
 129
 130     $router->get('/counter-auth', function () {
 131         $count = session()->get('secret-counter', 0) + 1;
 132         session()->put('secret-counter', $count);
 133         return "Count Authed: {$count}";
 134     });
 135 });
 136 ```
 137
 138 It was possible to register such routes previously, but you had to register them in a very specific way
 139 using internally named middleware, in the right order, otherwise you'd have issues with session & user access.
 140 These new events are intended to make this much simpler.
 141
 142 ### Rebuilt Page Include Engine
 143
 144 When [reusing page content](/docs/user/reusing-page-content/) BookStack has always processed include tags via quite
 145 a simple find/replace approach, which worked well for the most part but could lead to technically invalid syntax in some
 146 cases due to nested paragraphs and other oddities, which may cause unpredictable issues in how pages would display
 147 with include tags.
 148
 149 In this release, the engine for page include tags has been rebuilt to specifically be more content aware,
 150 avoiding invalid structure where possible by smartly splitting existing blocks or moving included content to
 151 appropriate locations if needed.
 152
 153 ### Translations
 154
 155 Before the year closes out we have one more new language made available in BookStack, and that is Finnish!
 156 A big thanks to the [Crowdin user ajnyga](https://crowdin.com/profile/ajnyga/activity) for all their efforts
 157 translating for Finnish up to the point where we can include it.
 158
 159 Once again a big thanks to all the exceptionally eloquent experts in language who've contributed
 160 translations since our last feature release:
 161
 162 - Eduard Ereza Martínez (Ereza) - *Catalan - 7160 words*
 163 - Antti-Jussi Nygård (ajnyga) - *Finnish - 6108 words*
 164 - Guttorm Hveem (guttormhveem) - *Norwegian Nynorsk; Norwegian Bokmal - 2718 words*
 165 - toras9000 - *Japanese - 1045 words*
 166 - Vitaliy (gviabcua) - *Ukrainian - 922 words*
 167 - poesty - *Chinese Simplified - 635 words*
 168 - Jabir Lang (amar.almrad) - *Arabic - 480 words*
 169 - Sascha (Man-in-Black) - *German Informal; German - 443 words*
 170 - pedromcsousa - *Portuguese - 372 words*
 171 - Jaroslav Koblizek (foretix) - *Czech; French - 365 words*
 172 - Felipe Cardoso (felipecardosoruff) - *Portuguese, Brazilian - 348 words*
 173 - SmokingCrop - *Dutch - 324 words*
 174 - sdhadi - *Persian - 284 words*
 175 - Indrek Haav (IndrekHaav) - *Estonian - 250 words*
 176 - Konstantin (kkovacheli) - *Ukrainian; Russian - 246 words*
 177 - Wiktor Adamczyk (adamczyk.wiktor) - *Polish - 184 words*
 178 - Maciej Lebiest (Szwendacz) - *Polish - 164 words*
 179 - Abdulmajeed Alshuaibi (4Majeed) - *Arabic - 114 words*
 180 - scureza - *Italian - 99 words*
 181 - m0uch0 - *Spanish - 99 words*
 182 - HyoungMin Lee (ddokkaebi) - *Korean - 67 words*
 183 - Dasferco - *Chinese Simplified - 64 words*
 184 - NotSmartZakk - *Czech - 62 words*
 185 - TheRazvy - *Romanian - 55 words*
 186 - Martins Pilsetnieks (pilsetnieks) - *Latvian - 49 words*
 187 - balmag - *Hungarian - 25 words*
 188 - Serkan Yardim (serkanzz) - *Turkish - 14 words*
 189 - LameeQS - *Latvian - 12 words*
 190 - Marcus Teräs (mteras) - *Finnish - 10 words*
 191 - Y (cnsr) - *Ukrainian - 7 words*
 192 - ZY ZV (vy0b0x) - *Chinese Simplified - 6 words*
 193 - diegobenitez - *Spanish - 4 words*
 194 - Sorin T. (trimbitassorin) - *Romanian - 3 words*
 195 - Marc Hagen (MarcHagen) - *Dutch - 1 words*
 196
 197
 198 *\* Word counts are those tracked by Crowdin, indicating original EN words translated.*
 199
 200 ### Next Steps
 201
 202 Now we have a simpler WYSIWYG editor, as implemented for descriptions in this release, I'll probably be looking to carry this across to the comments system to provide that with simple WYSIWYG editing, although this will require some breaking changes to the currently supported markdown content of this input.
 203
 204 Upon that, over the initial few weeks of this year I'd like to explore some of the new PHP-ecosystem technologies like roadrunner and/or FrankenPHP to understand their potential benefit to BookStack.
 205
 206 Over the next few days I'll be putting together a "BookStack in 2023" blogpost, like [done previous years](https://www.bookstackapp.com/blog/bookstack-in-2022/) to look back and assess the progress of the project over the last year.
 207
 208 ### Full List of Changes
 209
 210 **Released in v23.12**
 211
 212 * Added simple WYSIWYG for description fields. ([#4729](https://github.com/BookStackApp/BookStack/pull/4729), [#2354](https://github.com/BookStackApp/BookStack/issues/2354), [#2203](https://github.com/BookStackApp/BookStack/issues/2203))
 213 * Added default template option for books. Thanks to [@lennertdaniels](https://github.com/BookStackApp/BookStack/pull/3918). ([#4721](https://github.com/BookStackApp/BookStack/pull/4721), [#3918](https://github.com/BookStackApp/BookStack/pull/3918), [#1803](https://github.com/BookStackApp/BookStack/issues/1803))
 214 * Added OIDC RP-initiated logout. Thanks to [@joancyho](https://github.com/BookStackApp/BookStack/pull/4467). ([#4714](https://github.com/BookStackApp/BookStack/pull/4714), [#4467](https://github.com/BookStackApp/BookStack/pull/4467), [#3715](https://github.com/BookStackApp/BookStack/issues/3715))
 215 * Added new Logical Theme System event to register web routes. ([#4663](https://github.com/BookStackApp/BookStack/issues/4663))
 216 * Updated email notifications to include the page parent chapter/book. Thanks to [@Man-in-Black](https://github.com/BookStackApp/BookStack/pull/4629). ([#4629](https://github.com/BookStackApp/BookStack/pull/4629))
 217 * Updated and standardised DOM handling in the codebase. ([#4673](https://github.com/BookStackApp/BookStack/pull/4673))
 218 * Updated back redirection handling to not rely on referrer headers. ([#4656](https://github.com/BookStackApp/BookStack/issues/4656))
 219 * Updated book/chapter/shelf description character limit. ([#4085](https://github.com/BookStackApp/BookStack/issues/4085))
 220 * Updated design of buttons to be a bit friendlier. ([#4728](https://github.com/BookStackApp/BookStack/pull/4728))
 221 * Updated HTML exporting with better RTL handling. ([#4645](https://github.com/BookStackApp/BookStack/issues/4645))
 222 * Updated include tag handling to be structure/DOM aware. ([#4688](https://github.com/BookStackApp/BookStack/pull/4688))
 223 * Updated SAML2 dump debug option to include group parsing details. ([#4706](https://github.com/BookStackApp/BookStack/issues/4706))
 224 * Updated translations with latest Crowdin changes. ([#4658](https://github.com/BookStackApp/BookStack/pull/4658))
 225 * Updated WYSIWYG editor to allow video/embed alignment controls. ([#4727](https://github.com/BookStackApp/BookStack/pull/4727), [#3378](https://github.com/BookStackApp/BookStack/issues/3378))
 226 * Updated WYSIWYG library TinyMCE from 6.5.1 to 6.7.2. ([#4661](https://github.com/BookStackApp/BookStack/pull/4661))
 227 * Fixed extra paragraphs & invalid syntax when using page includes. ([#3385](https://github.com/BookStackApp/BookStack/issues/3385))
 228 * Fixed lack of user invite via the API in certain cases. ([#4720](https://github.com/BookStackApp/BookStack/issues/4720))
 229 * Fixed page includes leading to duplicate IDs. ([#3982](https://github.com/BookStackApp/BookStack/issues/3982))
 230 * Fixed permission generation failure with large amounts of content. ([#4695](https://github.com/BookStackApp/BookStack/issues/4695))
 231 * Fixed PHP mbstring deprecation warnings. ([#4638](https://github.com/BookStackApp/BookStack/issues/4638))
 232 * Fixed SAML2 Single Logout (SLO) not invalidating session at point defined by the spec. ([#4713](https://github.com/BookStackApp/BookStack/issues/4713))
 233
 234 **Released in v23.10.4**
 235
 236 This was simply a follow-up of v23.10.3 to fix the app version number.
 237
 238 **Released in v23.10.3**
 239
 240 * Updated thumbnail handling to fix use of content as image data. ([#4681](https://github.com/BookStackApp/BookStack/pull/4681))
 241
 242 **Released in v23.10.2**
 243
 244 * Fixed incorrect audit log dropdown behaviour. ([#4652](https://github.com/BookStackApp/BookStack/issues/4652))
 245 * Fixed redirects to the manfiest endpoint in some environments. ([#4649](https://github.com/BookStackApp/BookStack/issues/4649))
 246 * Updated translations with latest Crowdin changes. ([#4643](https://github.com/BookStackApp/BookStack/pull/4643))
 247
 248 **Released in v23.10.1**
 249
 250 * Added "Norwegian Nynorsk" to user language options.
 251 * Added JavaScript public event for customizing codemirror instances. ([#4639](https://github.com/BookStackApp/BookStack/issues/4639))
 252 * Added handling to allow jumping to headers/sections within collapsible sections. ([#4637](https://github.com/BookStackApp/BookStack/issues/4637))
 253 * Added PHP 8.3 support. ([#4633](https://github.com/BookStackApp/BookStack/issues/4633))
 254 * Updated translations with latest Crowdin changes. ([#4631](https://github.com/BookStackApp/BookStack/pull/4631))
 255 * Fixed header bar peeking through on markdown editor fullscreen mode. ([#4641](https://github.com/BookStackApp/BookStack/issues/4641))
 256 * Fixed incorrect color usage for editor toolbox active tabs. ([#4630](https://github.com/BookStackApp/BookStack/issues/4630))
 257
 258 ----
 259
 260 <span style="font-size: 0.8em;opacity:0.9;">Header Image Credits: <span>Photo by <a href="https://commons.wikimedia.org/wiki/File:Min%C4%8Dol_(vrch_v_%C4%8Cergove)_08.JPG">Milan Bališin (CC-BY-SA-4)</a> - Image Modified</span></span>