Known Anomalies in BookStack

Here is a list of known technical defects in this BookStack installation. The main purpose of listing them here is so that people know whether we already know about each issue. If it is a known issue, it saves time for people who come across the issue themselves, and would put effort into investigating and reporting it.

If you would like to help with fixing any of these, or have any suggestions, please get in touch, and/or add notes to this page. Some of the issues are trivial to fix once you have access, but we need a proper process in place to make sure that the fixes are documented and are not overwritten on upgrades etc. See the note about forking code on the Forum post mentioned below under Accessibility. Some of the issues are not seen to be an immediate problem, and will only be fixed when enough people see the need for a fix.

These items started out as copies of the text on cards on our Trello board, with minor modifications, but someone may have embellished them here since!

1. Removing sign-up and login fields

(Job for a developer, not hard) We need to remove the input fields from the sign-up and login pages, leaving only the buttons which let you do it via the Hub.

That needs some editing of the HTML template for those pages. There is no class or ID on the appropriate HTML element such that it could be hidden in the style sheet. The register form template is at: /var/www/html/resources/views/auth/register.blade.php The login form must be near it somewhere. Probably: /var/www/html/resources/views/auth/forms/login/standard.blade.php (I say "probably" because I'm just looking at my logs at the moment, not bothering to run up the virtual machine again)

2. Accessibility fixes

There are some changes needed to make the web site more accessible, in the sense of the Web Accessibility Initiative (WAI). See the UK Forum post "Looking for Dev. for Rebel Toolkit Wiki Project" in the Tech Reception category on the Forum (I don't want to put public links here to internal sites). PS. CSS sheet - text size to be made bigger for easier reading.

3. Logged out after 2 hours

By default, BookStack logs you out after 2 hours of inactivity. This is much less than applies to Mattermost, Forums, Cloud and the Hub. It is controlled by the SESSION_LIFETIME setting in the .env file, whose default value is 120 minutes (see .env.example.complete). I suggest that it should be set to a value similar to the other services.

The need to login is mostly for those who will be uploading resources therefore a niche population of the RT users. This comment about being logged out is here to say we know.

And if you are already logged in to the Hub, then logging in again takes two clicks. It looks like we won't fix this!

4. Spacing of list items on pages

Markdown generates different HTML depending on whether you leave a blank line between list items or not. See https://daringfireball.net/projects/markdown/syntax and search for "list items are separated". This is intended to control the spacing of list items. However the default BookStack style sheet specifically removes the top and bottom margins of <p> elements inside <li> elements, so negating the difference. A work-round is to use alternate "+" and "*" for your list items. This gives the required extra spacing, but if you look at the generated HTML it is actually putting in a new list for each item, which reduces accessibility.

5.Horizontal rules invisible in Dark Mode

If we are changing the style sheet at any time... Horizontal rules ("***" on a line by itself in Markdown) don't show up in BookStack Dark Mode because they are dark grey (#222) on the same grey background. This is a mistake in the default BookStack style sheet. Perhaps it shows up OK in some browsers. As an initial suggestion, change the background colour of "html.dark-mode hr" from #222 to #666. Note: I misread the style sheet first time, I don't think the background is #111 after all. PS It could usefully go lighter than #666 so it stands out.