BookStack Code Mirror - website/blob - content/blog/bookstack-release-v21-11.md

1 +++

2 categories = ["Releases"]

3 tags = ["Releases"]

4 title = "BookStack Release v21.11"

5 date = 2021-11-16T10:04:45Z

6 author = "Dan Brown"

7 image = "/images/blog-cover-images/autumn-road-sebastian_unrau.jpg"

8 slug = "bookstack-release-v21-11"

9 draft = false

10 +++

11

12 Today we release BookStack v21.11 which focuses on a couple of areas that have gone

13 untouched for a while; Those areas being tags and the site-wide search system. These changes

14 sit upon more substantial framework upgrade work that has occurred this release cycle.

15

16 * [Update instructions](https://www.bookstackapp.com/docs/admin/updates)

17 * [GitHub release page](https://github.com/BookStackApp/BookStack/releases/tag/v21.11)

18

19

20 **Upgrade Notices**

21

22 - **Security Releases** - There were some security vulnerabilities found during the life of

23 v21.10. See the [v21.10.1](/blog/bookstack-release-v21-10-1/), [v21.10.2](/blog/bookstack-release-v21-10-2/) and

24 [v21.10.3](/blog/bookstack-release-v21-10-3/) posts for more details.

25 - **API Changes** - As of v21.11 any dates in API responses will be formatted as per ISO-8601, with `2019-12-02T20:01:00.283041Z` reflecting an example of this format. You may need to review any of your scripts that utilise dates from API responses.

26 - **Upload Limit** - System file upload limits are now configured using a `FILE_UPLOAD_SIZE_LIMIT` option in your

27 `.env` file. This value is specified as an integer and represents the max upload size in MegaBytes. This defaults to 50MB. This replaces the old `window.uploadLimit` HTML head option that could be set.

28 - **Search Index Changes** - As detailed below, there have been search indexing and scoring changes in v21.11.

29 It's recommended to run `php artisan bookstack:regenerate-search` to ensure a consistent search experience and take

30 advantage of these changes.

31 - **Logout Endpoints** - Logout endpoints have now changed to be CSRF protected POST endpoints instead of GET endpoints. If you were using these for any external purposes you may now need to implement an alternative workflow.

32

33

34 ### New Tags Overview

35

36 A listing of used tags can now be found within BookStack. This view initially shows all used

37 tag names along with counts of usage, broken down by item type (Total, page, chapter, book, shelf):

38

39 ![Tags Overview Page Preview](/images/2021/11/tags-page.png)

40

41 Clicking the tag name, or the counts, will start a search for that particular tag and item type.

42 Shown on the right is the count of unique values used against the tag name. Clicking this will take

43 you to a similar view for that specific tag name, displaying all the values used for that tag.

44

45 This view can be accessed via the actions menu when viewing all books or shelves in the system.

46

47 ### Search System Enhancements

48

49 During this release cycle I decided to pay special attention to the search system.

50 The most obvious change is an improvement in how search results are displayed.

51 Item names, descriptions and tags will reflect the searched terms and show them in bold

52 with some surrounding context:

53

54 ![Search Enhancements Preview](/images/2021/11/search-results.png)

55

56 Upon this aesthetic change, which should help visual parsing of results, the following

57 improvements have been made to the search indexing and scoring system:

58

59 - Terms searched will now have their scores relatively adjusted based upon frequency

60 in the database. This should help prevent common, smaller terms causing so much noise in results.

61 - Page content is now parsed so that a score boost is given to terms within content headings.

62 - The score boost for terms in item titles has been significantly increased.

63 - Standard terms will now match against the names and values of tags.

64 - Search terms that had issues, due to containing certain delimiters (For example IP addresses), will

65 now be auto-converted to become an "exact" search term.

66 - The regenerate-search command will now report some level of progress to the user as it runs.

67

68 Put together, these changes should result in a big overall improvement to the search system and provide

69 much more accurate results in a format that's easier to read.

70

71 ### Search API Endpoints

72

73 As is common, the API has received new functionality. A "Search" endpoint has been added which allows

74 you to run queries against items within BookStack using [the same filters and options](/docs/user/searching/)

75 available when using the main search bar within the interface.

76

77 ![Search API Preview](/images/2021/11/search-api.png)

78

79 The behavior of this endpoint is a bit quirky compared to others so ensure you

80 read the documentation carefully if intending to use this.

81

82 ### Framework Upgrades

83

84 As an early part of this release I worked to upgrade our framework from Laravel 6 to Laravel 8.

85 To help this upgrade I used [Laravel shift](https://laravelshift.com/) to automate much of the busy

86 work. Moving to Laravel 8 puts us on the latest release for the first time in quite a while, and means

87 that we can take advantage of the latest framework features where needed. There won't really be a

88 noticeable impact to users but it should make development more pleasant while setting us up

89 to eventually move to the next Laravel long-term-support release.

90

91 A big thanks to the Laravel team, especially for their support on the LTS releases which has allowed

92 us to retain a steady and feasible upgrade path for users in terms of system requirements.

93

94 ### Translations

95

96 Thanks once again to our transcendent translating team. Since the last feature release the

97 below members have been doing fantastic work on Crowdin to keep text translated and up-to-date:

98

99 - jozefrebjak - *Slovak*

100 - Indrek Haav (IndrekHaav) - *Estonian*

101 - Martins Pilsetnieks (pilsetnieks) - *Latvian*

102 - na3shkw - *Japanese*

103 - Gerwin de Keijzer (gdekeijzer) - *Dutch*

104 - m0uch0 - *Spanish*

105 - nutsflag - *French*

106 - sulfo - *Danish*

107 - Michał Lipok (mLipok) - *Polish*

108 - Raukze - *German*

109 - Nicolas Pawlak (Mikolajek) - *French; German; Polish*

110 - zygimantus - *Lithuanian*

111 - aarchijs - *Latvian*

112

113

114 ### Official Twitter & YouTube Channel

115

116 Over the last month I've spent a bit of time focusing on some of the higher-level project elements.

117 As part of this I've set-up an official Twitter account for BookStack: [@bookstack_app](https://twitter.com/bookstack_app). This means you can follow project updates and progress without having to also scroll

118 past pictures of my cat.

119

120 I've also created a [BookStack YouTube channel](https://www.youtube.com/channel/UCH66RFWfw6CSm2T1EM4ik1g). I mentioned wanting to record some project videos in the "[A Year of BookStack](/blog/1-year-of-bookstack/)" blogpost; 5 years later I've finally started on these.

121 Currently there's just two videos to guide installation options but more should be coming with improved audio quality.

122

123 <iframe width="560" height="315" src="https://www.youtube.com/embed/ShqUjt33uOs" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen loading="lazy"></iframe>

124

125 <iframe width="560" height="315" src="https://www.youtube.com/embed/dbDzPIv8Cf8" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen loading="lazy"></iframe>

126

127 ### Full List of Changes

128

129 **Released in v21.11**

130

131 * Added a new tag view. ([#3042](https://github.com/BookStackApp/BookStack/pull/3042), [#738](https://github.com/BookStackApp/BookStack/issues/738))

132 * Added a wide series of improvements to the search system, including: ([#3043](https://github.com/BookStackApp/BookStack/pull/3043), [#2840](https://github.com/BookStackApp/BookStack/issues/2840))

133 * Added highlighting of search terms in search results. ([#1891](https://github.com/BookStackApp/BookStack/issues/1891), [#997](https://github.com/BookStackApp/BookStack/issues/997))

134 * Added matching of tag names and values through normal search terms. ([#1577](https://github.com/BookStackApp/BookStack/issues/1577))

135 * Added search API endpoints. ([#909](https://github.com/BookStackApp/BookStack/issues/909))

136 * Added new `.env` option to limit file uploads. ([#3033](https://github.com/BookStackApp/BookStack/issues/3033))

137 * Updated the used Laravel framework from version 6 to version 8. Thanks to @laravel-shift for accelerating this. ([#3012](https://github.com/BookStackApp/BookStack/pull/3012), [#3011](https://github.com/BookStackApp/BookStack/pull/3011))

138 * Implemented initial use of static analysis for PHP code. ([#3039](https://github.com/BookStackApp/BookStack/pull/3039))

139 * Updated Slack and Facebook logos to be current. Thanks to [@na3shkw](https://github.com/BookStackApp/BookStack/pull/3032). ([#3032](https://github.com/BookStackApp/BookStack/pull/3032))

140 * Updated user invite/email-confirmation journeys to help prevent potential malicious user manipulation. Thanks again to @haxatron for reporting. ([#3050](https://github.com/BookStackApp/BookStack/issues/3050))

141 * Updated logout endpoints to be POST to prevent potential CSRF concerns. Thanks to @hdvinnie for reporting. ([#3047](https://github.com/BookStackApp/BookStack/issues/3047))

142 * Updated page include system to retain the `pre` tags when including a code block. ([#2406](https://github.com/BookStackApp/BookStack/issues/2406))

143 * Updated translations with latest changes from Crowdin. ([#3040](https://github.com/BookStackApp/BookStack/pull/3040))

144 * Fixed issue where using the back button in the page editor could lead you to the same page. ([#2834](https://github.com/BookStackApp/BookStack/issues/2834))

145 * Fixed issue where setting new search filters could remove existing created_by & updated_by filters. ([#2736](https://github.com/BookStackApp/BookStack/issues/2736))

146 * Fixed issue where markdown draft pages could convert to HTML. ([#3054](https://github.com/BookStackApp/BookStack/issues/3054))

147 * Fixed issue where "Skip to content" link could be visible on print views. ([#3051](https://github.com/BookStackApp/BookStack/issues/3051))

148

149 **Released in v21.10.1 through v21.10.3**

150

151 * Fixed image upload vulnerability. Thanks to @haxatron ([#3010](https://github.com/BookStackApp/BookStack/issues/3010))

152 * Fixed capitalization for Estonian language option. Thanks to [@IndrekHaav](https://github.com/BookStackApp/BookStack/pull/3008). ([#3008](https://github.com/BookStackApp/BookStack/pull/3008))

153 * Updated PHP packages to prevent abandoned warning. ([#3007](https://github.com/BookStackApp/BookStack/issues/3007))

154 * Updated translations with latest changes from Crowdin. ([#3006](https://github.com/BookStackApp/BookStack/pull/3006), [#3023](https://github.com/BookStackApp/BookStack/pull/3023), [#3014](https://github.com/BookStackApp/BookStack/pull/3014))

155 * Made further fixes to address image upload vulnerability. Thanks again to @haxatron ([#3019](https://github.com/BookStackApp/BookStack/issues/3019))

156 * Updated AzureAD login library to work with the new Microsoft Graph API. ([#3028](https://github.com/BookStackApp/BookStack/issues/3028))

157 * Fixed path image file path traversal vulnerability. Thanks @theworstcomrade for reporting. ([#3030](https://github.com/BookStackApp/BookStack/issues/3030))

158 * Prevented HTML attachments being served inline. Thanks @theworstcomrade for reporting. ([#3027](https://github.com/BookStackApp/BookStack/issues/3027))

159

160 ### Next Steps

161

162 Within the latter stage of the v21.11 I went through some of the older issues in the project

163 to address them if still relevant. I'll probably continue that work to produce a few

164 patch releases.

165

166 As mentioned above I'm intending to produce more videos for [the BookStack YouTube channel](https://www.youtube.com/channel/UCH66RFWfw6CSm2T1EM4ik1g).

167 Will work on these in times when I want to do something a bit more creative.

168

169 In terms of larger features, I'll start getting deeper into

170 [assessing a new page editor](https://github.com/BookStackApp/BookStack/issues/2738)

171 which takes us to the next major project roadmap milestone.

172

173

174 ----

175

176 <span style="font-size: 0.8em;opacity:0.9;">Header Image Credits: <span>Photo by <a href="https://unsplash.com/@sebastian_unrau?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Sebastian Unrau</a> on <a href="https://unsplash.com/?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Unsplash</a></span></span>