1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
|
# Jekyll Sass Converter
Let Jekyll build your Sass and SCSS!
[](https://github.com/jekyll/jekyll-sass-converter/actions/workflows/ci.yml)
## Installation
**Jekyll Sass Converter requires Jekyll 2.0.0 or greater and is bundled
with Jekyll so you don't need to install it if you're already using Jekyll.**
Add this line to your application's Gemfile:
gem 'jekyll-sass-converter'
And then execute:
$ bundle
Or install it yourself as:
$ gem install jekyll-sass-converter
## Usage
Jekyll Sass Converter comes bundled with Jekyll 2.0.0 and greater. For more
information about usage, visit the [Jekyll Assets Documentation
page](https://jekyllrb.com/docs/assets/).
### Sass Implementations
#### SassC
By default, Jekyll Sass Converter uses [sassc](https://rubygems.org/gems/sassc)
for Sass implmentation. `sassc` is based on LibSass, and
[LibSass is deprecated](https://sass-lang.com/blog/libsass-is-deprecated).
#### Sass Embedded
[sass-embedded](https://rubygems.org/gems/sass-embedded) is a host for the
[Sass embedded protocol](https://github.com/sass/embedded-protocol).
The host runs [Dart Sass compiler](https://github.com/sass/dart-sass-embedded) as a subprocess
and communicates with the dart-sass compiler by sending / receiving
[protobuf](https://github.com/protocolbuffers/protobuf) messages via the standard
input-output channel.
To use the `sass-embedded` implementation, you need to first install the `sass-embedded` gem
either via your `Gemfile` and Bundler, or directly.
Add this line to your application's Gemfile:
gem 'sass-embedded', '~> 1.0'
And then execute:
$ bundle
Or install it yourself as:
$ gem install sass-embedded
Then, you have to specify `sass-embedded` as the desired implementation in your `_config.yml`:
```yaml
sass:
implementation: sass-embedded
```
### Source Maps
Starting with `v2.0`, the Converter will by default generate a _source map_ file along with
the `.css` output file. The _source map_ is useful when we use the web developers tools of
[Chrome](https://developers.google.com/web/tools/chrome-devtools/) or
[Firefox](https://developer.mozilla.org/en-US/docs/Tools) to debug our `.sass` or `.scss`
stylesheets.
The _source map_ is a file that maps from the output `.css` file to the original source
`.sass` or `.scss` style sheets. Thus enabling the browser to reconstruct the original source
and present the reconstructed original in the debugger.
### Configuration Options
Configuration options are specified in the `_config.yml` file in the following way:
```yml
sass:
<option_name1>: <option_value1>
<option_name2>: <option_value2>
```
Available options are:
* **`implementation`**
Sets the Sass implementation to use.
Can be `sassc` or `sass-embedded`.
Defaults to `sassc`.
* **`style`**
Sets the style of the CSS-output.
Can be `nested`, `compact`, `compressed`, or `expanded`.
See the [SASS_REFERENCE](https://sass-lang.com/documentation/cli/dart-sass#style)
for details.
Defaults to `compact` for `sassc`.
Defaults to `expanded` for `sass-embedded`.
* **`sass_dir`**
A filesystem-path which should be searched for Sass partials.
Defaults to `_sass`
* **`load_paths`**
An array of additional filesystem-paths which should be searched for Sass partials.
Defaults to `[]`
* **`line_comments`**
When set to _true_, the line number and filename of the source is included in the compiled
CSS-file. Useful for debugging when the _source map_ is not available, but might
considerably increase the size of the generated CSS files.
Defaults to `false`.
* **`sourcemap`**
Controls when source maps shall be generated.
- `never` — causes no source maps to be generated at all.
- `always` — source maps will always be generated.
- `development` — source maps will only be generated if the site is in development
[environment](https://jekyllrb.com/docs/configuration/environments/).
That is, when the environment variable `JEKYLL_ENV` is set to `development`.
Defaults to `always`.
## Contributing
1. Fork it ( https://github.com/jekyll/jekyll-sass-converter/fork )
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create new Pull Request
|
