Migrate from SCSS to blade templates #1325

New Issue

OVERLORD · 2026-02-05T00:37:03+03:00

OVERLORD commented

2026-02-05 00:37:03 +03:00

Originally created by @ssddanbrown on GitHub (Aug 29, 2019).

Just dumping this down so I don't forget it.

Proposal

Migrate the existing SCSS style files to blade template files containing normal CSS content.

Reasoning

We currently use, and I have loved, SCSS mainly due to the following features:

Use of variables.
Ability to split source into multiple files.
Ability to nest selectors.

Feature 1 can now be done via CSS variables now we have dropped IE. I have already started uses CSS variables for core theme colors.
Feature 2 can be done by any common templating system.
Feature 3, while useful, often encourages bad practice and is the most common incompatibility with normal CSS.

Migrating to standard CSS, split out via blade template files, will make the styles more accessible by being standards css rather than scss, while allowing easier customization via the theme system. A custom user theme would be able to selectively override the default BookStack css on a per file basis. This feature would also reduce development build dependencies, making it more accessible to start developing on BookStack and tweaking styles.

Considerations

Existing SCSS files would need to be cleaned up a bit, Certain bits are currently a bit of a mess. More granular would be better.
We'd ideally set sensible cache headers since, unless developing a theme, the styles should not be expected to change often.
Ideally the files would end with .blade.css so editor syntax highlighting remains working as normal. Not looked but, from experience of Laravel, they've probably made this easy to achieve.
Will need to consider PDF generation. Need to check if renderers support CSS variables, Might need to provided targeted backup styles for those.
Would be good if we can get sourcemaps to work to make debugging easier. Could be tricky.

Originally created by @ssddanbrown on GitHub (Aug 29, 2019). Just dumping this down so I don't forget it. ### Proposal Migrate the existing SCSS style files to blade template files containing normal CSS content. ### Reasoning We currently use, and I have loved, SCSS mainly due to the following features: 1. Use of variables. 2. Ability to split source into multiple files. 3. Ability to nest selectors. Feature 1 can now be done via CSS variables now we have dropped IE. I have already started uses CSS variables for core theme colors. Feature 2 can be done by any common templating system. Feature 3, while useful, often encourages bad practice and is the most common incompatibility with normal CSS. Migrating to standard CSS, split out via blade template files, will make the styles more accessible by being standards css rather than scss, while allowing easier customization via the [theme system](https://github.com/BookStackApp/BookStack/issues/652). A custom user theme would be able to selectively override the default BookStack css on a per file basis. This feature would also reduce development build dependencies, making it more accessible to start developing on BookStack and tweaking styles. ### Considerations * Existing SCSS files would need to be cleaned up a bit, Certain bits are currently a bit of a mess. More granular would be better. * We'd ideally set sensible cache headers since, unless developing a theme, the styles should not be expected to change often. * Ideally the files would end with `.blade.css` so editor syntax highlighting remains working as normal. Not looked but, from experience of Laravel, they've probably made this easy to achieve. * Will need to consider PDF generation. Need to check if renderers support CSS variables, Might need to provided targeted backup styles for those. * Would be good if we can get sourcemaps to work to make debugging easier. Could be tricky.

OVERLORD added the 🔧 Maintenance ☕ Open to discussion 🖌️ View Customization labels 2026-02-05 00:37:03 +03:00

OVERLORD commented

2026-02-05 00:37:07 +03:00

@slykar commented on GitHub (Oct 21, 2019):

I've been reading on some of the issues created with theme customization in mind. It looks like you are trying to come up with some out-of-the-box-thinking solution, because single page applications are basically unable to do themes and styles like "old-school" server side rendered applications could do.

In regards to Sass, I can only agree with statement about variables, but ability to split styles into multiple files was also possible with CSS. You could always use file concatenation to get a result in a single file. Nesting selectors? It's just a syntax sugar that I don't use too much to avoid insanely nested definitions.

I understand why it might sound as a good idea to replace Sass with blade templates if you only see the benefits listed, but I think what Sass is popular for are the mixins, extends, functions.

That being said, maybe there should be a way to implement template customization in Vue.js.
AngularJS (1.x) had used templateUrl, which allowed you to override any template you wanted on runtime.

Unfortunately, frameworks today do pre-compilation of HTML to Virtual DOM.

@slykar commented on GitHub (Oct 21, 2019): I've been reading on some of the issues created with theme customization in mind. It looks like you are trying to come up with some out-of-the-box-thinking solution, because single page applications are basically unable to do themes and styles like "old-school" server side rendered applications could do. In regards to Sass, I can only agree with statement about variables, but ability to split styles into multiple files was also possible with CSS. You could always use file concatenation to get a result in a single file. Nesting selectors? It's just a syntax sugar that I don't use too much to avoid insanely nested definitions. I understand why it might sound as a good idea to replace Sass with blade templates if you only see the benefits listed, but I think what Sass is popular for are the mixins, extends, functions. That being said, maybe there should be a way to implement template customization in Vue.js. AngularJS (1.x) had used `templateUrl`, which allowed you to override any template you wanted on runtime. Unfortunately, frameworks today do pre-compilation of HTML to Virtual DOM.

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/BookStack#1325