danog/sass-site
1
0
Fork 0
mirror of https://github.com/danog/sass-site.git synced 2024-11-27 04:24:50 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'main' of github.com:sass/sass-site

Browse Source 
* 'main' of github.com:sass/sass-site:
  Properly include code examples in bullet points (#721)
  Freshen Dart Sass page (#720)
  Cut a release for a new Dart Sass version
  Document the deprecation of multiple variable flags (#716)
This commit is contained in:
Jonny Gerig Meyer 2023-04-14 10:38:20 -04:00
commit 653009b9e6
No known key found for this signature in database
7 changed files with 140 additions and 152 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
helpers/sass_helpers.rb
View File

@ -513,6 +513,11 @@ MARKDOWN
text.gsub(/^#{text.scan(/^ *(?=\S)(?!<)/).min}/, "")
end
# Evaluates a block as markdown and concatenates it to the template.
def force_markdown
_concat(_render_markdown(_capture {yield}))
end
# A helper method that renders a chunk of Markdown text.
def _render_markdown(content)
@redcarpet ||= Redcarpet::Markdown.new(

134
old_source/blog/036-sass-and-native-nesting.md → old_source/blog/036-sass-and-native-nesting.md.erb
View File

@ -9,7 +9,7 @@ browser to add support for the new [native CSS nesting feature]. This feature—
inspired by Sass's nesting—adds the ability to nest style rules in plain CSS,
and even uses Sass's convention of `&` to refer to the parent selector.
[native CSS nesting spec]: https://drafts.csswg.org/css-nesting/
[native CSS nesting feature]: https://drafts.csswg.org/css-nesting/
We here at Sass HQ are honored every time our language design inspires
improvements in CSS itself. We're excited to see the usability and clarity
@ -30,76 +30,90 @@ supported native nesting.
More importantly, though, **native CSS nesting is subtly incompatible with Sass
nesting**. This affects three different cases:
1. Native CSS nesting implicitly wraps the parent selector in [`:is()`], while
Sass copies its text into the resolved selector. That means that
<ol><li>
<% force_markdown do %>
[`:is()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/:is
Native CSS nesting implicitly wraps the parent selector in [`:is()`], while
Sass copies its text into the resolved selector. That means that
```scss
.foo, #bar {
.baz { /* ... */ }
}
```
[`:is()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/:is
produces the selector `.foo .baz, #bar .baz` in Sass but `:is(.foo, #bar)
.baz` in native CSS. This changes the specificity: `:is()` always has the
specificity of its _most specific selector_, so `:is(.foo, #bar) .baz` will
match
```html
<div class=foo>
<p class=baz>
</div>
```
with specificity 1 0 1 in native CSS and 0 0 2 in Sass even though neither
element is matched by ID.
```scss
.foo, #bar {
.baz { /* ... */ }
}
```
2. Also because native CSS nesting uses `:is()`, a parent selector with
descendant combinators will behave differently.
produces the selector `.foo .baz, #bar .baz` in Sass but `:is(.foo, #bar)
.baz` in native CSS. This changes the specificity: `:is()` always has the
specificity of its _most specific selector_, so `:is(.foo, #bar) .baz` will
match
```scss
.foo .bar {
.green-theme & { /* ... */ }
}
```
```html
<div class=foo>
<p class=baz>
</div>
```
produces the selector `.green-theme .foo .bar` in Sass, but in native CSS it
produces `.green-theme :is(.foo .bar)`. This means that the native CSS
version will match
```html
<div class=foo>
<div class="green-theme">
<p class=bar>
</div>
</div>
```
with specificity 1 0 1 in native CSS and 0 0 2 in Sass even though neither
element is matched by ID.
but Sass will not, since the element matching `.foo` is outside the element
matching `.green-theme`.
<% end %>
</li><li>
<% force_markdown do %>
3. Sass nesting and native CSS nesting both support syntax that looks like
`&foo`, but it means different things. In Sass, this adds a suffix to the
parent selector, so
Also because native CSS nesting uses `:is()`, a parent selector with
descendant combinators will behave differently.
```scss
.foo {
&-suffix { /* ... */ }
}
```
```scss
.foo .bar {
.green-theme & { /* ... */ }
}
```
produces the selector `.foo-suffix`. But in native CSS, this adds a type
selector to the parent selector, so
```scss
.foo {
&div { /* ... */ }
}
```
produces the selector `.green-theme .foo .bar` in Sass, but in native CSS it
produces `.green-theme :is(.foo .bar)`. This means that the native CSS
version will match
produces the selector `div.foo` (where Sass would produce `.foodiv` instead).
Native CSS nesting has no way to add a suffix to a selector like Sass.
```html
<div class=foo>
<div class="green-theme">
<p class=bar>
</div>
</div>
```
but Sass will not, since the element matching `.foo` is outside the element
matching `.green-theme`.
<% end %>
</li><li>
<% force_markdown do %>
Sass nesting and native CSS nesting both support syntax that looks like
`&foo`, but it means different things. In Sass, this adds a suffix to the
parent selector, so
```scss
.foo {
&-suffix { /* ... */ }
}
```
produces the selector `.foo-suffix`. But in native CSS, this adds a type
selector to the parent selector, so
```scss
.foo {
&div { /* ... */ }
}
```
produces the selector `div.foo` (where Sass would produce `.foodiv` instead).
Native CSS nesting has no way to add a suffix to a selector like Sass.
<% end %>
</li></ol>
### Design Commitments

56
old_source/dart-sass.html.haml
View File

@ -55,8 +55,8 @@ introduction: >
import 'package:sass/sass.dart' as sass;
void main(List<String> arguments) {
var result = sass.compile(arguments[0]);
new File(arguments[1]).writeAsStringSync(result);
var result = sass.compileToResult(arguments[0]);
new File(arguments[1]).writeAsStringSync(result.css);
}
```
@ -84,50 +84,22 @@ introduction: >
`npm install --save-dev sass` and `require()` it as a library:
```js
var sass = require('sass');
const sass = require('sass');
sass.render({
file: scss_filename
}, function(err, result) {
/* ... */
});
const result = sass.compile("style.scss");
console.log(result.css);
// OR
var result = sass.renderSync({
file: scss_filename
});
const result = await sass.compileAsync("style.scss");
console.log(result.css);
```
When installed via npm, Dart Sass supports a JavaScript API that aims to
be compatible with [Node Sass](https://github.com/sass/node-sass#usage).
Full compatibility is a work in progress, but Dart Sass currently supports
the `render()` and `renderSync()` functions. Note however that by default,
**`renderSync()` is more than twice as fast as `render()`**, due to the
overhead of asynchronous callbacks.
When installed via npm, Dart Sass supports a [brand new JavaScript API],
as well as a [legacy API] that's fully compatible with the old Node Sass
API. Note that when using the `sass` asdf package, the synchronous API functions
are more than twice as fast as the asynchronous API, due to the overhead
of asynchronous callbacks.
To avoid this performance hit, `render()` can use the [`fibers`][fibers]
package to call asynchronous importers from the synchronous code path. To
enable this, pass the `Fiber` class to the `fiber` option:
[fibers]: https://www.npmjs.com/package/fibers
```js
var sass = require("sass");
var Fiber = require("fibers");
sass.render({
file: "input.scss",
importer: function(url, prev, done) {
// ...
},
fiber: Fiber
}, function(err, result) {
// ...
});
```
See [Dart Sass's documentation][js api] for more information about its
JavaScript API.
[js api]: https://github.com/sass/dart-sass/blob/master/README.md#javascript-api
[brand new JavaScript API]: https://sass-lang.com/documentation/js-api/
[legacy API]: https://sass-lang.com/documentation/js-api/#legacy-api

7
old_source/documentation/breaking-changes.html.md.erb
View File

@ -23,8 +23,8 @@ time-sensitive, so they may be released with new minor version numbers instead.
These breaking changes are coming soon or have recently been released:
* [Functions are stricter about which units they
allow](breaking-changes/function-units) beginning in Dart Sass 1.32.0.
* [A variable may only have a single `!global` or `!default`
flag](breaking-changes/duplicate-var-flags) beginning in Dart Sass 1.62.0.
* [Selectors with invalid combinators are
invalid](breaking-changes/bogus-combinators) beginning in Dart Sass 1.54.0.
@ -32,6 +32,9 @@ These breaking changes are coming soon or have recently been released:
* [`/` is changing from a division operation to a list
separator](breaking-changes/slash-div) beginning in Dart Sass 1.33.0.
* [Functions are stricter about which units they
allow](breaking-changes/function-units) beginning in Dart Sass 1.32.0.
* [Parsing the special syntax of `@-moz-document` will be
invalid](breaking-changes/moz-document) beginning in Dart Sass 1.7.2.

23
old_source/documentation/breaking-changes/duplicate-var-flags.md.erb Normal file
View File

@ -0,0 +1,23 @@
---
title: "Breaking Change: Duplicate Variable Flags"
introduction: >
Variables will only allow a single `!global` or `!default` flag. Duplicate
flags never had any additional effect, this just ensures that stylesheets are
more consistent.
---
## Phase 1
<% impl_status dart: '2.0.0', libsass: false, ruby: false %>
Starting in Dart Sass 2.0.0, if a single variable declaration has more than one
each `!global` or `!default` flag, this will be a syntax error. This means that
`$var: value !default !default` will be forbidden. `$var: value !global
!default` will still be allowed.
## Transition Period
<% impl_status dart: '1.62.0', libsass: false, ruby: false %>
Until Dart Sass 2.0.0 is released, multiple copies of a flag just produce
deprecation warnings.

5
old_source/documentation/cli/dart-sass.html.md.erb
View File

@ -519,6 +519,11 @@ The following deprecation IDs can be passed to this option:
<td>1.56.0</td>
<td>Passing invalid units to built-in functions.</td>
</tr>
<tr>
<td><a href="../breaking-changes/duplicate-var-flags"><code>duplicate-var-flags</code></a></td>
<td>1.62.0</td>
<td>Using multiple copies of <code>!global</code> or <code>!default</code> in a single variable declaration.</td>
</tr>
</tbody>
</table>

62
source/dart-sass.md
View File

@ -55,8 +55,8 @@ import 'dart:io';
import 'package:sass/sass.dart' as sass;
void main(List<String> arguments) {
var result = sass.compile(arguments[0]);
new File(arguments[1]).writeAsStringSync(result);
var result = sass.compileToResult(arguments[0]);
new File(arguments[1]).writeAsStringSync(result.css);
}
```
@ -85,59 +85,25 @@ JavaScript. You can add it to your project using `npm install --save-dev sass`
and `require()` it as a library:
```js
var sass = require('sass');
const sass = require('sass');
sass.render(
{
file: scss_filename,
},
function (err, result) {
/* ... */
},
);
const result = sass.compile('style.scss');
console.log(result.css);
// OR
var result = sass.renderSync({
file: scss_filename,
});
const result = await sass.compileAsync('style.scss');
console.log(result.css);
```
When installed via npm, Dart Sass supports a JavaScript API that aims to be
compatible with [Node Sass](https://github.com/sass/node-sass#usage). Full
compatibility is a work in progress, but Dart Sass currently supports the
`render()` and `renderSync()` functions. Note however that by default,
**`renderSync()` is more than twice as fast as `render()`**, due to the overhead
of asynchronous callbacks.
When installed via npm, Dart Sass supports a [brand new JavaScript API], as well
as a [legacy API] that's fully compatible with the old Node Sass API. Note that
when using the `sass` asdf package, the synchronous API functions are more than
twice as fast as the asynchronous API, due to the overhead of asynchronous
callbacks.
To avoid this performance hit, `render()` can use the [`fibers`][fibers] package
to call asynchronous importers from the synchronous code path. To enable this,
pass the `Fiber` class to the `fiber` option:
[fibers]: https://www.npmjs.com/package/fibers
```js
var sass = require('sass');
var Fiber = require('fibers');
sass.render(
{
file: 'input.scss',
importer: function (url, prev, done) {
// ...
},
fiber: Fiber,
},
function (err, result) {
// ...
},
);
```
See [Dart Sass's documentation][js api] for more information about its
JavaScript API.
[js api]: https://github.com/sass/dart-sass#legacy-javascript-api
[brand new JavaScript API]: https://sass-lang.com/documentation/js-api/
[legacy API]: https://sass-lang.com/documentation/js-api/#legacy-api
</div>
</div>