Merge pull request #55 from oddbird/port-docs-atrules-error-warn-debu…

…g-atroot

Porting documentation - At-Rules - @error, @warn, @debug, @at-root, Flow Control, From CSS

source/_includes/compatibility.liquid

@@ -34,6 +34,6 @@
 
 {%- if details | strip -%}
   <div class="sl-c-callout sl-c-callout--impl-status">
-    {{ details | markdown }}
+    {% if useMarkdown %}{{ details | markdown }}{% else %}{{ details }}{% endif %}
   </div>
 {%- endif -%}

source/code-snippets/example-each-list.liquid

@@ -0,0 +1,19 @@
+{% codeExample 'each-list' %}
+$sizes: 40px, 50px, 80px;
+
+@each $size in $sizes {
+  .icon-#{$size} {
+    font-size: $size;
+    height: $size;
+    width: $size;
+  }
+}
+===
+$sizes: 40px, 50px, 80px
+
+@each $size in $sizes
+  .icon-#{$size}
+    font-size: $size
+    height: $size
+    width: $size
+{% endcodeExample %}

source/code-snippets/example-each-map.liquid

@@ -0,0 +1,19 @@
+{% codeExample 'each-map' %}
+$icons: ("eye": "\f112", "start": "\f12e", "stop": "\f12f");
+
+@each $name, $glyph in $icons {
+  .icon-#{$name}:before {
+    display: inline-block;
+    font-family: "Icon Font";
+    content: $glyph;
+  }
+}
+===
+$icons: ("eye": "\f112", "start": "\f12e", "stop": "\f12f")
+
+@each $name, $glyph in $icons
+  .icon-#{$name}:before
+    display: inline-block
+    font-family: "Icon Font"
+    content: $glyph
+{% endcodeExample %}

source/code-snippets/example-if.liquid

@@ -0,0 +1,29 @@
+{% codeExample 'example-if' %}
+@mixin avatar($size, $circle: false) {
+  width: $size;
+  height: $size;
+
+  @if $circle {
+    border-radius: $size / 2;
+  }
+}
+
+.square-av {
+  @include avatar(100px, $circle: false);
+}
+.circle-av {
+  @include avatar(100px, $circle: true);
+}
+===
+@mixin avatar($size, $circle: false)
+  width: $size
+  height: $size
+
+  @if $circle
+    border-radius: $size / 2
+
+.square-av
+  @include avatar(100px, $circle: false)
+.circle-av
+  @include avatar(100px, $circle: true)
+{% endcodeExample %}

source/documentation/at-rules/at-root.liquid

