Custom View/Theme Support

[ssddanbrown]

This system has now been documented on the docs site here: https://www.bookstackapp.com/docs/admin/hacking-bookstack/#theme-system

---

Enable the ability to override views without editing original files. Will greatly enhance customizability of views.

By setting an APP_THEME environment variable a custom theme can be used.
A theme folder has been added to the root BookStack dir. Any custom themes can be added within their own folder here.

After setting an APP_THEME variable then the system will search in the themes/{APP_THEME} folder for any views before defaulting to standard BookStack views. This gives the option to only override single views if required.

Will need to do a major clean-up of views at some point to ensure everything is modular. May also need to add some helpers to allow easy, safe fetching of entities through the permission system to prevent otherwise 'Themers' with Laravel knowledge may directly query models within views.

This serves as a potential solution to the following:

• Feature Request: simple dompdf styling in settings #642
• Feature request : Custom login page #608
• [FEATURE] Header/Footer for PDF Export #493
• Table of Contents as Home Page #616?
• Referencing Popular & New Books from Home Page #584?
• Hide preview of pages #498?

[ssddanbrown]

Well laravel made that much easier than expected. Functionality added in 6988a6f.

Still need to do a view clear-up at some point so will keep this open for now.
I've put this directly into master for widespread testing during development but this is not something to publicize or recommend to non-technical users for now due to the instability of view changes.

[Abijeet]

I was thinking that maybe we could introduce something like WordPress shortcodes in BookStack for the table of contents related issues (and potentially others) but I think this is a solution that will meet more requirements.

[bridgeyuwa]

Have been waiting for this a long time now

[Wachert]

Another nice Feature for this one would be if it is possible to define a theme per role...

we want another theme for guests than for logged in users.

guests hould not see things like last changes, histories, etc... only logged in users should see this informations.

[MiguelAngelLV]

There are documentation and examples about create custom themes?

[ssddanbrown]

Hi @MiguelAngelLV, There is nothing yet since I'd deem the views, Which the themes would be based on, as unstable.

The feature is in the latest release though and my original description on this issue explains how the system works although I'd advise only small, selective theme overrides should be done for now to minimise breakage upon update.

[lindsayschm]

Is any of this going to end up 0.26? Or is there at least a possibility of getting a dark theme for 0.26, even if customized beyond that isn't necessarily an option?

[ssddanbrown]

@lindsayschm This functionality is already in v0.26, it's just not stable since views may still actively change therefore I'm keeping this issue open. There will not be a dark theme in v0.26. The request for a dark theme is already open under #1234. Not really looking to officially support a dark theme for a while due to the extra effort it would require for every UI change.

Pretty sure I've seen some repos offering dark styles for BookStack although it'll likely be a small while before these are updated for the changes in v0.26.

[ssddanbrown]

As of the last release, docs were updated with details of using this system for customisation:
https://www.bookstackapp.com/docs/admin/hacking-bookstack/#theme-system

[maggie44]

Are all of the settings from the customisation section of the app settings controllable from here if I was to export the folders from a version I have customised? Namely I am trying to set the application name, logo and colour.

[ssddanbrown]

@Maggie0002 Not directly, there are hacks accessible from the theme files but I'm not sure I'd recommend them. You can always override where those elements are used and, for the colors, these are just used as css variables so you could override those via css if needed to be done via the theme system.

[dorianim]

Hi @ssddanbrown

Do you plan to "officially" support this / to make the themenig system stable?

[ssddanbrown]

Hi @dorianim,
The core theme systems are relatively stable at this point, with documentation found here:

• Visual Theme System
• Logical Theme System

The logical system is newer so may incur more changes. But, for the core systems in use here, I would be intending to note potential breakages in any release notes.

What isn't stable is the elements that may be overridden using these systems. So icons, translations and view files (Or any application/framework classes or functions used in the logical system). These can change upon any release. They probably are not things I'd ever look to deem as "stable" due to the impact that'd have on development. That said, I don't really change translation files unless needed and I've recently done a pass on view files to make the structure a little more standard, so we have less volatility there.

[dsoftware43]

Olá @ssddanbrown,
Já existe documentação e exemplos sobre como criar temas personalizados?

[ssddanbrown]

Hi @dsoftware43,
The documentation is listed in my previous comment above.

[ssddanbrown]

Since the visual theme system has become relatively mature I'm going to go ahead and close this off as I'm not sure of what further to do apart from further clean & break down view files as we are developing the platform.