mirror of
https://github.com/BookStackApp/BookStack.git
synced 2026-02-12 19:06:27 +03:00
Custom View/Theme Support #540
Reference in New Issue
Block a user
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Originally created by @ssddanbrown on GitHub (Dec 31, 2017).
Originally assigned to: @ssddanbrown on GitHub.
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_THEMEenvironment variable a custom theme can be used.A
themefolder has been added to the root BookStack dir. Any custom themes can be added within their own folder here.After setting an
APP_THEMEvariable then the system will search in thethemes/{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:
@ssddanbrown commented on GitHub (Dec 31, 2017):
Well laravel made that much easier than expected. Functionality added in
6988a6ff88.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 commented on GitHub (Jan 2, 2018):
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 commented on GitHub (Feb 21, 2018):
Have been waiting for this a long time now
@Wachert commented on GitHub (Mar 28, 2018):
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 commented on GitHub (May 4, 2018):
There are documentation and examples about create custom themes?
@ssddanbrown commented on GitHub (May 12, 2018):
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 commented on GitHub (May 15, 2019):
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 commented on GitHub (May 15, 2019):
@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 commented on GitHub (Mar 6, 2020):
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 commented on GitHub (Dec 13, 2020):
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 commented on GitHub (Dec 13, 2020):
@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 commented on GitHub (Oct 30, 2021):
Hi @ssddanbrown
Do you plan to "officially" support this / to make the themenig system stable?
@ssddanbrown commented on GitHub (Oct 30, 2021):
Hi @dorianim,
The core theme systems are relatively stable at this point, with documentation found here:
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 commented on GitHub (Apr 11, 2022):
Olá @ssddanbrown,
Já existe documentação e exemplos sobre como criar temas personalizados?
@ssddanbrown commented on GitHub (Apr 11, 2022):
Hi @dsoftware43,
The documentation is listed in my previous comment above.
@ssddanbrown commented on GitHub (Sep 20, 2022):
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.