Beta Release v0.29.0

This Easter BookStack release welcomes a range of user-experience improvements, with features such as dark mode and improved right-to-left text support, in addition to a bunch of fixes and enhancements.

Dark Mode

BookStack now has a built-in dark mode. Here’s a comparison of the same content shown in both dark and light mode:

Dark Mode

Click to open larger view.

The dark mode covers all areas of the system including both the WYSIWYG and markdown editors. Where possible, page content such as tables & code blocks will react and change to be suitable dark alternatives. Vibrant theme-color elements, such as the header bar, will be automatically dimmed and de-saturated so they don’t stand-out or remain overly-bright on an otherwise dark page.

The option is user-selectable, from either the home-screen on via the top-right profile menu:

Dark Mode Toggle

This can be toggled at any point and the current preference will be saved to the user. For non-logged-in users, their preference will be saved to their browsing session.

A massive thanks to @domainzero on GitHub for tiding-over the BookStack community with a well-supported dark theme for the last few years.

Custom Option

Previously in BookStack the URL for (now was hard-coded within the BookStack code. This has now been exposed and can be customised as an .env option meaning you can tweak the embed behaviour or even use your own self-hosted instance.

Details for using this option can be found here.

Shelf Grid View

When viewing a single shelf, it’s now possible to toggle between grid & list view for the books within:

Shelf Grid View

This aligns the shelf page with the view options available on the “Books” page. A big thanks to @philjak for contributing this feature.

List of Shelves for Books

Previously in BookStack it was not easy to see the shelves a book is assigned to. In this release, A list of assigned shelves can now be seen when viewing a book:

Book shelves list

Big thanks to @cw1998 for contributing this feature to BookStack.

API Updates

The API has been expanded upon with the ability to perform CRUD operations on shelves. In addition, books have received endpoints for exporting their contents as HTML, PDF or plain-text. You’ll be able to find details of these when accessing the API docs in your instance, after updating.

API Endpoint Updates

Instance URL Update Command

Since BookStack hard-codes system URL’s in the database, a change in the domain used for your instance meant that some manual SQL commands needed to be ran to update the domain in the relevant tables & columns. In this release a command has been added to make this much quicker & easier, You just run the command providing your old and new URL and all the required columns will be updated.

Here’s and example of running this command:

$ php artisan bookstack:update-url http://bookstack.local    

 This will search for "http://bookstack.local" in your database and replace it with  "".
Are you sure you want to proceed? (yes/no) [no]:
 > yes

 This operation could cause issues if used incorrectly. Have you made a backup of your existing database? (yes/no) [no]:
 > yes

Updated 0 rows in attachments->path
Updated 26 rows in pages->html
Updated 0 rows in pages->text
Updated 8 rows in pages->markdown
Updated 394 rows in images->url
Updated 0 rows in comments->html
Updated 0 rows in comments->text
URL update procedure complete.

The command has been added to the command documentation found here.

Improved RTL System UI Support

For this release the core styles have been revised to work better for right-to-left (RTL) languages:

RTL Styling

Previously the BookStack UI would remain left-to-right (LTR), even when a RTL language was in use. Setting the html to display as RTL would cause most of the views to break as the styles were defined with LTR in mind.

For v0.29, we’ve made heavy use of CSS logical properties and values to ensure our styles work as expected when showing in an RTL format. Although, as of writing, the spec for logical properties is in draft it is well supported amongst the modern browsers we support, albeit with a few omissions.


Our fantastic community of translators continue to provide their great efforts as this release brings updates from the below languages by the below great Crowdin & GitHub members:

  • Hasan Özbey (the-turk) - Turkish
  • mrjaboozy - Slovenian
  • rcy - Swedish
  • Ali Yasir Yılmaz (ayyilmaz) - Turkish
  • m0uch0 - Spanish
  • scureza - Italian
  • Statium - Russian
  • Biepa - German Informal; German
  • Finn Wessel (19finnwessel6) - German
  • nutsflag - French
  • syecu - Chinese Simplified
  • Rodrigo Saczuk Niz (rodrigoniz) - Portuguese, Brazilian
  • Lap1t0r - French
  • Thinkverse (thinkverse) - Swedish
  • milesteg - Hungarian
  • @jzoy - Chinese

Full List of Changes

  • Added a user-selectable dark-mode option. (#2022, #1234)
  • Added the ability to define a custom URL and therefore use a custom instance if preferred. (#826)
  • Added grid-view support, with toggle, to the shelf view. Thanks to @philjak. (#1755, #1221)
  • Added a list of bookshelves that a book belongs when viewing a book. Thanks to @cw1998. (#1688, #1598)
  • Added a new command to update your BookStack URL in the database. (#1225)
  • Added shelf API endpoints. Thanks to @osmansorkar. (#1908)
  • Added book-export API endpoints.
  • Updated password reset flows to avoid indicating if a email is in use within the system. (#2016)
  • Updated WYSIWYG entity-link-insert to set link text to entity name, if input is empty. (#2014)
  • Updated styles with better RTL support through the use of CSS logical properties/values. (#2003)
  • Updated the name of saved drawings to not include the user’s name, to prevent issues with non-standard characters. (#1993)
  • Removed BMP and TIFF from the list of allows image upload types since these could not be resized properly. (#1990)
  • Updated code-block insert to handle focus, so code blocks can be inserted smoothly via keyboard alone. (#1972)
  • Updated namespacing used in tests to avoid warnings on recent versions of composer. (#1924)
  • Updated Chinese translations. Thanks to @jzoy. (#2023)
  • Updated translations for Turkish, Slovenian, Swedish, Spanish, Italian, Russian, German Informal, German, French, Chinese Simplified, Portuguese, Brazilian & Hungarian. Thanks to Crowdin Users.
  • Updated default .htaccess to allow Authorization header for API usage. Thanks to @osmansorkar. (#1908)
  • Updated GitHub authorization library to avoid use of deprecated auth methods. (#1879)
  • Fixed issue where ordered list numbers could be cut-off. This was most apparent on Safari.(#1978)

Next Steps

For the next release I’ll look to continue expanding the range of API endpoints. Would be nice to get the core chapter & page actions done. As per my “v0.28 next steps”, I’ll look to align how activity is tracked. The first steps will likely be to expand the range of tracked actions then expose everything within the admin area in a filterable “Audit Trail”.

Header Image Credits:   unsplash-logoVictor Larracuente