From 5b844a30c1c8ba4bbca6f7cc05d7fb64a44522a9 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Wed, 13 Mar 2024 16:21:04 -0400 Subject: [PATCH] Support for adding and modifying theme colors --- 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 | 65 ++++++++++++------- 4 files changed, 52 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..77f1513ad6 100644 --- a/userguide/content/en/docs/adding-content/lookandfeel.md +++ b/userguide/content/en/docs/adding-content/lookandfeel.md @@ -22,26 +22,29 @@ 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`**[^vp] and
+ **`_variables_project_after_bs.scss`**[^vpabs] : + + Use these files to add project-specific definitions of theme variables such as + [site colors](#site-colors) (explained in the next section), 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 `_variables.scss`[^v]. For + information about other Bootstrap 5 variables, see [Variable defaults] and + Bootstrap's `_variables.scss`[^bv] file. + +- **`_styles_project.scss`**[^sp] is where you can add your own custom SCSS + styles, including overriding any of the styles in Docsy's theme SCSS files. + +[^bv]: https://github.com/twbs/bootstrap/blob/v5.3.3/scss/_variables.scss +[^sp]: https://github.com/google/docsy/blob/main/assets/scss/_styles_project.scss +[^v]: https://github.com/google/docsy/blob/main/assets/scss/_variables.scss +[^vp]: https://github.com/google/docsy/blob/main/assets/scss/_variables_project.scss +[^vpabs]: https://github.com/google/docsy/blob/main/assets/scss/_variables_project_after_bs.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 +53,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 +65,24 @@ 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 can 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 +); + +$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`: