Confusion about the "external dependencies" in themes

[CookiePLMonster]

Having migrated from jekyll-sass-converter 2.x to 3.x, I started getting many deprecation warnings related to a new Dart Sass. I fixed them in my own SCSS files, but I can't fix all of them coming from external dependencies like Font Awesome. quiet_deps should be able to help me, but I don't know how to correctly restructure the _sass folder to have my partials considered "internal" and Font Awesome "external".

My _config.yml:

sass:
  style: compressed
  sourcemap: development
  quiet_deps: true

My files are structured as follows:

_sass\
   base\ <--- I want those to be treated as "internal"
      file1.scss
      file2.scss
   includes\ <--- Those too
      include1.scss
   external\ <--- Those should be dependencies
      font-awesome.scss
   theme.scss <--- Internal
assets\
   css\
      main.scss

Where main.scss is

---
---

@use "theme";

I tried removing the use of theme.scss and listing all my partials directly in main.scss, that didn't help. The only thing that did help was removing the Font Awesome partial from theme.scss and changing main.scss to:

---
---

// Font Awesome
@use "external/fontawesome-glue" with (
    $fa-font-path: 'fontawesome',
    $fa-inverse: var(--background-color),
    $fa-li-margin: 2em,
    $fa-li-width: 1.5em,
    $fa-stack-width: 2em
);

@use "../../_sass/theme.scss";

But this is probably not how it's supposed to be used.

TL;DR: Is there a way to restructure my _sass directory to consider my partials "internal" and get all SASS warnings, while partials from the external directory as external dependencies that do not get warnings?

[ashmaroli]

Hello @CookiePLMonster, quiet_deps is only a config property to prevent certain deprecation warnings from Dart Sass printing into the terminal. Therefore, your statement quiet_deps should be able to help me.. is out-of-place, incorrect and a misunderstanding.
In fact, the title of this issue ticket itself is misleading because your actual query is regarding segregating partials into internal and external dependencies which I honestly do not understand.

I am pinging @ntkme so that they may be able to shed some light or point you to relevant documentation on Dart Sass.

[CookiePLMonster]

In fact, the title of this issue ticket itself is misleading because your actual query is regarding segregating partials into internal and external dependencies which I honestly do not understand.

That makes sense. Perhaps this comes from a misunderstanding of what "external dependencies" in Dart Sass are, but I was hoping to be able to separate partials coming from my theme that I wrote and have full control over, from "external" partials I pulled into the project like Font Awesome, where it's not feasible for me to correct all deprecation warnings (especially the ones related to @import).

[ashmaroli]

it's not feasible for me to correct all deprecation warnings (especially the ones related to @import)

You may disable deprecation warnings related to @import with following configuration:

# _config.yml

sass:
  quiet_deps: true
  silence_deprecations: 
    - import

Other types of warnings can be added to the list above. Though, you'll have to refer the Dart Sass docs for the exact identifier for the type of deprecated feature.

[CookiePLMonster]

You may disable deprecation warnings related to @import with following configuration:

Indeed, and that's what I tried just before opening this ticket. However, Font Awesome also throws multiple other warnings (e.g. about a deprecated unquote) that I "don't care" about in their CSS, but would like to have pointed out in my styles.

[ntkme]

The definition of “dependency” is stylesheet resolved from load_paths. Stylesheet resolved as relative path does not count.

[CookiePLMonster]

My load_paths is left at default, i.e. empty. Those all load from sass_dir. And FWIW I did try to change the includes in theme.scss to relative (./includes/foo.scss), and that didn't re-enable warnings.

[ntkme]

Stylesheet resolved as relative path does not count, even if the file is located in the load_paths. Note _sass (sass_dir) is a default load path.

[ntkme]

For the structure you have, what you can do is:

// main
@use "../../_sass/theme"; // this is a relative path, does not count as dependency.

Add _sass/external to load_paths, then:

// theme
@use "font-awesome";

[CookiePLMonster]

For the structure you have, what you can do is:

This works, but it's admittedly quite "ugly" and doesn't look quite right - which brings me to my original question, what would be the "right" way to do it, short of putting all my sass code in main.scss? Ideally I would like to keep my own partials in the _sass dir.

[ntkme]

The reason is that for most of the end users who import the root stylesheet for a theme e.g. minima, that whole theme is a dependency which users do not care about those warnings. So treat the whole theme as dependency is actually intended behavior.

I understand that this is a bit inconvenient for you as a theme author, but relative import vs load_path is the only difference for sass compiler to consider if a file is a dependency or not.

What I do in my own project is that I use npm to install all external dependencies, and I add node_modules to load_paths. Then for the theme root stylesheet import, I use a relative path. It’s more or less the same as what I described for your structure.

[ashmaroli]

Thank you for your insights, @ntkme.
If possible will you be able to submit a pull request to update the README to concisely illustrate the core scenario discussed in this issue ticket?

[CookiePLMonster]

The reason is that for most of the end users who import the root stylesheet for a theme e.g. minima, that whole theme is a dependency which users do not care about those warnings. So treat the whole theme as dependency is actually intended behavior.

That clears things up for me, thanks! I haven't considered this particular scenario and that my workflow of maintaining the blog contents together with a theme may be an outlier. With this in mind, I now understand why I need to resort to an "ugly" relative path.

Should I keep this issue open for the sake of a readme update @ashmaroli mentioned? Otherwise I'll try it out again in the evening and close if everything works fine - as I have tried the relative path before opening the ticket but I have not tried adding _sass/externals to the load paths.

[ashmaroli]

You may leave this ticket open, @CookiePLMonster.
I'll close it later.

You could however, update the title to better describe the actual issue 😉

[CookiePLMonster]

You could however, update the title to better describe the actual issue 😉

Sure, is this better?

[CookiePLMonster]

What I do in my own project is that I use npm to install all external dependencies, and I add node_modules to load_paths. Then for the theme root stylesheet import, I use a relative path. It’s more or less the same as what I described for your structure.

To add to that, looks like I may potentially be able to add Font Awesome as a Ruby gem and move it out of _sass/externals:
https://docs.fontawesome.com/web/use-with/ruby-on-rails

[ntkme]

Another thing here is that you have theme.scss in the root of _sass, which means @use "external/font-awesome"; can be interpreted as either a relative path or a load path import, but relative path is always considered first. So, another way to deal with that part is to move _sass/theme.scss to a different place, e.g. _sass/theme/main.scss, this way you don’t need an extra load path and modify the import statement. Still, it is a bit ugly and strange.

Logically _sass is for dependency. If you’re maintaining the theme together with your blog, another option would simply be move all the internal files to assets/css or somewhere else outside of load_paths, that you have a logical separation for internal vs external.

[ntkme]

Font Awesome as a Ruby gem

That’s for Ruby on Rails, which cannot be used for Jekyll at this moment.

[CookiePLMonster]

Logically _sass is for dependency. If you’re maintaining the theme together with your blog, another option would simply be move all the internal files to assets/css, that you have a logical separation for internal vs external.

Will these files not be copied over to _site when building then? Or are .scss files excluded?
I checked, all Sass/CSS files that start with an underscore aren't copied over to _site, so I can even put e.g. assets/css/_icomoon.css there.

That’s for Ruby on Rails, which cannot be used for Jekyll at this moment.

I see, my bad - there are separate -rails packaged but they are quite old and unmaintained.

[ntkme]

Will these files not be copied over to _site?

Jekyll ignores copying filenames started with underscore, and sass consider underscore as a partial, which can be imported without the underscore prefix. E.g. you can have assets/css/_theme.scss and still have @use "theme"; in assets/css/main.scss.

[CookiePLMonster]

I tested, and everything worked as expected! In case anyone in the future has similar doubts to me and needs help, here's what I did to my theme:

1. I moved my own internal theme files to assets/css/theme.
2. I updated the @use rules to specify relative paths where applicable, e.g. for my layouts including _variables.scss.
3. My old theme.scss became main.scss where I included my theme with @use 'theme/[x] and externals with @use 'external/[x]'.
   1. One of my externals depended on my internal _variables.scss, so I slightly updated it to accept variables passed from the theme via @use 'external/syntax' with ( // Variables );.
4. To tie Font Awesome that is incompatible with @use rules, with my own variable overrides I specify in the theme:
   1. I created external/fontawesome-glue.scss that uses @import on the appropriate FA stylesheets.
   2. Instead of importing FA directly, I import the "glue" SCSS file with @use external/fontawesome-glue.scss with ( // Variables );.

Now I am getting all warnings for my own theme (there actually were a few deprecation warnings that snuck under the radar!), while externals like Font Awesome don't get warnings.

Thank you both for your help!