@@ -0,0 +1,79 @@
+---
+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](/documentation/style-rules/parent-selector#advanced-nesting) with the
+  [SassScript parent
+  selector](/documentation/style-rules/parent-selector#in-sassscript) and
+  [selector functions](/documentation/modules/selector).
+---
+
+{% render 'code-snippets/example-advanced-nesting' %}
+
+{% markdown %}
+The `@at-root` rule is necessary here because Sass doesn't know what
+interpolation was used to generate a selector when it's performing selector
+nesting. This means it will automatically add the outer selector to the inner
+selector *even if* you used `&` as a SassScript expression. The `@at-root`
+explicitly tells Sass not to include the outer selector.
+
+{% funFact %}
+The `@at-root` rule can also be written `@at-root { ... }` to put multiple style
+rules at the root of the document. In fact, `@at-root <selector> { ... }` is
+just a shorthand for `@at-root { <selector> { ... } }`!
+{% endfunFact %}
+
+## Beyond Style Rules
+
+On its own, `@at-root` only gets rid of [style rules][]. Any at-rules like
+[`@media`][] or [`@supports`][] will be left in. If this isn't what you want,
+though, you can control exactly what it includes or excludes using syntax like
+[media query features][], written `@at-root (with: <rules...>) { ... }` or
+`@at-root (without: <rules...>) { ... }`. The `(without: ...)` query tells Sass
+which rules should be excluded; the `(with: ...)` query excludes all rules
+*except* those that are listed.
+
+[style rules]: /documentation/style-rules
+[`@media`]: /documentation/at-rules/css#media
+[`@supports`]: /documentation/at-rules/css#supports
+[media query features]: https://developer.mozilla.org/en-US/docs/Web/CSS/Media_Queries/Using_media_queries#Targeting_media_features
+{% endmarkdown %}
+
+{% codeExample 'at-root' %}
+@media print {
+  .page {
+    width: 8in;
+
+    @at-root (without: media) {
+      color: #111;
+    }
+
+    @at-root (with: rule) {
+      font-size: 1.2em;
+    }
+  }
+}
+===
+@media print
+  .page
+    width: 8in
+
+    @at-root (without: media)
+      color: #111
+
+
+    @at-root (with: rule)
+      font-size: 1.2em
+{% endcodeExample %}
+
+{% markdown %}
+In addition to the names of at-rules, there are two special values that can be
+used in queries:
+
+* `rule` refers to style rules. For example, `@at-root (with: rule)` excludes
+  all at-rules but preserves style rules.
+
+* `all` refers to all at-rules *and* style rules should be excluded.
+{% endmarkdown %}

source/documentation/at-rules/control/each.liquid

@@ -0,0 +1,73 @@
+---
+title: "@each"
+introduction: >
+  The `@each` rule makes it easy to emit styles or evaluate code for each
+  element of a [list](/documentation/values/lists) or each pair in a
+  [map](/documentation/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](/documentation/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.
+---
+
+{% render 'code-snippets/example-each-list' %}
+
+{% markdown %}
+## With Maps
+
+You can also use `@each` to iterate over every key/value pair in a map by
+writing it `@each <variable>, <variable> in <expression> { ... }`. The key is
+assigned to the first variable name, and the element is assigned to the second.
+{% endmarkdown %}
+
+{% render 'code-snippets/example-each-map' %}
+
+{% markdown %}
+## Destructuring
+
+If you have a list of lists, you can use `@each` to automatically assign
+variables to each of the values from the inner lists by writing it
+`@each <variable...> in <expression> { ... }`. This is known as *destructuring*,
+since the variables match the structure of the inner lists. Each variable name
+is assigned to the value at the corresponding position in the list, or
+[`null`][] if the list doesn't have enough values.
+
+[`null`]: /documentation/values/null
+{% endmarkdown %}
+
+{% codeExample 'each' %}
+$icons:
+  "eye" "\f112" 12px,
+  "start" "\f12e" 16px,
+  "stop" "\f12f" 10px;
+
+@each $name, $glyph, $size in $icons {
+  .icon-#{$name}:before {
+    display: inline-block;
+    font-family: "Icon Font";
+    content: $glyph;
+    font-size: $size;
+  }
+}
+===
+$icons: "eye" "\f112" 12px, "start" "\f12e" 16px, "stop" "\f12f" 10px
+
+
+
+
+@each $name, $glyph, $size in $icons
+  .icon-#{$name}:before
+    display: inline-block
+    font-family: "Icon Font"
+    content: $glyph
+    font-size: $size
+{% endcodeExample %}
+
+{% funFact %}
+Because `@each` supports destructuring and [maps count as lists of lists][],
+`@each`'s map support works without needing special support for maps in
+particular.
+
+[maps count as lists of lists]: /documentation/values/maps
+{% endfunFact %}

source/documentation/at-rules/control/for.liquid

@@ -0,0 +1,27 @@
+---
+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](/documentation/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.
+---
+
+{% codeExample 'for' %}
+$base-color: #036;
+
+@for $i from 1 through 3 {
+  ul:nth-child(3n + #{$i}) {
+    background-color: lighten($base-color, $i * 5%);
+  }
+}
+===
+$base-color: #036
+
+@for $i from 1 through 3
+  ul:nth-child(3n + #{$i})
+    background-color: lighten($base-color, $i * 5%)
+{% endcodeExample %}