search

quarto-dev / quarto-cli

Open-source scientific and technical publishing system built on Pandoc.
https://quarto.org
Other
3.74k stars 305 forks source link

Questions/ need more advice on extending themes ? #2086

Closed cboettig closed 2 years ago

cboettig commented 2 years ago

Really excited about quarto, but coming from blogdown/hugo world I'm struggling to understand how custom SASS themes work. In particular, I've read https://quarto.org/docs/output-formats/html-themes-more.html#bootswatch-sass-theme-files, which says:

We’ve merged Bootswatch themes for Bootstrap 5 into this single file theme format in our repo here: https://github.com/twbs/bootstrap/blob/main/scss/_variables.scss

err... is that the correct link? That appears to be the (unmerged?) official bootstrap-5 sources of the Bootstrap team, not a merged scss file in "our repo"? (trying to better understand this single-file format deal).

More generally, it's not clear how I would go about bringing in external bootstrap-based SASS themes. For instance, I rather like the MIT-licensed bootstrap-5 themes from CreativeTim, like https://github.com/creativetimofficial/material-kit. It seems like to work with quarto, I need to refactor that whole sass stack into a single .scss file, ordered specifically as quarto expects, with the five decorations described in the above link? (e.g. /*-- scss:uses --*/, /*-- scss:functions --*/). Is that correct? Or do I just need to convert my sass theme to a bootswatch theme (al al https://bootswatch.com/help/#customization) ?

Maybe just my ignorance here in these things, but manually refactoring perfectly good SASS code seems like a significant and somewhat cumbersome and needless design -- e.g. compared to converting material-kit or other bootstrap-based SASS templates into hugo themes which was super straight-forward. Maybe the answer is that users who want lower-level customization should just stick with hugo and this is out of scope for quarto? All the same, I had hoped that quarto would lower rather than raise the barrier for user-contributed themes. Sorry if I'm just confused?

dragonstyle commented 2 years ago

Thanks for pointing out that incorrect link - I've fixed that in the documentation. It should've been pointing to:

https://github.com/quarto-dev/quarto-cli/tree/main/src/resources/formats/html/bootstrap/themes

We consolidated the scss theming into a single file primarily as a way to make it simpler for users to define themes (just write a single file with all the relevant variables, rules, and so on). I think this is true for typical themes (for example the bootswatch themes are very simple to read and understand). Order isn't important in these single theme files (the decorations can be in any order and you can omit decorations that don't provide anything).

I'm not familiar enough with MaterialKit to give you complete guidance on the best way to integrate it, though if at the end of the stack there is is an SCSS file defining variables, a file defining rules, and so on, it seems like it would be straightforward to import those in a theme file with the correct decorations.

In the case of authoring your own theme for Quarto, I would just start with a theme in the link above and continue modifying and adding usage of bootstrap variables, css rules, and so on to create the theme that works for you. You can layer your customization on top of an existing theme to customize it, or can provide a complete replacement that will customize the bootstrap default appearance.

cboettig commented 2 years ago

This is great, thanks so much for the help and love what you've done here! I'll give this a go following those examples.