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

review

Browse Source
This commit is contained in:
Jonny Gerig Meyer 2023-05-25 11:55:08 -04:00
parent be895963fc
commit 61127e5e60
No known key found for this signature in database
12 changed files with 164 additions and 123 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
source/code-snippets/example-advanced-nesting.liquid
View File

@ -1,8 +1,9 @@
{% markdown %}
For example, suppose you want to write a selector that matches the outer
selector *and* an element selector. You could write a mixin like this one that uses the [`selector.unify()` function][] to combine `&` with a user's selector.
selector *and* an element selector. You could write a mixin like this one that
uses the [`selector.unify()` function][] to combine `&` with a user's selector.
[`selector.unify()` function]: ../../modules/selector#unify
[`selector.unify()` function]: /documentation/modules/selector#unify
{% endmarkdown %}
{% codeExample 'advanced-nesting' %}
@ -30,6 +31,7 @@ selector *and* an element selector. You could write a mixin like this one that u
@content
.wrapper .field
@include unify-parent("input")
/* ... */

2
source/code-snippets/example-if-parent-selector.liquid
View File

@ -1,4 +1,4 @@
{% codeExample 'if-parent-selector'%}
{% codeExample 'if-parent-selector' %}
@mixin app-background($color) {
#{if(&, '&.app-background', '.app-background')} {
background-color: $color;

31
source/code-snippets/example-nesting.liquid Normal file
View File

@ -0,0 +1,31 @@
{% codeExample 'nesting' %}
nav {
ul {
margin: 0;
padding: 0;
list-style: none;
}
li { display: inline-block; }
a {
display: block;
padding: 6px 12px;
text-decoration: none;
}
}
===
nav
ul
margin: 0
padding: 0
list-style: none
li
display: inline-block
a
display: block
padding: 6px 12px
text-decoration: none
{% endcodeExample %}

19
source/documentation/style-rules/declarations.liquid
View File

@ -2,8 +2,11 @@
title: Property Declarations
table_of_contents: true
introduction: >
In Sass as in CSS, property declarations define how elements that match a selector are styled. But Sass adds extra features to make them easier to write and to automate. First and foremost, a declaration's value can be any [SassScript expression](/documentation/syntax/structure#expressions), which will be
evaluated and included in the result.
In Sass as in CSS, property declarations define how elements that match a
selector are styled. But Sass adds extra features to make them easier to write
and to automate. First and foremost, a declaration's value can be any
[SassScript expression](/documentation/syntax/structure#expressions), which
will be evaluated and included in the result.
---
{% codeExample 'declaration' %}
@ -133,15 +136,14 @@ $rounded-corners: false
border-radius: if($rounded-corners, 5px, null)
{% endcodeExample %}
{% markdown %}
## Custom Properties
{% endmarkdown %}
{{ '## Custom Properties' | markdown }}
{% # Arguments are (in order): `dart`, `libsass`, `node`, `ruby`, optional feature name, additional details within %}
{% compatibility true, '3.5.0', null, '3.5.0', 'SassScript Syntax' %}
Older versions of LibSass and Ruby Sass parsed custom property declarations just like any other property declaration, allowing the full range of SassScript expressions as values. Even when using these versions, it's
recommended that you use interpolation to inject SassScript values for
forwards-compatibility.
Older versions of LibSass and Ruby Sass parsed custom property declarations just
like any other property declaration, allowing the full range of SassScript
expressions as values. Even when using these versions, it's recommended that you
use interpolation to inject SassScript values for forwards-compatibility.
See [the breaking change page][] for more details.
@ -165,6 +167,7 @@ is the only way to inject dynamic values into a custom property.
[interpolation]: /documentation/interpolation
{% endmarkdown %}
<!-- TODO(nweiz): auto-generate this CSS once we're compiling with Dart Sass -->
{% codeExample 'custom-properties' %}
$primary: #81899b;
$accent: #302e24;

51
source/documentation/style-rules/index.liquid
View File

@ -2,7 +2,10 @@
title: Style Rules
table_of_contents: true
introduction: >
Style rules are the foundation of Sass, just like they are for CSS. And they work the same way: you choose which elements to style with a selector, and [declare properties](/documentation/style-rules/declarations) that affect how those elements look.
Style rules are the foundation of Sass, just like they are for CSS. And they
work the same way: you choose which elements to style with a selector, and
[declare properties](/documentation/style-rules/declarations) that affect how
those elements look.
---
{% codeExample 'style-rules' %}
@ -28,38 +31,7 @@ selectors over and over again, you can write one style rules inside another.
Sass will automatically combine the outer rule's selector with the inner rule's.
{% endmarkdown %}
{% codeExample 'nesting' %}
nav {
ul {
margin: 0;
padding: 0;
list-style: none;
}
li { display: inline-block; }
a {
display: block;
padding: 6px 12px;
text-decoration: none;
}
}
===
nav
ul
margin: 0
padding: 0
list-style: none
li
display: inline-block
a
display: block
padding: 6px 12px
text-decoration: none
{% endcodeExample %}
{% render 'code-snippets/example-nesting' %}
{% headsUp %}
Nested rules are super helpful, but they can also make it hard to visualize how
@ -102,7 +74,7 @@ selector, or even all on its own in between the two.
[combinators]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors#Combinators#Combinators
{% endmarkdown %}
{% codeExample 'selector-combinators'%}
{% codeExample 'selector-combinators' %}
ul > {
li {
list-style-type: none;
@ -162,7 +134,7 @@ parameters your users pass in.
[mixins]: /documentation/at-rules/mixin
{% endmarkdown %}
{% codeExample 'interpolation'%}
{% codeExample 'interpolation' %}
@mixin define-emoji($name, $glyph) {
span.emoji-#{$name} {
font-family: IconFont;
@ -187,11 +159,16 @@ parameters your users pass in.
{% endcodeExample %}
{% funFact %}
Sass only parses selectors *after* interpolation is resolved. This means you can safely use interpolation to generate any part of the selector without worrying that it won't parse.
Sass only parses selectors *after* interpolation is resolved. This means you can
safely use interpolation to generate any part of the selector without worrying
that it won't parse.
{% endfunFact %}
{% markdown %}
You can combine interpolation with the parent selector `&`, the [`@at-root` rule][], and [selector functions][] to wield some serious power when dynamically generating selectors. For more information, see the [parent selector documentation][].
You can combine interpolation with the parent selector `&`, the [`@at-root`
rule][], and [selector functions][] to wield some serious power when dynamically
generating selectors. For more information, see the [parent selector
documentation][].
[`@at-root` rule]: /documentation/at-rules/at-root
[selector functions]: /documentation/modules/selector

24
source/documentation/style-rules/parent-selector.liquid
View File

@ -2,14 +2,16 @@
title: Parent Selector
introduction: >
The parent selector, `&`, is a special selector invented by Sass that’s used
in [nested selectors](/documentation/style-rules#nesting) to refer to the outer selector.
It makes it possible to re-use the outer selector in more complex ways, like
adding a
in [nested selectors](/documentation/style-rules#nesting) to refer to the
outer selector. It makes it possible to re-use the outer selector in more
complex ways, like adding a
[pseudo-class](https://developer.mozilla.org/en-US/docs/Web/CSS/Pseudo-classes)
or adding a selector *before* the parent.
---
When a parent selector is used in an inner selector, it's replaced with the corresponding outer selector. This happens instead of the normal nesting behavior.
When a parent selector is used in an inner selector, it's replaced with the
corresponding outer selector. This happens instead of the normal nesting
behavior.
{% codeExample 'parent-selector' %}
.alert {
@ -119,7 +121,10 @@ parent selector to append additional text.
## In SassScript
The parent selector can also be used within SassScript. It's a special
expression that returns the current parent selector in the same format used by [selector functions][]: a comma-separated list (the selector list) that contains space-separated lists (the complex selectors) that contain unquoted strings (the compound selectors).
expression that returns the current parent selector in the same format used by
[selector functions][]: a comma-separated list (the selector list) that contains
space-separated lists (the complex selectors) that contain unquoted strings (the
compound selectors).
[selector functions]: /documentation/modules/selector#selector-values
{% endmarkdown %}
@ -140,7 +145,9 @@ expression that returns the current parent selector in the same format used by [
{% endcodeExample %}
{% markdown %}
If the `&` expression is used outside any style rules, it returns `null`. Since `null` is [falsey][], this means you can easily use it to determine whether a mixin is being called in a style rule or not.
If the `&` expression is used outside any style rules, it returns `null`. Since
`null` is [falsey][], this means you can easily use it to determine whether a
mixin is being called in a style rule or not.
[falsey]: /documentation/at-rules/control/if#truthiness-and-falsiness
{% endmarkdown %}
@ -150,7 +157,10 @@ If the `&` expression is used outside any style rules, it returns `null`. Since
{% markdown %}
### Advanced Nesting
You can use `&` as a normal SassScript expression, which means you can pass it to functions or include it in interpolation—even in other selectors! Using it in combination with [selector functions][] and the [`@at-root` rule][] allows you to nest selectors in very powerful ways.
You can use `&` as a normal SassScript expression, which means you can pass it
to functions or include it in interpolation—even in other selectors! Using it in
combination with [selector functions][] and the [`@at-root` rule][] allows you
to nest selectors in very powerful ways.
[selector functions]: /documentation/modules/selector#selector-values
[`@at-root` rule]: /documentation/at-rules/at-root

11
source/documentation/style-rules/placeholder-selectors.liquid
View File

@ -7,10 +7,14 @@ introduction: >
the commas) that even *contains* a placeholder selector isn't included in the
CSS, nor is any style rule whose selectors all contain placeholders.
---
{% render 'code-snippets/example-placeholder' %}
{% markdown %}
What's the use of a selector that isn't emitted? It can still be [extended][]! Unlike class selectors, placeholders don't clutter up the CSS if they aren't extended and they don't mandate that users of a library use specific class names for their HTML.
What's the use of a selector that isn't emitted? It can still be [extended][]!
Unlike class selectors, placeholders don't clutter up the CSS if they aren't
extended and they don't mandate that users of a library use specific class names
for their HTML.
[extended]: /documentation/at-rules/extend
{% endmarkdown %}
@ -55,5 +59,8 @@ What's the use of a selector that isn't emitted? It can still be [extended][]! U
{% endcodeExample %}
{% markdown %}
Placeholder selectors are useful when writing a Sass library where each style rule may or may not be used. As a rule of thumb, if you're writing a stylesheet just for your own app, it's often better to just extend a class selector if one is available.
Placeholder selectors are useful when writing a Sass library where each style
rule may or may not be used. As a rule of thumb, if you're writing a stylesheet
just for your own app, it's often better to just extend a class selector if one
is available.
{% endmarkdown %}

35
source/documentation/syntax/comments.liquid
View File

@ -1,8 +1,12 @@
---
title: Comments
introduction: >
The way Sass comments work differs substantially between SCSS and the indented syntax. Both syntaxes support two types of comments: comments defined using `/* */` that are (usually) compiled to CSS, and comments defined using `//` that are not.
The way Sass comments work differs substantially between SCSS and the indented
syntax. Both syntaxes support two types of comments: comments defined using
`/* */` that are (usually) compiled to CSS, and comments defined using `//`
that are not.
---
{% markdown %}
## In SCSS
@ -18,27 +22,27 @@ compiled to a CSS comment. They're also called **loud comment**, by contrast
with silent comments. A multi-line comment that's compiled to CSS may contain
[interpolation][], which will be evaluated before the comment is compiled.
By default, multi-line comments be stripped from the compiled CSS in [compressed
mode][]. If a comment begins with `/*!`, though, it will always be included in
the CSS output.
By default, multi-line comments will be stripped from the compiled CSS in
[compressed mode][]. If a comment begins with `/*!`, though, it will always be
included in the CSS output.
[statement]: /documentation/syntax/structure#statements
[interpolation]: /documentation/interpolation
[compressed mode]: /documentation/cli/dart-sass#style
{% endmarkdown %}
{% codeExample 'scss-comment', , true, 'scss'%}
// This comment won't be included in the CSS.
{% codeExample 'scss-comment', true, 'scss' %}
// This comment won't be included in the CSS.
/* But this comment will, except in compressed mode. */
/* It can also contain interpolation:
* 1 + 1 = #{1 + 1} */
* 1 + 1 = #{1 + 1} */
/*! This comment will be included even in compressed mode. */
p /* Multi-line comments can be written anywhere
* whitespace is allowed. */ .sans {
* whitespace is allowed. */ .sans {
font: Helvetica, // So can single-line comments.
sans-serif;
}
@ -65,14 +69,14 @@ case, they have exactly the same syntax as they do in SCSS.
[expressions]: /documentation/syntax/structure#expressions
{% endmarkdown %}
{% codeExample 'sass-comment', , true, 'sass'%}
{% codeExample 'sass-comment', true, 'sass' %}
// This comment won't be included in the CSS.
This is also commented out.
This is also commented out.
/* But this comment will, except in compressed mode.
/* It can also contain interpolation:
1 + 1 = #{1 + 1}
1 + 1 = #{1 + 1}
/*! This comment will be included even in compressed mode.
@ -85,10 +89,9 @@ p .sans
When writing style libraries using Sass, you can use comments to document the
[mixins][], [functions][], [variables][], and [placeholder selectors][] that
your library provides, as well as the library itself. These are comments are
read by the [SassDoc][] tool, which uses them to generate beautiful
documentation. Check out [the Susy grid engine][susy]'s documentation to see it
in action!
your library provides, as well as the library itself. These comments are read by
the [SassDoc][] tool, which uses them to generate beautiful documentation. Check
out [the Susy grid engine][susy]'s documentation to see it in action!
[mixins]: /documentation/at-rules/mixin
[functions]: /documentation/at-rules/function
@ -106,7 +109,7 @@ detail.
[annotations]: http://sassdoc.com/annotations/
{% endmarkdown %}
{% codeExample 'documentation-comment', , false%}
{% codeExample 'documentation-comment' %}
/// Computes an exponent.
///
/// @param {number} $base

4
source/documentation/syntax/index.md
View File

@ -53,9 +53,9 @@ indented syntax that are noted throughout the reference.
{% headsUp %}
The indented syntax currently doesn't support expressions that wrap across
multiple lines. See [issue 216].
multiple lines. See [issue #216].
[issue 216]: https://github.com/sass/sass/issues/216
[issue #216]: https://github.com/sass/sass/issues/216
{% endheadsUp %}

13
source/documentation/syntax/parsing.liquid
View File

@ -9,24 +9,26 @@ introduction: >
{% # Arguments are (in order): `dart`, `libsass`, `node`, `ruby`, optional feature name, additional details within %}
{% compatibility false, true, null, true %}
Dart Sass currently _only_ supports the UTF-8 encoding. As such, it's safest to encode all Sass stylesheets as UTF-8.
Dart Sass currently *only* supports the UTF-8 encoding. As such, it's safest to
encode all Sass stylesheets as UTF-8.
{% endcompatibility %}
{% markdown %}
It's often the case that a document is initially available only as a sequence of
bytes, which must be decoded into Unicode. Sass performs this decoding as
follows:
- If the sequence of bytes begins with the UTF-8 or UTF-16 encoding of U+FEFF
* If the sequence of bytes begins with the UTF-8 or UTF-16 encoding of U+FEFF
BYTE ORDER MARK, the corresponding encoding is used.
- If the sequence of bytes begins with the plain ASCII string `@charset`, Sass
* If the sequence of bytes begins with the plain ASCII string `@charset`, Sass
determines the encoding using step 2 of the CSS algorithm for
[determining the fallback encoding][].
[determining the fallback encoding]: https://drafts.csswg.org/css-syntax-3/#input-byte-stream
- Otherwise, UTF-8 is used.
* Otherwise, UTF-8 is used.
## Parse Errors
@ -36,7 +38,7 @@ invalid syntax and the reason it was invalid.
Note that this is different than CSS, which specifies how to recover from most
errors rather than failing immediately. This is one of the few cases where SCSS
isn't _strictly_ a superset of CSS. However, it's much more useful to Sass users
isn't *strictly* a superset of CSS. However, it's much more useful to Sass users
to see errors immediately, rather than having them passed through to the CSS
output.
@ -47,4 +49,5 @@ Node Sass's and Dart Sass's JS API you can access the [`file`, `line`, and
[`SassException.span`]: https://pub.dartlang.org/documentation/sass/latest/sass/SassException/span.html
[js error]: https://github.com/sass/node-sass#error-object
{% endmarkdown %}

86
source/documentation/syntax/special-functions.liquid
View File

@ -1,20 +1,21 @@
---
title: Special Functions
table_of_contents: true
introduction: >
CSS defines many functions, and most of them work just fine with Sass’s normal
function syntax. They’re parsed as function calls, resolved to [plain CSS
functions](/documentation/at-rules/function#plain-css-functions), and compiled as-is to
CSS. There are a few exceptions, though, which have special syntax that can’t
just be parsed as a [SassScript expression](/documentation/syntax/structure#expressions). All
special function calls return [unquoted strings](/documentation/values/strings#unquoted).
table_of_contents: true
functions](/documentation/at-rules/function#plain-css-functions), and compiled
as-is to CSS. There are a few exceptions, though, which have special syntax
that can’t just be parsed as a [SassScript
expression](/documentation/syntax/structure#expressions). All special function
calls return [unquoted strings](/documentation/values/strings#unquoted).
---
{% markdown %}
## `url()`
The [`url()` function][] is commonly used in CSS, but its syntax is different
than other functions: it can take either a quoted _or_ unquoted URL. Because an
than other functions: it can take either a quoted *or* unquoted URL. Because an
unquoted URL isn't a valid SassScript expression, Sass needs special logic to
parse it.
@ -35,62 +36,63 @@ calls][]—it's parsed as a normal [plain CSS function call][].
$roboto-font-path: "../fonts/roboto";
@font-face {
// This is parsed as a normal function call that takes a quoted string.
src: url("#{$roboto-font-path}/Roboto-Thin.woff2") format("woff2");
// This is parsed as a normal function call that takes a quoted string.
src: url("#{$roboto-font-path}/Roboto-Thin.woff2") format("woff2");
font-family: "Roboto";
font-weight: 100;
font-family: "Roboto";
font-weight: 100;
}
@font-face {
// This is parsed as a normal function call that takes an arithmetic
// expression.
src: url($roboto-font-path + "/Roboto-Light.woff2") format("woff2");
// This is parsed as a normal function call that takes an arithmetic
// expression.
src: url($roboto-font-path + "/Roboto-Light.woff2") format("woff2");
font-family: "Roboto";
font-weight: 300;
font-family: "Roboto";
font-weight: 300;
}
@font-face {
// This is parsed as an interpolated special function.
src: url(#{$roboto-font-path}/Roboto-Regular.woff2) format("woff2");
// This is parsed as an interpolated special function.
src: url(#{$roboto-font-path}/Roboto-Regular.woff2) format("woff2");
font-family: "Roboto";
font-weight: 400;
}
font-family: "Roboto";
font-weight: 400;
}
===
$roboto-font-path: "../fonts/roboto"
@font-face
// This is parsed as a normal function call that takes a quoted string.
src: url("#{$roboto-font-path}/Roboto-Thin.woff2") format("woff2")
// This is parsed as a normal function call that takes a quoted string.
src: url("#{$roboto-font-path}/Roboto-Thin.woff2") format("woff2")
font-family: "Roboto"
font-weight: 100
font-family: "Roboto"
font-weight: 100
@font-face
// This is parsed as a normal function call that takes an arithmetic
// expression.
src: url($roboto-font-path + "/Roboto-Light.woff2") format("woff2")
// This is parsed as a normal function call that takes an arithmetic
// expression.
src: url($roboto-font-path + "/Roboto-Light.woff2") format("woff2")
font-family: "Roboto"
font-weight: 300
font-family: "Roboto"
font-weight: 300
@font-face
// This is parsed as an interpolated special function.
src: url(#{$roboto-font-path}/Roboto-Regular.woff2) format("woff2")
// This is parsed as an interpolated special function.
src: url(#{$roboto-font-path}/Roboto-Regular.woff2) format("woff2")
font-family: "Roboto"
font-weight: 400
font-family: "Roboto"
font-weight: 400
{% endcodeExample %}
{{ '## `element()`, `progid:...()`, and `expression()`' | markdown }}
{% # Arguments are (in order): `dart`, `libsass`, `node`, `ruby`, optional feature name, additional details within %}
{% compatibility "<1.40.0", false, null, false, "calc()" %}
LibSass, Ruby Sass, and versions of Dart Sass prior to 1.40.0 parse `calc()` as special syntactic function like `element()`.
LibSass, Ruby Sass, and versions of Dart Sass prior to 1.40.0 parse `calc()` as
special syntactic function like `element()`.
Dart Sass versions 1.40.0 and later parse `calc()` as a [calculation].
@ -99,8 +101,8 @@ Dart Sass versions 1.40.0 and later parse `calc()` as a [calculation].
{% # Arguments are (in order): `dart`, `libsass`, `node`, `ruby`, optional feature name, additional details within %}
{% compatibility ">=1.31.0 <1.40.0", false, null, false, "clamp()" %}
LibSass, Ruby Sass, and versions of Dart Sass prior to 1.31.0 parse `clamp()`
as a [plain CSS function] rather than supporting special syntax within it.
LibSass, Ruby Sass, and versions of Dart Sass prior to 1.31.0 parse `clamp()` as
a [plain CSS function] rather than supporting special syntax within it.
[plain CSS function]: /documentation/at-rules/function#plain-css-functions
@ -113,7 +115,8 @@ Dart Sass versions 1.40.0 and later parse `clamp()` as a [calculation].
{% endcompatibility %}
{% markdown %}
The [`element()`] function is defined in the CSS spec, and because its IDs couldbe parsed as colors, they need special parsing.
The [`element()`] function is defined in the CSS spec, and because its IDs could
be parsed as colors, they need special parsing.
[`element()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/element
@ -125,27 +128,26 @@ compatibility.
[`expression()`]: https://blogs.msdn.microsoft.com/ie/2008/10/16/ending-expressions/
[`progid:`]: https://blogs.msdn.microsoft.com/ie/2009/02/19/the-css-corner-using-filters-in-ie8/
Sass allows _any text_ in these function calls, including nested parentheses.
Sass allows *any text* in these function calls, including nested parentheses.
Nothing is interpreted as a SassScript expression, with the exception that
[interpolation][] can be used to inject dynamic values.
[interpolation]: /documentation/interpolation
{% endmarkdown %}
{% codeExample 'element' %}
$logo-element: logo-bg;
.logo {
background: element(##{$logo-element});
background: element(##{$logo-element});
}
===
$logo-element: logo-bg
.logo
background: element(##{$logo-element})
background: element(##{$logo-element})
===
.logo {
background: element(#logo-bg);
background: element(#logo-bg);
}
{% endcodeExample %}

5
source/helpers/components/codeExample.ts
View File

@ -96,9 +96,12 @@ const generateCodeExample = (
if (sections.length !== 1) {
throw new Error("Can't auto-generate CSS from more than one SCSS block.");
}
cssContents = sass.compileString(sections[0], {
const css = sass.compileString(sections[0], {
syntax: syntax === 'sass' ? 'indented' : 'scss',
}).css;
if (css.trim()) {
cssContents = css;
}
}
const cssExamples =