diff --git a/source/documentation/style-rules/declarations.liquid b/source/documentation/style-rules/declarations.liquid new file mode 100644 index 0000000..3ded41d --- /dev/null +++ b/source/documentation/style-rules/declarations.liquid @@ -0,0 +1,161 @@ +--- +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. +complementary_content: | + +--- +{% codeExample 'declaration' %} +.circle { + $size: 100px; + width: $size; + height: $size; + border-radius: $size * 0.5; +} +=== +.circle + $size: 100px + width: $size + height: $size + border-radius: $size * 0.5 +{% endcodeExample %} + +{% markdown %} +## Interpolation + +A property's name can include [interpolation][], which makes it possible to +dynamically generate properties as needed. You can even interpolate the entire +property name! + +[interpolation]: ../interpolation +{% endmarkdown %} + +{% codeExample 'interpolation' %} +@mixin prefix($property, $value, $prefixes) { + @each $prefix in $prefixes { + -#{$prefix}-#{$property}: $value; + } + #{$property}: $value; +} + +.gray { + @include prefix(filter, grayscale(50%), moz webkit); +} +=== +@mixin prefix($property, $value, $prefixes) + @each $prefix in $prefixes + -#{$prefix}-#{$property}: $value + + #{$property}: $value + + +.gray + @include prefix(filter, grayscale(50%), moz webkit) +{% endcodeExample %} + +{% markdown %} +## Nesting + +Many CSS properties start with the same prefix that acts as a kind of namespace. +For example, `font-family`, `font-size`, and `font-weight` all start with +`font-`. Sass makes this easier and less redundant by allowing property +declarations to be nested. The outer property names are added to the inner, +separated by a hyphen. +{% endmarkdown %} + +{% codeExample 'nesting' %} +.enlarge { + font-size: 14px; + transition: { + property: font-size; + duration: 4s; + delay: 2s; + } + + &:hover { font-size: 36px; } +} +=== +.enlarge + font-size: 14px + transition: + property: font-size + duration: 4s + delay: 2s + + &:hover + font-size: 36px +{% endcodeExample %} + +{% markdown %} +Some of these CSS properties have shorthand versions that use the namespace as +the property name. For these, you can write both the shorthand value *and* the +more explicit nested versions. +{% endmarkdown %} + +{% codeExample 'nesting-shorthand' %} +.info-page { + margin: auto { + bottom: 10px; + top: 2px; + } +} +=== +.info-page + margin: auto + bottom: 10px + top: 2px +{% endcodeExample %} + +{% markdown %} +## Hidden Declarations + +Sometimes you only want a property declaration to show up some of the time. If a +declaration's value is [`null`][] or an empty [unquoted string][], Sass won't +compile that declaration to CSS at all. + +[`null`]: ../values/null +[unquoted string]: ../values/strings#unquoted +{% endmarkdown %} + +{% codeExample 'hidden-declarations' %} +$rounded-corners: false; + +.button { + border: 1px solid black; + border-radius: if($rounded-corners, 5px, null); +} +=== +$rounded-corners: false + +.button + border: 1px solid black + border-radius: if($rounded-corners, 5px, null) +{% endcodeExample %} + +{% markdown %} +## Custom Properties +{% endmarkdown %} + +{% # Arguments are (in order): `dart`, `libsass`, `ruby`, optional feature name, additional details within %} +{% compatibility true, '3.5.0', '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. + +See [the breaking change page][] for more details. + +[the breaking change page]: ../breaking-changes/css-vars +{% endcompatibility %} diff --git a/source/documentation/style-rules/declarations.md b/source/documentation/style-rules/declarations.md deleted file mode 100644 index e69de29..0000000 diff --git a/source/documentation/style-rules/index.liquid b/source/documentation/style-rules/index.liquid new file mode 100644 index 0000000..c825627 --- /dev/null +++ b/source/documentation/style-rules/index.liquid @@ -0,0 +1,197 @@ +--- +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. +complementary_content: | + +--- +{% markdown %} +## Nesting + +But Sass wants to make your life easier. Rather than repeating the same +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 %} + + +{% headsUp %} + Nested rules are super helpful, but they can also make it hard to visualize how much CSS you're actually generating. The deeper you nest, the more bandwidth it takes to serve your CSS and the more work it takes the browser to render it. Keep those selectors shallow! +{% endheadsUp %} + +{% markdown %} +### Selector Lists + +Nested rules are clever about handling selector lists (that is, comma-separated +selectors). Each complex selector (the ones between the commas) is nested +separately, and then they're combined back into a selector list. +{% endmarkdown %} + +{% codeExample 'selector-lists' %} +.alert, .warning { + ul, p { + margin-right: 0; + margin-left: 0; + padding-bottom: 0; + } +} +=== +.alert, .warning + ul, p + margin-right: 0 + margin-left: 0 + padding-bottom: 0 +{% endcodeExample %} + +{% markdown %} +### Selector Combinators + +You can nest selectors that use [combinators][] as well. You can put the +combinator at the end of the outer selector, at the beginning of the inner +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'%} +ul > { + li { + list-style-type: none; + } +} + +h2 { + + p { + border-top: 1px solid gray; + } +} + +p { + ~ { + span { + opacity: 0.8; + } + } +} +=== +ul > + li + list-style-type: none + + + +h2 + + p + border-top: 1px solid gray + + + +p + ~ + span + opacity: 0.8 +{% endcodeExample %} + +{% markdown %} +### Advanced Nesting + +If you want to do more with your nested style rules than just combine them in +order with the descendant combinator (that is, a plain space) separating them, +Sass has your back. See the [parent selector documentation][] for more details. + +[parent selector documentation]: style-rules/parent-selector + +## Interpolation + +You can use [interpolation][] to inject values from [expressions][] like +variables and function calls into your selectors. This is particularly useful +when you're writing [mixins][], since it allows you to create selectors from +parameters your users pass in. + +[interpolation]: interpolation +[expressions]: syntax/structure#expressions +[mixins]: at-rules/mixin +{% endmarkdown %} + +{% codeExample 'interpolation'%} +@mixin define-emoji($name, $glyph) { + span.emoji-#{$name} { + font-family: IconFont; + font-variant: normal; + font-weight: normal; + content: $glyph; + } +} + +@include define-emoji("women-holding-hands", "👭"); +=== +@mixin define-emoji($name, $glyph) + span.emoji-#{$name} + font-family: IconFont + font-variant: normal + font-weight: normal + content: $glyph + + + +@include define-emoji("women-holding-hands", "👭") +{% 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. +{% 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][]. + +[`@at-root` rule]: at-rules/at-root +[selector functions]: modules/selector +{% endmarkdown %} diff --git a/source/documentation/style-rules/index.md b/source/documentation/style-rules/index.md deleted file mode 100644 index e69de29..0000000 diff --git a/source/documentation/syntax/comments.liquid b/source/documentation/syntax/comments.liquid new file mode 100644 index 0000000..df12540 --- /dev/null +++ b/source/documentation/syntax/comments.liquid @@ -0,0 +1,140 @@ +--- +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. +--- +{% markdown %} +## In SCSS + +Comments in SCSS work similarly to comments in other languages like JavaScript. +**Single-line comments** start with `//`, and go until the end of the line. +Nothing in a single-line comment is emitted as CSS; as far as Sass is concerned, +they may as well not exist. They're also called **silent comments**, because +they don't produce any CSS. + +**Multi-line comments** start with `/*` and end at the next `*/`. If a +multi-line comment is written somewhere that a [statement][] is allowed, it's +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. + +[statement]: structure#statements +[interpolation]: ../interpolation +[compressed mode]: ../cli/dart-sass#style +{% endmarkdown %} + +{% 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} */ + +/*! This comment will be included even in compressed mode. */ + +p /* Multi-line comments can be written anywhere + * whitespace is allowed. */ .sans { + font: Helvetica, // So can single-line comments. + sans-serif; +} +{% endcodeExample %} + +{% markdown %} +## In Sass + +Comments in the indented syntax work a little differently: they're +indentation-based, just like the rest of the syntax. Like SCSS, silent comments +written with `//` are never emitted as CSS, but unlike SCSS everything indented +beneath the opening `//` is also commented out. + +Indented syntax comments that start with `/*` work with indentation the same +way, except that they are compiled to CSS. Because the extent of the comment is +based on indentation, the closing `*/` is optional. Also like SCSS, `/*` +comments can contain [interpolation][] and can start with `/*!` to avoid being +stripped in compressed mode. + +Comments can also be used within [expressions][] in the indented syntax. In this +case, they have exactly the same syntax as they do in SCSS. + +[expressions]: structure#expressions +{% endmarkdown %} + +{% codeExample 'sass-comment', , true, 'sass'%} +// This comment won't be included in the CSS. + This is also commented out. + +/* But this comment will, except in compressed mode. + +/* It can also contain interpolation: + 1 + 1 = #{1 + 1} + +/*! This comment will be included even in compressed mode. + +p .sans + font: Helvetica, /* Inline comments must be closed. */ sans-serif +{% endcodeExample %} + +{% markdown %} +## Documentation Comments + +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! + +[mixins]: ../at-rules/mixin +[functions]: ../at-rules/function +[variables]: ../variables +[placeholder selectors]: ../style-rules/placeholder-selectors +[SassDoc]: http://sassdoc.com +[susy]: http://oddbird.net/susy/docs/index.html + +Documentation comments are silent comments, written with three slashes (`///`) +directly above the thing you're documenting. SassDoc parses text in the comments +as [Markdown][], and supports many useful [annotations][] to describe it in +detail. + +[Markdown]: https://www.markdownguide.org/getting-started +[annotations]: http://sassdoc.com/annotations/ +{% endmarkdown %} + +{% codeExample 'documentation-comment', , false%} +/// Computes an exponent. +/// +/// @param {number} $base +/// The number to multiply by itself. +/// @param {integer (unitless)} $exponent +/// The number of `$base`s to multiply together. +/// @return {number} `$base` to the power of `$exponent`. +@function pow($base, $exponent) { + $result: 1; + @for $_ from 1 through $exponent { + $result: $result * $base; + } + @return $result; +} +=== +/// Computes an exponent. +/// +/// @param {number} $base +/// The number to multiply by itself. +/// @param {integer (unitless)} $exponent +/// The number of `$base`s to multiply together. +/// @return {number} `$base` to the power of `$exponent`. +@function pow($base, $exponent) + $result: 1 + @for $_ from 1 through $exponent + $result: $result * $base + + @return $result +{% endcodeExample %} diff --git a/source/documentation/syntax/parsing.md b/source/documentation/syntax/parsing.md index 12e44f0..8075d0e 100644 --- a/source/documentation/syntax/parsing.md +++ b/source/documentation/syntax/parsing.md @@ -9,23 +9,23 @@ introduction: > {% # Arguments are (in order): `dart`, `libsass`, `ruby`, optional feature name, additional details within %} {% compatibility false, true, 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 %} 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 @@ -35,7 +35,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. diff --git a/source/documentation/syntax/structure.md b/source/documentation/syntax/structure.md index d0796aa..e69a320 100644 --- a/source/documentation/syntax/structure.md +++ b/source/documentation/syntax/structure.md @@ -27,8 +27,8 @@ complementary_content: | ## Statements -A Sass stylesheet is made up of a series of *statements*, which are evaluated in -order to build the resulting CSS. Some statements may have *blocks*, defined +A Sass stylesheet is made up of a series of _statements_, which are evaluated in +order to build the resulting CSS. Some statements may have _blocks_, defined using `{` and `}`, which contain other statements. For example, a style rule is a statement with a block. That block contains other statements, such as property declarations. @@ -41,9 +41,9 @@ newlines. These types of statements can be used anywhere in a Sass stylesheet: -* [Variable declarations](../variables), like `$var: value`. -* [Flow control at-rules](../at-rules/control), like `@if` and `@each`. -* The [`@error`](../at-rules/error), [`@warn`](../at-rules/warn), and +- [Variable declarations](../variables), like `$var: value`. +- [Flow control at-rules](../at-rules/control), like `@if` and `@each`. +- The [`@error`](../at-rules/error), [`@warn`](../at-rules/warn), and [`@debug`](../at-rules/debug) rules. ### CSS Statements @@ -51,35 +51,35 @@ These types of statements can be used anywhere in a Sass stylesheet: These statements produce CSS. They can be used anywhere except within a `@function`: -* [Style rules](../style-rules), like `h1 { /* ... */ }`. -* [CSS at-rules](../at-rules/css), like `@media` and `@font-face`. -* [Mixin uses](../at-rules/mixin) using `@include`. -* The [`@at-root` rule](../at-rules/at-root). +- [Style rules](../style-rules), like `h1 { /* ... */ }`. +- [CSS at-rules](../at-rules/css), like `@media` and `@font-face`. +- [Mixin uses](../at-rules/mixin) using `@include`. +- The [`@at-root` rule](../at-rules/at-root). ### Top-Level Statements These statements can only be used at the top level of a stylesheet, or nested within a CSS statement at the top level: -* [Module loads](../at-rules/use), using `@use`. -* [Imports](../at-rules/import), using `@import`. -* [Mixin definitions](../at-rules/mixin) using `@mixin`. -* [Function definitions](../at-rules/function) using `@function`. +- [Module loads](../at-rules/use), using `@use`. +- [Imports](../at-rules/import), using `@import`. +- [Mixin definitions](../at-rules/mixin) using `@mixin`. +- [Function definitions](../at-rules/function) using `@function`. ### Other Statements -* [Property declarations](../style-rules/declarations) like `width: 100px` may +- [Property declarations](../style-rules/declarations) like `width: 100px` may only be used within style rules and some CSS at-rules. -* The [`@extend` rule](../at-rules/extend) may only be used within style rules. +- The [`@extend` rule](../at-rules/extend) may only be used within style rules. ## Expressions -An *expression* is anything that goes on the right-hand side of a property or -variable declaration. Each expression produces a *[value][]*. Any valid CSS property +An _expression_ is anything that goes on the right-hand side of a property or +variable declaration. Each expression produces a _[value][]_. Any valid CSS property value is also a Sass expression, but Sass expressions are much more powerful than plain CSS values. They're passed as arguments to [mixins][] and [functions][], used for control flow with the [`@if` rule][], and manipulated using -[arithmetic][]. We call Sass's expression syntax *SassScript*. +[arithmetic][]. We call Sass's expression syntax _SassScript_. [value]: ../values [mixins]: ../at-rules/mixin @@ -91,18 +91,18 @@ than plain CSS values. They're passed as arguments to [mixins][] and The simplest expressions just represent static values: -* [Numbers](../values/numbers), which may or may not have units, like `12` or +- [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 +- [Strings](../values/strings), which may or may not have quotes, like `"Helvetica Neue"` or `bold`. -* [Colors](../values/colors), which can be referred to by their hex +- [Colors](../values/colors), which can be referred to by their hex representation or by name, like `#c6538c` or `blue`. -* The [boolean](../values/booleans) literals `true` or `false`. -* The singleton [`null`](../values/null). -* [Lists of values](../values/lists), which may be separated by spaces or commas +- The [boolean](../values/booleans) literals `true` or `false`. +- The singleton [`null`](../values/null). +- [Lists of values](../values/lists), which may be separated by spaces or commas and which may be enclosed in square brackets or no brackets at all, like `1.5em 1em 0 2em`, `Helvetica, Arial, sans-serif`, or `[col1-start]`. -* [Maps](../values/maps) that associate values with keys, like +- [Maps](../values/maps) that associate values with keys, like `("background": red, "foreground": pink)`. ### Operations @@ -113,12 +113,12 @@ Sass defines syntax for a number of operations: ### Other Expressions -* [Variables](../variables), like `$var`. -* [Function calls](../at-rules/function), like `nth($list, 1)` or +- [Variables](../variables), like `$var`. +- [Function calls](../at-rules/function), like `nth($list, 1)` or `var(--main-bg-color)`, which may call Sass core library functions or user-defined functions, or which may be compiled directly to CSS. -* [Special functions](special-functions), like `calc(1px + 100%)` or +- [Special functions](special-functions), like `calc(1px + 100%)` or `url(http://myapp.com/assets/logo.png)`, that have their own unique parsing rules. -* [The parent selector](../style-rules/parent-selector), `&`. -* The value `!important`, which is parsed as an unquoted string. +- [The parent selector](../style-rules/parent-selector), `&`. +- The value `!important`, which is parsed as an unquoted string. diff --git a/source/helpers/engines.ts b/source/helpers/engines.ts index 29726ee..f3333fc 100644 --- a/source/helpers/engines.ts +++ b/source/helpers/engines.ts @@ -21,7 +21,7 @@ export const markdownEngine = markdown({ .use(markdownDefList) .use(markdownItAttrs) .use(markdownAnchor, { - level: [2,3], + level: [2, 3], permalink: renderPermalink, });