BookStack Release v21.08

Dan Brown posted on the 31st of August 2021

Today we release BookStack v21.08, which brings along multi-factor authentication support in addition to a number of other nice features. Within this post we’ll dive into some of the biggest new changes since the v21.05 release.

• Update instructions
• GitHub release page

Upgrade Notices

• Config & Administration - The introduction of multi-factor authentication brings the first use of encryption in the platform. This uses the APP_KEY value in your .env file. Ensure you have this stored safely since it would be required if you ever restore/migrate your instance to another system.
• Security/Exports - During this release cycle it was highlighted that server-side request forgery could be achieved via the PDF export system. External fetching in the default PDF renderer has been disabled by default. The WKHTMLtoPDF renderer will now not be used if active. Either of these changes can be overridden by setting ALLOW_UNTRUSTED_SERVER_FETCHING=true in your .env file. This should only be used were only trusted users can create and export content. To support this we’ve added permissions that allow disabling of exports per role.
• Security/Authentication - A slight change was made in relation to how email addresses are confirmed. Email confirmations are now primarily checked at point-of-login rather than being checked on every request. Enabling email confirmation, or email domain restrictions, may no longer take action on unconfirmed users right away in the future.

Multi-Factor Authentication

Multi-factor authentication (MFA) can now be enabled for user accounts in BookStack. Two different MFA methods are available in this initial release of the feature:

1. TOTP, Labelled as “Mobile App” (Google/Microsoft Authenticator etc…)
2. Backup Codes (A list of single-use codes)

MFA can be enabled by any user accounts in the system. It can be enforced at a per-role level via a new “Requires Multi-Factor Authentication” checkbox found when editing a role:

When required, users will be forced to setup at least one MFA method upon next login. For those with at least one method configured, the system will require an MFA method to be used upon login:

To help in the scenario where someone may lose their MFA credentials, a new system command has been added which will clear all MFA methods for the given user:

1

php artisan bookstack:reset-mfa --email=john@example.com

This feature was more effort than expected, partially due to needing to refactor how authentication is performed within BookStack, but it should provide a significant benefit to instances that house sensitive content.

Markdown Export

In addition to the PDF, plaintext and HTML export options, you can now export pages, chapters and books as markdown:

For pages that have not been written in the markdown editor, we’ll attempt to convert the underlying HTML content to markdown. This new markdown export option has also been added to the API. Note: This format does not contain the image data like the HTML option since readability and cleanliness have taken priority.

Role-Based Export Permissions

A new “Export content” role permission has been added to BookStack. This will be given to all roles by default upon upgrade. This new permission allows admins to control who can see and use the “Export” option that’s available via the API or on any page, chapter or book.

“Skip to content” Link

A new accessibility feature was added in v21.05.3, providing a “Skip to main content” link on the first element of focus on the page. This link is not visible by default but will appear when focused upon, typically by hitting tab after landing on a page.

Upload Images in Page Content via API

As of v21.05.1 it’s now possible to upload images via a page’s HTML content. To utilise this, the image just needs to be provided as a base64 encoded data URI within the src of an img tag like so:

1
2
3

{
	"html": "<p><img src='data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAACklEQVR4nGMAAQAABQAB'></p>"
}

Upon POST/PUT of this data, BookStack will extract these images out to their own files, as if they had been uploaded via the UI. This is not yet available for markdown content.

Non-Download Attachment Links

Within BookStack v21.05.2 we added the ability to open/reference attachments without forcing the file to be downloaded. This can be useful for files that your browser may support like images and PDFs, where they could then open in their own tab instead of being downloaded.

This feature is fairly hidden. You can either Ctrl/Cmd+Click the attachment link or add ?open=true to the end of any current attachment link. I’d like to build this option into the interface at some point to make it easier to find & use where desired.

Translations

This release brings a new language option of Lithuanian! Big thanks to @ffranchina and their translators for providing this new language.

Upon that, the below wonderful people have provided translation updates to the shown languages since the initial v21.05 release:

