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

make call outs less… called out

Browse Source
This commit is contained in:
Jina Anne 2019-03-04 16:24:31 -08:00
parent 8aa45d75a3
commit 94c9c002ec
42 changed files with 229 additions and 306 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
helpers/sass_helpers.rb
View File

@ -271,7 +271,7 @@ module SassHelpers
# The contents should be supplied as a block.
def heads_up
concat(content_tag :aside, [
content_tag(:h3, 'Heads up!'),
content_tag(:h3, '⚠️ Heads up!'),
_render_markdown(_capture {yield})
], class: 'sl-c-callout sl-c-callout--warning')
end
@ -282,7 +282,7 @@ module SassHelpers
# The contents should be supplied as a block.
def fun_fact
concat(content_tag :aside, [
content_tag(:h3, 'Fun fact:'),
content_tag(:h3, '💡 Fun fact:'),
_render_markdown(_capture {yield})
], class: 'sl-c-callout sl-c-callout--fun-fact')
end

23
source/assets/css/components/_callouts.scss
View File

@ -1,24 +1,13 @@
.sl-c-callout {
margin: 1.5rem 0;
padding: .75rem 1rem;
background: $sl-color--midnight-blue;
color: $sl-color--white;
padding: 1.5rem 1rem;
background: darken($sl-color--pale-sky, 25%);
a,
code { color: inherit; }
&--warning { background: lighten($sl-color--hopbush, 36%); }
a {
border-bottom: 1px solid rgba(rgba($sl-color--white, .75), .5);
font-weight: $sl-font-weight--bold;
color: inherit;
&--fun-fact { background: lighten($sl-color--patina, 43%); }
&:hover,
&:focus { border-bottom-color: rgba($sl-color--white, .5); }
> *:first-child { margin-top: 0; }
&:active { border-bottom-color: rgba($sl-color--white, .75); }
}
&--warning { background: darken($sl-color--hopbush, 10%); }
&--fun-fact { background: darken($sl-color--patina, 10%); }
> *:last-child { margin-bottom: 0; }
}

9
source/documentation/at-rules.html.md.erb
View File

@ -1,12 +1,11 @@
---
title: At-Rules
introduction: >
Much of Sass’s extra functionality comes in the form of new
[at-rules](https://developer.mozilla.org/en-US/docs/Web/CSS/At-rule) it adds
on top of CSS:
---
Much of Sass's extra functionality comes in the form of new [at-rules][] it adds
on top of CSS:
[at-rules]: https://developer.mozilla.org/en-US/docs/Web/CSS/At-rule
* [`@import`](at-rules/import) extends the CSS at-rule to load styles, mixins,
functions, and variables from other stylesheets.

16
source/documentation/at-rules/at-root.html.md.erb
View File

@ -1,16 +1,14 @@
---
title: "@at-root"
introduction: >
The `@at-root` rule is usually written `@at-root <selector> { ... }` and
causes everything within it to be emitted at the root of the document instead
of using the normal nesting. It's most often used when doing [advanced
nesting](../style-rules/parent-selector#advanced-nesting) with the [SassScript
parent selector](../style-rules/parent-selector#in-sassscript) and [selector
functions](../functions/selector).
---
The `@at-root` rule is usually written `@at-root <selector> { ... }` and causes
everything within it to be emitted at the root of the document instead of using
the normal nesting. It's most often used when doing [advanced nesting][] with
the [SassScript parent selector][] and [selector functions][].
[advanced nesting]: ../style-rules/parent-selector#advanced-nesting
[SassScript parent selector]: ../style-rules/parent-selector#in-sassscript
[selector functions]: ../functions/selector
<%= partial 'code-snippets/example-advanced-nesting' %>
The `@at-root` rule is necessary here because Sass doesn't know what

13
source/documentation/at-rules/control.html.md.erb
View File

