From 7ab2c081fd6a61a7a6583e2984badaedf0fceee0 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 15 Mar 2024 15:49:58 -0400 Subject: [PATCH] Support for adding and modifying theme colors (#1893) --- assets/scss/_variables_project.scss | 7 +- assets/scss/_variables_project_after_bs.scss | 4 ++ assets/scss/main.scss | 4 +- .../en/docs/adding-content/lookandfeel.md | 67 +++++++++++++------ 4 files changed, 54 insertions(+), 28 deletions(-) create mode 100644 assets/scss/_variables_project_after_bs.scss diff --git a/assets/scss/_variables_project.scss b/assets/scss/_variables_project.scss index 387082dca2..89e5f1ac12 100644 --- a/assets/scss/_variables_project.scss +++ b/assets/scss/_variables_project.scss @@ -1,7 +1,4 @@ /* - -Nothing defined here. The Hugo project that uses this theme can override theme variables by adding a file to: - -assets/scss/_variables_project.scss - +Projects can override this file. For details, see: +https://www.docsy.dev/docs/adding-content/lookandfeel/#project-style-files */ diff --git a/assets/scss/_variables_project_after_bs.scss b/assets/scss/_variables_project_after_bs.scss new file mode 100644 index 0000000000..89e5f1ac12 --- /dev/null +++ b/assets/scss/_variables_project_after_bs.scss @@ -0,0 +1,4 @@ +/* +Projects can override this file. For details, see: +https://www.docsy.dev/docs/adding-content/lookandfeel/#project-style-files +*/ diff --git a/assets/scss/main.scss b/assets/scss/main.scss index 2152c7383e..710c943991 100644 --- a/assets/scss/main.scss +++ b/assets/scss/main.scss @@ -1,6 +1,6 @@ @import "../vendor/bootstrap/scss/functions"; -@import "_variables_forward"; +@import "variables_forward"; @import "variables_project"; @import "variables"; @import "support/mixins"; @@ -12,6 +12,8 @@ @import "../vendor/Font-Awesome/scss/solid.scss"; @import "../vendor/Font-Awesome/scss/brands.scss"; +@import "variables_project_after_bs"; + @import "support/utilities"; @import "colors"; @import "table"; diff --git a/userguide/content/en/docs/adding-content/lookandfeel.md b/userguide/content/en/docs/adding-content/lookandfeel.md index de1c91240d..ce88722306 100644 --- a/userguide/content/en/docs/adding-content/lookandfeel.md +++ b/userguide/content/en/docs/adding-content/lookandfeel.md @@ -22,26 +22,30 @@ Prism for highlighting. ## Project style files -To customize your project's look and feel, create your own version of either or -both of the following Docsy placeholder files (note the **`_project.scss`** -suffixes): - -- [`assets/scss/`**`_variables_project.scss`**][_variables_project] is where you - add project-specific definitions of theme variables such as [site - colors](#site-colors), as well as any additional Bootstrap variable values you - want to set. You can find a list of Docsy's theme variables and their default - values in [`assets/scss/`**`_variables.scss`**][_variables]. For information - about other Bootstrap 5 variables, see [Variable defaults] and Bootstrap's - [`_variables.scss`] file. -- [`assets/scss/`**`_styles_project.scss`**][_styles_project] is where you can - add your own custom SCSS styles, including overriding any of the styles in - Docsy's theme SCSS files. - -[_styles_project]: https://github.com/google/docsy/blob/main/assets/scss/_styles_project.scss -[_variables_project]: https://github.com/google/docsy/blob/main/assets/scss/_variables_project.scss -[_variables]: https://github.com/google/docsy/blob/main/assets/scss/_variables.scss -[`_variables.scss`]: https://github.com/twbs/bootstrap/blob/v5.2.3/scss/_variables.scss -[variable defaults]: https://getbootstrap.com/docs/5.3/customize/sass/#variable-defaults +To customize your project's look and feel, create your own version of the +following Docsy placeholder files (note the **`_project*.scss`** suffixes) and +place them inside your project's `assets/scss/` folder: + +- **[`_variables_project.scss`]** and
+ **[`_variables_project_after_bs.scss`]** : + + Use these files to add project-specific definitions of theme variables as well + as any additional Bootstrap variables you want to set or override. For + details, including an explanation of which file to use, see [Site + colors](#site-colors). + + For a list of Docsy's theme variables and their default values, see + [`_variables.scss`]. For information about other Bootstrap 5 variables, see + [Variable defaults] and [Bootstrap's `_variables.scss`][bs_var] file. + +- **[`_styles_project.scss`]** is where you can add your own custom SCSS styles, + including overriding any of the styles in Docsy's theme SCSS files. + +[`_styles_project.scss`]: https://github.com/google/docsy/blob/main/assets/scss/_styles_project.scss +[`_variables.scss`]: https://github.com/google/docsy/blob/main/assets/scss/_variables.scss +[`_variables_project.scss`]: https://github.com/google/docsy/blob/main/assets/scss/_variables_project.scss +[`_variables_project_after_bs.scss`]: https://github.com/google/docsy/blob/main/assets/scss/_variables_project_after_bs.scss +[bs_var]: https://github.com/twbs/bootstrap/blob/v5.3.3/scss/_variables.scss {{% alert title="Tip" %}} PostCSS (autoprefixing of CSS browser-prefixes) is not enabled when running in server mode (it is a little slow), so Chrome is the recommended choice for development. @@ -50,8 +54,8 @@ PostCSS (autoprefixing of CSS browser-prefixes) is not enabled when running in s ## Site colors To customize your site's colors, add SCSS variable overrides to -`assets/scss/_variables_project.scss`. For example, you can set the primary and -secondary site colors as follows: +**`assets/scss/_variables_project.scss`**. For example, you can set the primary +and secondary site colors as follows: ```scss $primary: #390040; @@ -62,6 +66,25 @@ The theme has features such as gradient backgrounds (`$enable-gradients`) and shadows (`$enable-shadows`) enabled by default. These can also be toggled in your project variables file by setting the variables to `false`. +To add colors to or modify Bootstrap's [color maps], use +**`assets/scss/_variables_project_after_bs.scss`**. For example: + +```scss +$custom-colors: ( + "my-favorite-color": purple, + "my-other-color": pink +); + +$theme-colors: map-merge($theme-colors, $custom-colors); +``` + +Learn how to modify maps, see [Maps and loops] and [Adding theme colors]. + +[Adding theme colors]: https://getbootstrap.com/docs/5.3/customize/color-modes/#adding-theme-colors +[color maps]: https://getbootstrap.com/docs/5.3/customize/color/#color-sass-maps +[Maps and loops]: https://getbootstrap.com/docs/5.3/customize/sass/#maps-and-loops +[variable defaults]: https://getbootstrap.com/docs/5.3/customize/sass/#variable-defaults + ## Fonts The theme uses [Open Sans](https://fonts.google.com/specimen/Open+Sans) as its primary font. To disable Google Fonts and use a system font, set this SCSS variable in `assets/scss/_variables_project.scss`: