Oh I see you've mostly copied and pasted the plugin config options from the README file.

https://github.com/jekyll/jekyll-sass-converter#configuration-options

I would recommend against duplicating that here. Rather just mention the plugin and link to it like

Jekyll comes bundled with the Sass converted plugin...

Read the options for the plugin in its docs - [jekyll-sass-converter](https://github.com/jekyll/jekyll-sass-converter#readme).

Then this PR can become a lot shorter. And we don't have to worry about it going out of sync which that is valid in the plugin or covered in the plugin docs

Thanks for your review @MichaelCurrin! Since the jekyll-sass-converter plugin is bundled with Jekyll, and since we do have documentation on the website for other plugins (kramdown and webrick for example), I thought there should be some reference to the SASS config options in the Configuration section of the Jekyll docs.

I agree that I can shorten the docs by removing information about the additional configuration options (style, sourcemap and line_comments) and simply link to the plugin's README. However, I would prefer to mention sass_dir and load_paths, especially since these values depend on the Jekyll site's source directory (and has caused confusion). I would also prefer to keep the Default Configuration section as an example of how to specify options in _config.yml.

What do you think? I'm a new contributor and I may not have the best context for what would be most sustainable for the docs website, so please feel free to push back :)

Thanks for the reply. You can keep your page in, but keep it shorter than you have it now. I also have ideas of other parts of the Jekyll docs to add to and even to the plugin's docs.

I think you should leave out your detailed descriptions for load_paths and sass_dir, as those are covered in the plugin's docs already like style.

Your PR here can be shorter and just mention something like:

• there is a Sass plugin, with a link
• there are Sass default options, which are covered in the plugin's docs.
• a warning that paths set in the sass field must be relative to the source directory, not the project root.

(This avoids having to mention load_paths and sass_dir by name explicitly, as that would be brittle, like if those fields are renamed or more path fields are added or removed.

I think it is unnecessary to add the default config in your PR as, again, things can go out of sync.

Case in point, your style value says compressed here. But that conflicts with the actual default covered in the plugin's docs here

Defaults to compact

Also of relevance is sass section in Default Configuration page.

https://jekyllrb.com/docs/configuration/default/

Again, I wouldn't go an add default values for all sass fields, for reasons above. Also because the defaults might be set by the plugin rather than Jekyll and therefore would not belong in Jekyll's default config.

Note there is already a warning saying that paths should be relative to the working directory and not the site source. This could be modified by you to say that the Sass paths must be set relative to the source directory. (Without mentioning _sass_dir or load_paths explicitly.)

> Make directory path values in configuration keys like `plugins_dir` relative to the current working directory, not the site source.
+> With the exception of `sass`, where values must be relative to the source directory.

Can I suggest you make a PR in the plugin's docs?

Which explains that load_paths and sass_dir must be relative to source directory - also can you please confirm that is indeed case with a screenshot of terminal output.

Another idea for adding to the plugin docs - explicit list of fields and defaults. See sample diff below. BTW I've moved style first to match the plugin docs order.

...

## Configuration Options

Configuration options are specified in the _config.yml file in the following way:
  
    sass:
      <option_name1>: <option_value1>
      <option_name2>: <option_value2>

+Default values:
+  
+```yaml
+sass:
+  style: compact
+  sass_dir: _sass
+  load_paths: []
+  sourcemap: always
+  line_comments: false
+```

Available options are:
 
style
 - Sets the style of the CSS-output. Can be nested, compact, compressed, or expanded. See the SASS_REFERENCE for details.
 ...

@MichaelCurrin thanks for your suggestions, and sorry it took me a while to get back to this.

I've updated the docs based on your suggestions. Further feedback is welcome, especially wordsmithing support xD

also can you please confirm that is indeed case with a screenshot of terminal output.

I don't think the terminal output says much, but I've also included an example jekyll site and its file structure to demonstrate that SASS load paths are relative to the site source and not the config.

Can I suggest you make a PR in the plugin's docs?

👍 Will do later this week!

@jekyll: merge +docs