@ -1,15 +1,12 @@
---
title: Flow Control Rules
introduction: >
Sass provides a number of at-rules that make it possible to control whether
styles get emitted, or to emit them multiple times with small variations. They
can also be used in [mixins](mixin) and [functions](function) to write small
algorithms to make writing your Sass easier.
---
Sass provides a number of at-rules that make it possible to control whether
styles get emitted, or to emit them multiple times with small variations. They
can also be used in [mixins][] and [functions][] to write small algorithms to
make writing your Sass easier.
[mixins]: mixin
[functions]: function
Sass supports four flow control rules:
* [`@if`](control/if) controls whether or not a block is evaluated.

20
source/documentation/at-rules/control/each.html.md.erb
View File

@ -1,18 +1,16 @@
---
title: "@each"
introduction: >
The `@each` rule makes it easy to emit styles or evaluate code for each
element of a [list](../../values/lists) or each pair in a
[map](../../values/maps). It’s great for repetitive styles that only have a
few variations between them. It’s usually written `@each <variable> in
<expression> { ... }`, where the
[expression](../../syntax/structure#expressions) returns a list. The block is
evaluated for each element of the list in turn, which is assigned to the given
variable name.
---
The `@each` rule makes it easy to emit styles or evaluate code for each element
of a [list][] or each pair in a [map][]. It's great for repetitive styles that
only have a few variations between them. It's usually written
`@each <variable> in <expression> { ... }`, where the [expression][] returns a
list. The block is evaluated for each element of the list in turn, which is
assigned to the given variable name.
[list]: ../../values/lists
[map]: ../../values/maps
[expression]: ../../syntax/structure#expressions
<%= partial 'code-snippets/example-each-list' %>
## With Maps

18
source/documentation/at-rules/control/for.html.md.erb
View File

@ -1,17 +1,15 @@
---
title: "@for"
introduction: >
The `@for` rule, written `@for <variable> from <expression> to <expression>
{ ... }` or `@for <variable> from <expression> through <expression> { ... }`,
counts up or down from one number (the result of the first
[expression](../../syntax/structure#expressions)) to another (the result of
the second) and evaluates a block for each number in between. Each number
along the way is assigned to the given variable name. If `to` is used, the
final number is excluded; if `through` is used, it's included.
---
The `@for` rule, written
`@for <variable> from <expression> to <expression> { ... }` or
`@for <variable> from <expression> through <expression> { ... }`, counts up or
down from one number (the result of the first [expression][]) to another (the
result of the second) and evaluates a block for each number in between. Each
number along the way is assigned to the given variable name. If `to` is used,
the final number is excluded; if `through` is used, it's included.
[expression]: ../../syntax/structure#expressions
<% example do %>
$base-color: #036;

15
source/documentation/at-rules/control/if.html.md.erb
View File

@ -1,17 +1,14 @@
---
title: "@if and @else"
table_of_contents: true
introduction: >
The `@if` rule is written `@if <expression> { ... }`, and it controls whether
or not its block gets evaluated (including emitting any styles as CSS). The
[expression](../../syntax/structure#expressions) usually returns either
[`true` or `false`](../../values/booleans)—if the expression returns `true`,
the block is evaluated, and if the expression returns `false` it’s not.
---
The `@if` rule is written `@if <expression> { ... }`, and it controls whether or
not its block gets evaluated (including emitting any styles as CSS). The
[expression][] usually returns either [`true` or `false`][]—if the expression
returns `true`, the block is evaluated, and if the expression returns `false`
it's not.
[expression]: ../../syntax/structure#expressions
[`true` or `false`]: ../../values/booleans
<%= partial 'code-snippets/example-if' %>
## `@else`

12
source/documentation/at-rules/control/while.html.md.erb
View File

@ -1,14 +1,12 @@
---
title: "@while"
introduction: >
The `@while` rule, written `@while <expression> { ... }`, evaluates its block
if its [expression](../../syntax/structure#expressions) returns `true`. Then,
if its expression still returns `true`, it evaluates its block again. This
continues until the expression finally returns `false`.
---
The `@while` rule, written `@while <expression> { ... }`, evaluates its block if
its [expression][] returns `true`. Then, if its expression still returns `true`,
it evaluates its block again. This continues until the expression finally
returns `false`.
[expression]: ../../syntax/structure#expressions
<% example do %>
/// Divides `$value` by `$ratio` until it's below `$base`.
@function scale-below($value, $base, $ratio: 1.618) {

14
source/documentation/at-rules/debug.html.md.erb
View File

@ -1,15 +1,13 @@
---
title: "@debug"
introduction: >
Sometimes it’s useful to see the value of a [variable](../variables) or
[expression](../syntax/structure#expressions) while you’re developing your
stylesheet. That’s what the `@debug` rule is for: it’s written
`@debug <expression>`, and it prints the value of that expression, along with
the filename and line number.
---
Sometimes it's useful to see the value of a [variable][] or [expression][] while
you're developing your stylesheet. That's what the `@debug` rule is for: it's
written `@debug <expression>`, and it prints the value of that expression, along
with the filename and line number.
[variable]: ../variables
[expression]: ../syntax/structure#expressions
<% example(autogen_css: false) do %>
@mixin inset-divider-offset($offset, $padding) {
$divider-offset: (2 * $padding) + $offset;

13
source/documentation/at-rules/error.html.md.erb
View File

@ -1,15 +1,12 @@
---
title: "@error"
introduction: >
When writing [mixins](mixin) and [functions](function) that take arguments,
you usually want to ensure that those arguments have the types and formats
your API expects. If they aren't, the user needs to be notified and your
mixin/function needs to stop running.
---
When writing [mixins][] and [functions][] that take arguments, you usually want
to ensure that those arguments have the types and formats your API expects. If
they aren't, the user needs to be notified and your mixin/function needs to stop
running.
[mixins]: mixin
[functions]: function
Sass makes this easy with the `@error` rule, which is written
`@error <expression>`. It prints the value of the [expression][] (usually a
string) along with a stack trace indicating how the current mixin or function

16
source/documentation/at-rules/extend.html.md.erb
View File

@ -1,17 +1,15 @@
---
title: "@extend"
table_of_contents: true
introduction: >
There are often cases when designing a page when one class should have all the
styles of another class, as well as its own specific styles. For example, the
[BEM methodology](http://getbem.com/naming/) encourages modifier classes that
go on the same elements as block or element classes. But this can create
cluttered HTML, it's prone to errors from forgetting to include both classes,
and it can bring non-semantic style concerns into your markup.
---
There are often cases when designing a page when one class should have all the
styles of another class, as well as its own specific styles. For example, the
[BEM methodology][] encourages modifier classes that go on the same elements as
block or element classes. But this can create cluttered HTML, it's prone to
errors from forgetting to include both classes, and it can bring non-semantic
style concerns into your markup.
[BEM methodology]: http://getbem.com/naming/
<%# TODO(jina): I think these code blocks should be side-by-side %>
```html

10
source/documentation/at-rules/function.html.md.erb
View File

@ -1,14 +1,12 @@
---
title: "@function"
table_of_contents: true
introduction: >
Functions allow you to define complex operations on [SassScript
values](../values) that you can re-use throughout your stylesheet. They make
it easy to abstract out common formulas and behaviors in a readable way.
---
Functions allow you to define complex operations on [SassScript values][] that
you can re-use throughout your stylesheet. They make it easy to abstract out
common formulas and behaviors in a readable way.
[SassScript values]: ../values
Functions are defined using the `@function` at-rule, which is written
`@function <name>(<arguments...>) { ... }`. A function's name can be any Sass
identifier. It can only contain [universal statements][], as well as the

19
source/documentation/at-rules/import.html.md.erb
View File

@ -1,19 +1,16 @@
---
title: "@import"
table_of_contents: true
introduction: >
Sass extends CSS's [`@import`
rule](https://developer.mozilla.org/en-US/docs/Web/CSS/@import) with the
ability to import Sass and CSS stylesheets, providing access to
[mixins](mixin), [functions](function), and [variables](../variables) and
combining multiple stylesheets' CSS together. Unlike plain CSS imports, which
require the browser to make multiple HTTP requests as it renders your page,
Sass imports are handled entirely during compilation.
---
Sass extends CSS's [`@import` rule][] with the ability to import Sass and CSS
stylesheets, providing access to [mixins][], [functions][], and [variables][]
and combining multiple stylesheets' CSS together. Unlike plain CSS imports,
which require the browser to make multiple HTTP requests as it renders your
page, Sass imports are handled entirely during compilation.
[`@import` rule]: https://developer.mozilla.org/en-US/docs/Web/CSS/@import
[mixins]: mixin
[functions]: function
[variables]: ../variables
Sass imports have the same syntax as CSS imports, except that they allow
multiple imports to be separated by commas rather than requiring each one to
have its own `@import`. Also, in the [indented syntax][], imported URLs aren't

8
source/documentation/at-rules/mixin.html.md.erb
View File

@ -1,12 +1,12 @@
---
title: "@mixin and @include"
table_of_contents: true
introduction: >
Mixins allow you to define styles that can be re-used throughout your
stylesheet. They make it easy to avoid using non-semantic classes like
`.float-left`, and to distribute collections of styles in libraries.
---
Mixins allow you to define styles that can be re-used throughout your
stylesheet. They make it easy to avoid using non-semantic classes like
`.float-left`, and to distribute collections of styles in libraries.
Mixins are defined using the `@mixin` at-rule, which is written
`@mixin <name> { ... }` or `@mixin name(<arguments...>) { ... }`. A mixin's name
can be any Sass identifier, and it can contain any [statement][] other than

13
source/documentation/at-rules/warn.html.md.erb
View File

@ -1,15 +1,12 @@
---
title: "@warn"
introduction: >
When writing [mixins](mixin) and [functions](function), you may want to
discourage users from passing certain arguments or certain values. They may be
passing legacy arguments that are now deprecated, or they may be calling your
API in a way that’s not quite optimal.
---
When writing [mixins][] and [functions][], you may want to discourage users from
passing certain arguments or certain values. They may be passing legacy
arguments that are now deprecated, or they may be calling your API in a way
that's not quite optimal.
[mixins]: mixin
[functions]: function
The `@warn` rule is designed just for that. It's written `@warn <expression>`
and it prints the value of the [expression][] (usually a string) for the user,
along with a stack trace indicating how the current mixin or function was

6
source/documentation/cli.html.md.erb
View File

@ -1,10 +1,10 @@
---
title: Command-Line Interface
introduction: >
Different implementations of Sass have different interfaces when using them
from the command line:
---
Different implementations of Sass have different interfaces when using them from
the command line:
* [Dart Sass](cli/dart-sass) has the same command-line interface no matter how
you [install it](/dart-sass).

14
source/documentation/functions.html.md.erb
View File

@ -1,15 +1,13 @@
---
title: Built-In Functions
introduction: >
In addition to allowing users to [define their own
functions](at-rules/function), there are many useful functions built right
into Sass. These functions are called using the normal CSS function syntax,
with the addition of [special Sass argument
syntax](at-rules/function#arguments).
---
In addition to allowing users to [define their own functions][], there are many
useful functions built right into Sass. These functions are called using the
normal CSS function syntax, with the addition of [special Sass argument
syntax][].
[define their own functions]: at-rules/function
[special Sass argument syntax]: at-rules/function#arguments
Sass's built-in functions are divided into a few categories:
* Any function that Sass doesn't recognize as built-in or user-defined is

18
source/documentation/functions/css.html.md.erb
View File

@ -1,17 +1,15 @@
---
title: Plain CSS Functions
introduction: >
Any function call that's not either a [built-in](../functions) or
[user-defined](../at-rules/function) function is compiled to a plain CSS
function (unless it uses [Sass argument
syntax](../at-rules/function#arguments)). The arguments will be compiled to
CSS and included as-is in the function call. This ensures that Sass supports
all CSS functions without needing to release new versions every time a new one
is added.
---
Any function call that's not either a [built-in][] or [user-defined][] function
is compiled to a plain CSS function (unless it uses [Sass argument syntax][]).
The arguments will be compiled to CSS and included as-is in the function call.
This ensures that Sass supports all CSS functions without needing to release new
versions every time a new one is added.
[built-in]: ../functions
[user-defined]: ../at-rules/function
[Sass argument syntax]: ../at-rules/function#arguments
<% example(autogen_css: false) do %>
@debug var(--main-bg-color); // var(--main-bg-color)

18
source/documentation/index.html.md
View File

@ -1,17 +1,15 @@
---
title: Documentation
introduction: >
Sass is a stylesheet language that’s compiled to CSS. It allows you to use
[variables](/documentation/variables), [nested
rules](/documentation/style-rules#nesting),
[mixins](/documentation/at-rules/mixin),
[functions](/documentation/functions), and more, all with a fully
CSS-compatible syntax. Sass helps keep large stylesheets well-organized and
makes it easy to share design within and across projects.
---
Sass is a stylesheet language that's compiled to CSS. It allows you to use
[variables][], [nested rules][], [mixins][], [functions][], and more, all with a
fully CSS-compatible syntax. Sass helps keep large stylesheets well-organized
and makes it easy to share design within and across projects.
[variables]: /documentation/variables
[nested rules]: /documentation/style-rules#nesting
[mixins]: /documentation/at-rules/mixin
[functions]: /documentation/functions
* If you're looking for an introduction to Sass, check out [the
tutorial](/guide).

10
source/documentation/interpolation.html.md.erb
View File

@ -1,14 +1,12 @@
---
title: Interpolation
table_of_contents: true
introduction: >
Interpolation can be used almost anywhere in a Sass stylesheet to embed the
result of a [SassScript expression](syntax/structure#expressions) into a chunk
of CSS. Just wrap an expression in `#{}` in any of the following places:
---
Interpolation can be used almost anywhere in a Sass stylesheet to embed the
result of a [SassScript expression][] into a chunk of CSS. Just wrap an
expression in `#{}` in any of the following places:
[SassScript expression]: syntax/structure#expressions
* [Selectors in style rules](style-rules#interpolation)
* [Property names in declarations](style-rules/declarations#interpolation)
* [Custom property values](style-rules/declarations#custom-properties)

17
source/documentation/js-api.html.md.erb
View File

@ -1,17 +1,14 @@
---
title: JavaScript API
table_of_contents: true
introduction: >
Both major Sass implementations support the same JavaScript API. [Dart
Sass](/dart-sass) is distributed as the pure-Javascript [`sass`
package](https://www.npmjs.com/package/sass), and [LibSass](/libsass) is
distributed as a native extension in the [`node-sass`
package](https://www.npmjs.com/package/node-sass).
---
Both major Sass implementations support the same JavaScript API. [Dart Sass][]
is distributed as the pure-Javascript [`sass` package][], and [LibSass][] is
distributed as a native extension in the [`node-sass` package][].
[Dart Sass]: /dart-sass
[`sass` package]: https://www.npmjs.com/package/sass
[LibSass]: /libsass
[`node-sass` package]: https://www.npmjs.com/package/node-sass
## Usage
The Sass module provides two functions with similar APIs.
@ -810,7 +807,7 @@ wrappers for its various [value types][]. These are all provided under the
they don't match the general principle that Sass values are immutable. Users
should construct new objects rather than modifying existing ones.
[`Map` type]: #types-map
[`List` type]: #types-list
<% end %>

8
source/documentation/operators.html.md.erb
View File

@ -1,11 +1,11 @@
---
title: Operators
introduction: >
Sass supports a handful of useful `operators` for working with different
values. These include the standard mathematical operators like `+` and `*`, as
well as operators for various other types:
---
Sass supports a handful of useful `operators` for working with different values.
These include the standard mathematical operators like `+` and `*`, as well as
operators for various other types:
<%= partial 'documentation/snippets/operator-list', locals: {parens: false} %>
<% heads_up do %>

8
source/documentation/operators/boolean.html.md.erb
View File

@ -1,12 +1,10 @@
---
title: Boolean Operators
introduction: >
Unlike languages like JavaScript, Sass uses words rather than symbols for its
[boolean](../values/booleans) operators.
---
Unlike languages like JavaScript, Sass uses words rather than symbols for its
[boolean][] operators.
[boolean]: ../values/booleans
* `not <expression>` returns the opposite of the expression's value: it turns
`true` into `false` and `false` into `true`.
* `<expression> and <expression>` returns `true` if *both* expressions' values

11
source/documentation/operators/numeric.html.md.erb
View File

@ -1,13 +1,12 @@
---
title: Numeric Operators
table_of_contents: true
introduction: >
Sass supports the standard set of mathematical operators for
[numbers](../values/numbers). They automatically convert between compatible
units.
---
Sass supports the standard set of mathematical operators for [numbers][]. They
automatically convert between compatible units.
[numbers]: ../values/numbers
* `<expression> + <expression>` adds the first [expression][]'s value to the
second's.
* `<expression> - <expression>` subtracts the first [expression][]'s value from
@ -112,7 +111,7 @@ You can also write `+` and `-` as unary operators, which take only one value:
@debug 5-3 // 2
@debug 1 -2 3 // 1 -2 3
$number: 2
$number: 2
@debug 1 -$number 3 // -1 3
@debug 1 (-$number) 3 // 1 -2 3
<% end %>

9
source/documentation/operators/relational.html.md.erb
View File

@ -1,12 +1,11 @@
---
title: Relational Operators
introduction: >
Relational operators determine whether [numbers](../values/numbers) are larger
or smaller than one another. They automatically convert between compatible
units.
---
Relational operators determine whether [numbers][] are larger or smaller than one
another. They automatically convert between compatible units.
[numbers]: ../values/numbers
* `<expression> < <expression>` returns whether the first [expression][]'s value
is less than the second's.
* `<expression> <= <expression>` returns whether the first [expression][]'s

6
source/documentation/operators/string.html.md.erb
View File

@ -1,11 +1,9 @@
---
title: String Operators
introduction: >
Sass supports a few operators that generate [strings](../values/strings):
---
Sass supports a few operators that generate [strings][]:
[strings]: ../values/strings
* `<expression> + <expression>` returns a string that contains both expressions'
values. If the either value is a [quoted string][], the result will be quoted;
otherwise, it will be unquoted.

12
source/documentation/style-rules.html.md.erb
View File

@ -1,11 +1,13 @@
---
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](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][declarations] that affect how those elements look.
---
<% example do %>
.button {
@ -22,8 +24,6 @@ work the same way: you choose which elements to style with a selector, and
border: 1px solid #e1e4e8
<% end %>
[declarations]: style-rules/declarations
## Nesting
But Sass wants to make your life easier. Rather than repeating the same

13
source/documentation/style-rules/declarations.html.md.erb
View File

@ -1,15 +1,14 @@
---
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](../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][], which will be evaluated and included in the result.
[SassScript expression]: ../syntax/structure#expressions
<% example do %>
.circle {
$size: 100px;

15
source/documentation/style-rules/parent-selector.html.md.erb
View File

@ -1,15 +1,14 @@
---
title: Parent Selector
introduction: >
The parent selector, `&`, is a special selector invented by Sass that’s used
in [nested selectors](../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.
---
The parent selector, `&`, is a special selector invented by Sass that's used in
[nested selectors][] 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][]
or adding a selector *before* the parent.
[nested selectors]: ../style-rules#nesting
[pseudo-class]: https://developer.mozilla.org/en-US/docs/Web/CSS/Pseudo-classes
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.

12
source/documentation/style-rules/placeholder-selectors.html.md.erb
View File

@ -1,13 +1,13 @@
---
title: Placeholder Selectors
introduction: >
Sass has a special kind of selector known as a “placeholder”. It looks and
acts a lot like a class selector, but it starts with a `%` and it's not
included in the CSS output. In fact, any complex selector (the ones between
the commas) that even *contains* a placeholder selector isn't included in the
CSS, nor is any style rule whose selectors all contain placeholders,
---
Sass has a special kind of selector known as a "placeholder". It looks and acts
a lot like a class selector, but it starts with a `%` and it's not included in
the CSS output. In fact, any complex selector (the ones between the commas) that
even *contains* a placeholder selector isn't included in the CSS, nor is any
style rule whose selectors all contain placeholders,
<%= partial "code-snippets/example-placeholder" %>
What's the use of a selector that isn't emitted? It can still be [extended][]!

10
source/documentation/syntax/comments.html.md.erb
View File

@ -1,12 +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.
## In SCSS
Comments in SCSS work similarly to comments in other languages like JavaScript.

6
source/documentation/syntax/parsing.html.md.erb
View File

@ -1,10 +1,10 @@
---
title: Parsing a Stylesheet
introduction: >
A Sass stylesheet is parsed from a sequence of Unicode code points. It's
parsed directly, without first being converted to a token stream.
---
A Sass stylesheet is parsed from a sequence of Unicode code points. It's parsed
directly, without first being converted to a token stream.
## Input Encoding
<% impl_status(dart: false, libsass: true, ruby: true) do %>

17
source/documentation/syntax/special-functions.html.md.erb
View File

@ -1,18 +1,15 @@
---
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](../functions/css), 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](structure#expressions). All special function calls
return [unquoted strings](../values/strings#unquoted).
---
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][], 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][]. All special function calls return [unquoted strings][].
[plain CSS functions]: ../functions/css
[SassScript expression]: structure#expressions
[unquoted strings]: ../values/strings#unquoted
## `url()`
The [`url()` function][] is commonly used in CSS, but its syntax is different

8
source/documentation/syntax/structure.html.md.erb
View File

@ -1,12 +1,12 @@
---
title: Structure of a Stylesheet
table_of_contents: true
introduction: >
Just like CSS, most Sass stylesheets are mainly made up of style rules that
contain property declarations. But Sass stylesheets have many more features
that can exist alongside these.
---
Just like CSS, most Sass stylesheets are mainly made up of style rules that
contain property declarations. But Sass stylesheets have many more features that
can exist alongside these.
## Statements
A Sass stylesheet is made up of a series of *statements*, which are evaluated in

11
source/documentation/values.html.md
View File

@ -1,14 +1,11 @@
---
title: Values
introduction: >
Sass supports a number of value types, most of which come straight from CSS.
Every [expression](syntax/structure#expressions) produces a value,
[variables](variables) hold values. Most value types come straight from CSS:
---
Sass supports a number of value types, most of which come straight from CSS.
Every [expression][] produces a value, [variables][] hold values. Most value
types come straight from CSS:
[expression]: syntax/structure#expressions
[variables]: variables
* [Numbers](values/numbers), which may or may not have units, like `12` or
`100px`.
* [Strings](values/strings), which may or may not have quotes, like

15
source/documentation/values/booleans.html.md.erb
View File

@ -1,16 +1,13 @@
---
title: Booleans
introduction: >
Booleans are the logical values `true` and `false`. In addition their literal
forms, booleans are returned by [equality](../operators/equality) and
[relational](../operators/relational) operators, as well as many built-in
functions like [`comparable()`](../functions/map#map-has-key) and
[`map-has-key()`](../functions/math#comparable).
---
Booleans are the logical values `true` and `false`. In addition their literal
forms, booleans are returned by [equality][] and [relational][] operators, as
well as many built-in functions like [`comparable()`][] and [`map-has-key()`][].
[equality]: ../operators/equality
[relational]: ../operators/relational
[`map-has-key()`]: ../functions/map#map-has-key
[`comparable()`]: ../functions/math#comparable
<% example(autogen_css: false) do %>
@debug 1px == 2px; // false
@debug 1px == 1px; // true

19
source/documentation/values/maps.html.md.erb
View File

@ -1,19 +1,16 @@
---
title: Maps
table_of_contents: true
introduction: >
Maps in Sass hold pairs of keys and values, and make it easy to look up a
value by its corresponding key. They're written `(<expression>: <expression>,
<expression>: <expression>)`. The
[expression](../syntax/structure#expressions) before the `:` is the key, and
the expression after is the value associated with that key. The keys must be
unique, but the values may be duplicated. Unlike [lists](lists), maps *must*
be written with parentheses around them. A map with no pairs is written `()`.
---
Maps in Sass hold pairs of keys and values, and make it easy to look up a value
by its corresponding key. They're written
`(<expression>: <expression>, <expression>: <expression>)`. The [expression][]
before the `:` is the key, and the expression after is the value associated with
that key. The keys must be unique, but the values may be duplicated. Unlike
[lists][], maps *must* be written with parentheses around them. A map with no
pairs is written `()`.
[expression]: ../syntax/structure#expressions
[lists]: lists
<% fun_fact do %>
Astute readers may note that an empty map, `()`, is written the same as an
empty list. That's because it counts as both a map and a list. In fact, *all*

9
source/documentation/values/null.html.md.erb
View File

@ -1,12 +1,11 @@
---
title: "null"
introduction: >
The value `null` is the only value of its type. It represents the absence of a
value, and is often returned by [functions](../at-rules/function) to indicate
the lack of a result.
---
The value `null` is the only value of its type. It represents the absence of a
value, and is often returned by [functions][] to indicate the lack of a result.
[functions]: ../at-rules/function
<% example(autogen_css: false) do %>
@debug str-index("Helvetica Neue", "Roboto"); // null
@debug map-get(("large": 20px), "small"); // null

11
source/documentation/values/numbers.html.md.erb
View File

@ -1,13 +1,12 @@
---
title: Numbers
introduction: >
Numbers in Sass have two components: the number itself, and its units. For
example, in `16px` the number is `16` and the unit is `px`. Numbers can have
no units, and they can have complex units. See [Units](#units) below for more
details.
---
Numbers in Sass have two components: the number itself, and its units. For
example, in `16px` the number is `16` and the unit is `px`. Numbers can have no
units, and they can have complex units. See [Units][] below for more details.
[Units]: #units
<% example(autogen_css: false) do %>
@debug 100; // 100
@debug 0.8; // 0.8

17
source/documentation/values/strings.html.md.erb
View File

@ -1,18 +1,15 @@
---
title: Strings
table_of_contents: true
introduction: >
Strings are sequences of characters (specifically [Unicode code
points](https://en.wikipedia.org/wiki/Code_point)). Sass supports two kinds of
strings whose internal structure is the same but which are rendered
differently: [quoted strings](#quoted), like `"Helvetica Neue"`, and [unquoted
strings](#unquoted) (also known as *identifiers*), like `bold`. Together,
these cover the different kinds of text that appear in CSS.
---
Strings are sequences of characters (specifically [Unicode code points][]). Sass
supports two kinds of strings whose internal structure is the same but which are
rendered differently: [quoted strings][], like `"Helvetica Neue"`, and [unquoted
strings][] (also known as *identifiers*), like `bold`. Together, these cover the
different kinds of text that appear in CSS.
[Unicode code points]: https://en.wikipedia.org/wiki/Code_point
[quoted strings]: #quoted
[unquoted strings]: #unquoted
<% fun_fact do %>
You can convert a quoted string to an unquoted string using the [`unquote()`
function][], and you can convert an unquoted string to a quoted string using

12
source/documentation/variables.html.md.erb
View File

@ -1,14 +1,14 @@
---
title: Variables
table_of_contents: true
introduction: >
Sass variables are simple: you assign a value to a name that begins with `$`,
and then you can refer to that name instead of the value itself. But despite
their simplicity, they're one of the most useful tools Sass brings to the
table. Variables make it possible to reduce repetition, do complex math,
configure libraries, and much more.
---
Sass variables are simple: you assign a value to a name that begins with `$`,
and then you can refer to that name instead of the value itself. But despite
their simplicity, they're one of the most useful tools Sass brings to the table.
Variables make it possible to reduce repetition, do complex math, configure
libraries, and much more.
A variable declaration looks a lot like a [property declaration][]: it's written
`<variable>: <expression>`. Unlike a property, which can only be declared in a
style rule or at-rule, variables can be declared anywhere you want. To use a