• Behzad HosseinPoor (behzad.hp) - Persian
• Jakub Bouček (jakubboucek) - Czech
• syn7ax69 - Bulgarian; Turkish
• Ole Aldric (Swoy) - Norwegian Bokmal
• whenwesober - Indonesian
• m0uch0 - Spanish
• Alexander Predl (Harveyhase68) - German
• scureza - Italian
• Gustav Kånåhols (Kurbitz) - Swedish
• 10 935 336 - Chinese Simplified
• Michał Stelmach (stelmach-web) - Polish
• Francesco Franchina (ffranchina) - Italian
• arniom - French
• 林祖年 (contagion) - Chinese Traditional
• nutsflag - French
• Leonardo Mario Martinez (leonardo.m.martinez) - Spanish, Argentina
• Vuong Trung Hieu (fpooon) - Vietnamese
• Irfan Hukama Arsyad (IrfanArsyad) - Indonesian
• semirte - Bosnian
• Luís Tiago Favas (starkyller) - Portuguese
• Statium - Russian
• Gerwin de Keijzer (gdekeijzer) - German; Dutch
• aarchijs - Latvian
• Lis Maestrelo (lismtrl) - Portuguese, Brazilian
• Nathanaël (nathanaelhoun) - French
• A Ibnu Hibban (abd.ibnuhibban) - Indonesian
• Martins Pilsetnieks (pilsetnieks) - Latvian
• Frost-ZX - Chinese Simplified
• Kuzma Simonov (ovmach) - Russian
• Vojtěch Krystek (acantophis) - Czech
• Blaade - French
• Siamak Guodarzi (siamakgoudarzi88) - Persian

Full List of Changes

Released in v21.08

• Added multi-factor authentication system. (#2827, #1118)
• Added the ability to export content as Markdown. Thanks to @nikhiljha. (#2115, #1717)
• Added role permissions for exporting content. (#2899, #1251)
• Added an advisory notice on the shelf permissions page regarding the lack of cascade. (#2876)
• Added Lithuanian language translations. Thanks to @ffranchina. (#2868)
• Added item parent link in recycle bin restore to make parent item restore easier. Thanks to @arjvand. (#2682, #2594)
• Added some core opengraph tags to content. Thanks to @james-geiger. (#2393, #2348)
• Updated blade views to be more consistent and follow a documented convention. (#2805)
• Fixed markdown blockquotes not rendering correctly in preview. (#2858, #2837)
• Fixed issue on API where page updates can remove HTML. (#2856)
• Fixed inconsistency in list display and nesting. (#2854)
• Standardised styling of the codebase. (#2820)

Released in v21.05.1 through v21.05.4

• Added base64 image extraction within page content. Thanks to @awarre. (#2700, #2631)
• Added Croatian translations. Thanks to @ffranchina. (#2784, #2785)
• Added VB.NET code block highlighting option. (#2869)
• Added a “Skip to content” link as first page focus item for accessibility use. (#2810)
• Added the ability to serve attachments without forcing downloads. (#2791)
• Updated item permission roles list to be sorted alphabetically. (#2782)
• Updated social account detachment to have CSRF protection. (#2808)
• Updated PHP dependency versions.
• Updated translations with latest changes from Crowdin. (#2790)
• Merged in latest Crowdin translations. (#2787, #2777)
• Improved audit log user select list stability. (#2863)
• Fixed incorrect styling of favourites sidebar when using a non-default homepage option. (#2783)
• Fixed issue where empty HTML comments could cause errors. (#2804)
• Extracted not found text into its own view for easier overridding (58117bc)
• Fixed issue where translations system may attempt to load from the root directory when a theme was not in use. (#2836)
• Fixed issue where user profile pages item “View All” links used ids hence did not link to proper searches. (#2857)

Next Steps

This will likely be my last feature release before I leave my current job and start focusing on BookStack for a while. For the next month or so I’ll just be sneaking in bugfixes and minor improvements as patch releases.

Over the last couple of releases I’ve made good progress in merging in pending pull requests, so I’ll now look to upgrade the framework of BookStack from Laravel 6 to Laravel 8. As part of this I’ll probably do some more cleanup of the codebase.

I’m not sure what I’ll be starting with once I’m working on BookStack full time. The search system is in much need of improvement so that may be the first challenge I tackle.

Header Image Credits: Photo by Dimitry B on Unsplash