Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add new _sass/custom/setup.scss for variable definition #1135

Merged
merged 4 commits into from Jan 18, 2023
Merged

Add new _sass/custom/setup.scss for variable definition #1135

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
57e41d8
adds setup.scss
mattxwang Jan 17, 2023
673cb95
update content of custom scss files
mattxwang Jan 17, 2023
b7f42d1
Touches up docs, removes custom `$pink` setup code
mattxwang Jan 17, 2023
77378a1
reword custom.scss comment
mattxwang Jan 18, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
1 change: 1 addition & 0 deletions _includes/css/just-the-docs.scss.liquid
View file
Open in desktop
Expand Up @@ -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";
Expand Down
5 changes: 1 addition & 4 deletions _sass/custom/custom.scss
View file
Open in desktop
@@ -1,4 +1 @@
$pink-000: #f77ef1;
$pink-100: #f967f1;
$pink-200: #e94ee1;
$pink-300: #dd2cd4;
// custom CSS rules goes here
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
// custom CSS rules goes here
// custom SCSS rules go here

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll provide an alternate more specific text; I did mean CSS rules (as in the formal spec definition)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But the file extension is scss, so I think Jekyll will compile it anyway?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh, the idea wasn't to say that only CSS is allowed; rather, that everything in that file should emit CSS (after compilation), rather than just being variable declarations.

I think I'll revert this change somewhat since that's not actually a constraint.

6 changes: 6 additions & 0 deletions _sass/custom/setup.scss
View file
Open in desktop
@@ -0,0 +1,6 @@
// custom setup code goes here

$pink-000: #f77ef1;
$pink-100: #f967f1;
$pink-200: #e94ee1;
$pink-300: #dd2cd4;
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should avoid content in such a custom file, because changing the content could break sites that rely on the content but don't override the file.

So I suggest to delete these lines.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hm, ok - in that case, this theme will introduce different behaviour (since we're removing these same lines from custom.scss.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think those lines were added in RC1, by #578. So it's not breaking wrt v0.3.3.

And yes, this illustrates very well the danger of putting content in custom styles…

2 changes: 1 addition & 1 deletion docs/configuration.md
View file
Open in desktop
Expand Up @@ -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;
Expand Down
21 changes: 20 additions & 1 deletion docs/customization.md
View file
Open in desktop
Expand Up @@ -111,9 +111,28 @@ This allows you to switch the scheme via the following javascript.
jtd.setTheme("foo")
```

## Override and define new variables

mattxwang marked this conversation as resolved.
Show resolved Hide resolved
New (v0.4.0)
{: .label .label-green }

To define new SASS variables, functions, or override existing theme variables, place SASS files in `_sass/custom/setup.scss`. This should *not* be used for defining custom styles (see the next section).
mattxwang marked this conversation as resolved.
Show resolved Hide resolved

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 SASS 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.
Expand Down