From d423c96d7aeb44178099b64da4da795ec22a7b13 Mon Sep 17 00:00:00 2001
From: Matt Wang <matt@matthewwang.me>
Date: Wed, 18 Jan 2023 11:13:30 -0800
Subject: [PATCH] Add new `_sass/custom/setup.scss` for variable definition
(#1135)
This is an alternative PR that resolves #1011. Unlike #1013, this PR defines a *new* SASS file, `_sass/custom/setup.scss`, specifically designed for new custom variables (and other SASS-only constructs). It's imported after our `support` SASS files are (functions, variables), but otherwise is imported before all other files (ex, when CSS is emitted).
So, custom callout colors can now be defined in this file. I also move the custom callout colors present in `custom.scss` to the right location.
I've added some docs that briefly explain how to use the feature. Feedback is welcome!
---
As an aside, I chose not to add a `_includes/css` file that imports this, and then import that file. I think that's only necessary if we're trying to render liquid somehow in the SASS file; since we're not trying to do that for `setup.scss`, I've opted to not include it. If we think this is relevant, I can re-add it.
Co-authored-by: Peter Mosses <18308236+pdmosses@users.noreply.github.com>
---
_includes/css/just-the-docs.scss.liquid | 1 +
_sass/custom/custom.scss | 5 +----
_sass/custom/setup.scss | 1 +
docs/configuration.md | 2 +-
docs/customization.md | 22 +++++++++++++++++++++-
5 files changed, 25 insertions(+), 6 deletions(-)
create mode 100644 _sass/custom/setup.scss
diff --git a/_includes/css/just-the-docs.scss.liquid b/_includes/css/just-the-docs.scss.liquid
index da0f4084..3e24c02a 100644
--- a/_includes/css/just-the-docs.scss.liquid
+++ b/_includes/css/just-the-docs.scss.liquid
@@ -2,6 +2,7 @@
$logo: "{{ site.logo | relative_url }}";
{% endif %}
@import "./support/support";
+@import "./custom/setup";
@import "./color_schemes/light";
@import "./color_schemes/{{ include.color_scheme }}";
@import "./modules";
diff --git a/_sass/custom/custom.scss b/_sass/custom/custom.scss
index d5c801e6..ac8445a7 100644
--- a/_sass/custom/custom.scss
+++ b/_sass/custom/custom.scss
@@ -1,4 +1 @@
-$pink-000: #f77ef1;
-$pink-100: #f967f1;
-$pink-200: #e94ee1;
-$pink-300: #dd2cd4;
+// custom SCSS (or CSS) goes here
diff --git a/_sass/custom/setup.scss b/_sass/custom/setup.scss
new file mode 100644
index 00000000..c3b0a942
--- /dev/null
+++ b/_sass/custom/setup.scss
@@ -0,0 +1 @@
+// custom setup code goes here
diff --git a/docs/configuration.md b/docs/configuration.md
index b03806f0..239cde99 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -185,7 +185,7 @@ A paragraph...
[^dark]:
If you use the `dark` color scheme, this callout uses `$red-300` for the background, and `$red-000` for the title.
-The colors `grey-lt`, `grey-dk`, `purple`, `blue`, `green`, `yellow`, and `red` are predefined; to use a custom color, you need to define its `000` and `300` levels in your SCSS files. For example, to use `pink`, add the following to your `_sass/custom/custom.scss` file:
+The colors `grey-lt`, `grey-dk`, `purple`, `blue`, `green`, `yellow`, and `red` are predefined; to use a custom color, you need to define its `000` and `300` levels in your SCSS files. For example, to use `pink`, add the following to your `_sass/custom/setup.scss` file:
```scss
$pink-000: #f77ef1;
diff --git a/docs/customization.md b/docs/customization.md
index 57fc9976..d1a37ed6 100644
--- a/docs/customization.md
+++ b/docs/customization.md
@@ -111,9 +111,29 @@ This allows you to switch the scheme via the following javascript.
jtd.setTheme("foo")
```
+## Override and define new variables
+{: .d-inline-block }
+
+New (v0.4.0)
+{: .label .label-green }
+
+To define new SCSS variables, functions, or override existing theme variables, place SCSS code in `_sass/custom/setup.scss`. This should *not* be used for defining custom styles (see the next section).
+
+This is most commonly-used to define [custom callout colors]({% link docs/configuration.md %}#callouts). For example,
+
+```scss
+// _sass/custom/setup.scss
+$pink-000: #f77ef1;
+$pink-100: #f967f1;
+$pink-200: #e94ee1;
+$pink-300: #dd2cd4;
+```
+
+In particular: this file is imported *after* the theme's variables and functions are defined, but *before* any CSS classes are emitted.
+
## Override and completely custom styles
-For styles that aren't defined as variables, you may want to modify specific CSS classes.
+For styles that aren't defined as SCSS variables, you may want to modify specific CSS classes.
Additionally, you may want to add completely custom CSS specific to your content.
To do this, put your styles in the file `_sass/custom/custom.scss`.
This will allow for all overrides to be kept in a single file, and for any upstream changes to still be applied.
--
GitLab