Starting to port documentation

2024-11-30 04:29:17 +01:00 · 2023-05-07 18:58:40 +02:00 · 2023-05-07 18:58:40 +02:00 · 387dab1129
commit 387dab1129
parent 2270dd2e9b
15 changed files with 593 additions and 16 deletions
--- a/source/_includes/compatibility.liquid
+++ b/source/_includes/compatibility.liquid
@ -2,34 +2,29 @@
  <div class="compatibility">
    Compatibility{% if feature %} ({{ feature }}){% endif %}:
  </div>
-  {% if dart != null %}
+  {%- if dart != null -%}
    <div>
      <dt>Dart Sass</dt>
      <dd>{{ dart | implStatus }}</dd>
    </div>
-  {% endif %}
-  {% if libsass != null %}
+  {%- endif -%}
+  {%- if libsass != null -%}
    <div>
      <dt>LibSass</dt>
      <dd>{{ libsass | implStatus }}</dd>
    </div>
-  {% endif %}
-  {% if ruby != null %}
+  {%- endif -%}
+  {%- if ruby != null -%}
    <div>
      <dt>Ruby Sass</dt>
      <dd>{{ ruby | implStatus }}</dd>
    </div>
-  {% endif %}
-  {% if details %}
-    <div>
-      {% # The no-op href here ensures that this toggle is focusable in browsers. %}
-      <a href="javascript:;">▶</a>
-    </div>
-  {% endif %}
+  {%- endif -%}
+  {%- if details -%}
+    <div>{% # The no-op href here ensures that this toggle is focusable in browsers. %}<a href="javascript:;">▶</a></div>
+  {%- endif -%}
 </dl>

 {% if details %}
-  <div class="sl-c-callout sl-c-callout--impl-status">
-    {{ details | markdown }}
-  </div>
+  <div class="sl-c-callout sl-c-callout--impl-status">{{ details | markdown }}</div>
 {% endif %}
--- a/source/_includes/heads_up.liquid
+++ b/source/_includes/heads_up.liquid
@ -0,0 +1,4 @@
+<div class="sl-c-callout sl-c-callout--warning">
+  <h3>⚠️ Heads up!</h3>
+  {{ contents | markdown }}
+</div>
--- a/source/documentation/documentation.11tydata.yml
+++ b/source/documentation/documentation.11tydata.yml
@ -0,0 +1,84 @@
+layout: has_both_sidebars
+navigation: |
+  <div class="sl-c-list-navigation-wrapper sl-c-list-navigation-wrapper--collapsible">
+
+  <h2>Contents</h2>
+
+  - [Syntax](/documentation/syntax){.section}
+    - [Overview](/documentation/syntax)
+    - [Parsing a Stylesheet](/documentation/syntax/parsing)
+    - [Structure of a Stylesheet](/documentation/syntax/structure)
+    - [Comments](/documentation/syntax/comments)
+    - [Special Functions](/documentation/syntax/special-functions)
+  - [Style Rules](/documentation/style-rules){.section}
+    - [Overview](/documentation/style-rules)
+    - [Property Declarations](/documentation/style-rules/declarations)
+    - [Parent Selector](/documentation/style-rules/parent-selector)
+    - [Placeholder Selectors](/documentation/style-rules/placeholder-selectors)
+  - [Variables](/documentation/variables)
+  - [Interpolation](/documentation/interpolation)
+  - [At-Rules](/documentation/at-rules){.section}
+    - [Overview](/documentation/at-rules)
+    - [<code>@use</code>](/documentation/at-rules/use)
+    - [<code>@forward</code>](/documentation/at-rules/forward)
+    - [<code>@import</code>](/documentation/at-rules/import)
+    - [<code>@mixin</code> and <code>@include</code>](/documentation/at-rules/mixin)
+    - [<code>@function</code>](/documentation/at-rules/function)
+    - [<code>@extend</code>](/documentation/at-rules/extend)
+    - [<code>@error</code>](/documentation/at-rules/error)
+    - [<code>@warn</code>](/documentation/at-rules/warn)
+    - [<code>@debug</code>](/documentation/at-rules/debug)
+    - [<code>@at-root</code>](/documentation/at-rules/at-root)
+    - [Flow Control](/documentation/at-rules/control)
+        - [Overview](/documentation/at-rules/control)
+        - [<code>@if</code> and <code>@else</code>](/documentation/at-rules/control/if)
+        - [<code>@each</code>](/documentation/at-rules/control/each)
+        - [<code>@for</code>](/documentation/at-rules/control/for)
+        - [<code>@while</code>](/documentation/at-rules/control/while)
+    - [From CSS](/documentation/at-rules/css)
+  - [Values](/documentation/values){.section}
+    - [Overview](/documentation/values)
+    - [Numbers](/documentation/values/numbers)
+    - [Strings](/documentation/values/strings)
+    - [Colors](/documentation/values/colors)
+    - [Lists](/documentation/values/lists)
+    - [Maps](/documentation/values/maps)
+    - [<code>true</code> and <code>false</code>](/documentation/values/booleans)
+    - [<code>null</code>](/documentation/values/null)
+    - [Calculations](/documentation/values/calculations)
+    - [Functions](/documentation/values/functions)
+  - [Operators](/documentation/operators){.section}
+    - [Overview](/documentation/operators)
+    - [Equality](/documentation/operators/equality)
+    - [Relational](/documentation/operators/relational)
+    - [Numeric](/documentation/operators/numeric)
+    - [String](/documentation/operators/string)
+    - [Boolean](/documentation/operators/boolean)
+  - [Built-In Modules](/documentation/modules){.section}
+    - [Overview](/documentation/modules)
+    - [<code>sass:color</code>](/documentation/modules/color)
+    - [<code>sass:list</code>](/documentation/modules/list)
+    - [<code>sass:map</code>](/documentation/modules/map)
+    - [<code>sass:math</code>](/documentation/modules/math)
+    - [<code>sass:meta</code>](/documentation/modules/meta)
+    - [<code>sass:selector</code>](/documentation/modules/selector)
+    - [<code>sass:string</code>](/documentation/modules/string)
+  - [Breaking Changes](/documentation/breaking-changes){.section}
+    - [Overview](/documentation/breaking-changes)
+    - [Strict Unary Operators](/documentation/breaking-changes/strict-unary)
+    - [Random With Units](/documentation/breaking-changes/random-with-units)
+    - [Invalid Combinators](/documentation/breaking-changes/bogus-combinators)
+    - [Media Queries Level 4](/documentation/breaking-changes/media-logic)
+    - [<code>/</code> as Division](/documentation/breaking-changes/slash-div)
+    - [Function Units](/documentation/breaking-changes/function-units)
+    - [<code>-moz-document</code>](/documentation/breaking-changes/moz-document)
+    - [Extending Compound Selectors](/documentation/breaking-changes/extend-compound)
+    - [CSS Variable Syntax](/documentation/breaking-changes/css-vars)
+  - [Command Line](/documentation/cli){.section}
+    - [Overview](/documentation/cli)
+    - [Dart Sass](/documentation/cli/dart-sass)
+    - [Ruby Sass](/documentation/cli/ruby-sass)
+    - [Migrator](/documentation/cli/migrator)
+  - [Javascript API](/documentation/js-api)
+
+  </div>
--- a/source/documentation/index.md
+++ b/source/documentation/index.md
@ -0,0 +1,57 @@
+---
+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/modules), 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.
+---
+
+- If you're looking for an introduction to Sass, check out [the
+  tutorial](/guide).
+
+- If you want to look up a built-in Sass function, look no further than [the
+  built-in module reference](/documentation/modules).
+
+- If you're calling Sass from JavaScript, you may want the [JS API
+  documentation][js].
+
+- Or the [Dart API documentation][dart] if you're calling it from Dart.
+
+- Otherwise, use the table of contents for the language reference!
+
+[js]: https://github.com/sass/node-sass#usage
+[dart]: https://pub.dartlang.org/documentation/sass/latest/sass/sass-library.html
+
+## Older Versions
+
+This documentation is written for the most recent version of the Sass language.
+If you're using [Dart Sass] <%= impl_version(:dart) %>, you'll have access to
+all the features described here. But if you're using an older version of Dart
+Sass or a deprecated Sass implementation like [LibSass] or [Ruby Sass], there
+may be some behavioral differences.
+
+[Dart Sass]: /dart-sass
+[LibSass]: /libsass
+[Ruby Sass]: /ruby-sass
+
+Anywhere behavior differs between versions or implementations, the documentation
+includes a compatibility indicator like this:
+
+{% compatibility true, '3.6.0', false, 'Feature Name'%}{% endcompatibility %}
+
+Implementations with a "✓" fully support the feature in question, and
+implementations with a "✗" don't support it all. Implementations with a version
+number started supporting the feature in question at that version.
+Implementations can also be marked as "partial":
+
+{% # Arguments are (in order): `dart`, `libsass`, `ruby`, optional feature name, additional details within %}
+{% compatibility true, 'partial', false%}Additional details go here.{% endcompatibility %}
+
+This indicates that the implementation only supports some aspects of the
+feature. These compatibility indicators (and many others) have a "▶" button,
+which can be clicked to show more details about exactly how the implementations
+differ and which versions support which aspects of the feature in question.
--- a/source/documentation/snippets/operator-list.liquid
+++ b/source/documentation/snippets/operator-list.liquid
@ -0,0 +1,16 @@
+* [`==` and `!=`](/documentation/operators/equality) are used to check if two
+  values are the same.
+* [`+`, `-`, `*`, `/`, and `%`](/documentation/operators/numeric) have their
+  usual mathematical meaning for numbers, with special behaviors for units that
+  matches the use of units in scientific math.
+* [`<`, `<=`, `>`, and `>=`](/documentation/operators/relational) check whether
+  two numbers are greater or less than one another.
+* [`and`, `or`, and `not`](/documentation/operators/boolean) have the usual
+  boolean behavior. Sass considers every value "true" except for `false` and
+  `null`.
+* [`+`, `-`, and `/`](/documentation/operators/string) can be used to
+  concatenate strings.
+{% if parens %}
+* [`(` and `)`](/documentation/operators#parentheses) can be used to explicitly
+  control the precedence order of operations.
+{% endif %}
--- a/source/documentation/style-rules/declarations.md
+++ b/source/documentation/style-rules/declarations.md
--- a/source/documentation/style-rules/index.md
+++ b/source/documentation/style-rules/index.md
--- a/source/documentation/style-rules/parent-selector.md
+++ b/source/documentation/style-rules/parent-selector.md
--- a/source/documentation/style-rules/placeholder-selectors.md
+++ b/source/documentation/style-rules/placeholder-selectors.md
--- a/source/documentation/syntax/index.md
+++ b/source/documentation/syntax/index.md
@ -0,0 +1,83 @@
+---
+title: Syntax
+introduction: >
+  Sass supports two different syntaxes. Each one can load the other, so it's
+  up to you and your team which one to choose.
+---
+
+## SCSS
+
+The SCSS syntax uses the file extension `.scss`. With a few small exceptions,
+it's a superset of CSS, which means essentially **all valid CSS is valid SCSS as
+well**. Because of its similarity to CSS, it's the easiest syntax to get used to
+and the most popular.
+
+SCSS looks like this:
+
+```scss
+@mixin button-base() {
+  @include typography(button);
+  @include ripple-surface;
+  @include ripple-radius-bounded;
+
+  display: inline-flex;
+  position: relative;
+  height: $button-height;
+  border: none;
+  vertical-align: middle;
+
+  &:hover {
+    cursor: pointer;
+  }
+
+  &:disabled {
+    color: $mdc-button-disabled-ink-color;
+    cursor: default;
+    pointer-events: none;
+  }
+}
+```
+
+## The Indented Syntax
+
+The indented syntax was Sass's original syntax, and so it uses the file
+extension `.sass`. Because of this extension, it's sometimes just called "Sass".
+The indented syntax supports all the same features as SCSS, but it uses
+indentation instead of curly braces and semicolons to describe the format of the
+document.
+
+In general, any time you'd write curly braces in CSS or SCSS, you can just
+indent one level deeper in the indented syntax. And any time a line ends, that
+counts as a semicolon. There are also a few additional differences in the
+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].
+
+[issue 216]: https://github.com/sass/sass/issues/216
+
+{% endheadsUp %}
+
+The indented syntax looks like this:
+
+```sass
+@mixin button-base()
+  @include typography(button)
+  @include ripple-surface
+  @include ripple-radius-bounded
+
+  display: inline-flex
+  position: relative
+  height: $button-height
+  border: none
+  vertical-align: middle
+
+  &:hover
+    cursor: pointer
+
+  &:disabled
+    color: $mdc-button-disabled-ink-color
+    cursor: default
+    pointer-events: none
+```
--- a/source/documentation/syntax/parsing.md
+++ b/source/documentation/syntax/parsing.md
@ -0,0 +1,48 @@
+---
+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.
+---
+
+## Input Encoding
+
+{% # 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.
+{% 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
+  BYTE ORDER MARK, the corresponding encoding is used.
+
+* 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.
+
+## Parse Errors
+
+When Sass encounters invalid syntax in a stylesheet, parsing will fail and an
+error will be presented to the user with information about the location of the
+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
+to see errors immediately, rather than having them passed through to the CSS
+output.
+
+The location of parse errors can be accessed through implementation-specific
+APIs. For example, in Dart Sass you can access [`SassException.span`][], and in
+Node Sass's and Dart Sass's JS API you can access the [`file`, `line`, and
+`column`][js error] properties.
+
+[`SassException.span`]: https://pub.dartlang.org/documentation/sass/latest/sass/SassException/span.html
+[js error]: https://github.com/sass/node-sass#error-object
--- a/source/documentation/syntax/special-functions.liquid
+++ b/source/documentation/syntax/special-functions.liquid
@ -0,0 +1,156 @@
+---
+title: Special Functions
+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](../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](structure#expressions). All
+  special function calls return [unquoted strings](../values/strings#unquoted).
+table_of_contents: true
+complementary_content: |
+  <nav aria-labelledby="page-sections" class="page-sections sl-c-list-navigation-wrapper sl-c-list-navigation-wrapper--collapsible">
+
+  <h3 id="page-sections">Page Sections</h3>
+
+  - [<code>url()</code>](#url())
+  - [<code>element(),</code> <code>progid:...(),</code> and <code>expression()</code>](#element()%2C-progid%3A...()%2C-and-expression())
+
+  </nav>
+---
+{% 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
+unquoted URL isn't a valid SassScript expression, Sass needs special logic to
+parse it.
+
+[`url()` function]: https://developer.mozilla.org/en-US/docs/Web/CSS/url
+
+If the `url()`'s argument is a valid unquoted URL, Sass parses it as-is,
+although [interpolation][] may also be used to inject SassScript values. If it's
+not a valid unquoted URL—for example, if it contains [variables][] or [function
+calls][]—it's parsed as a normal [plain CSS function call][].
+
+[interpolation]: ../interpolation
+[variables]: ../variables
+[function calls]: ../at-rules/function
+[plain CSS function call]: ../at-rules/function#plain-css-functions
+
+{% endmarkdown %}
+
+{% codeExample 'url' %}
+$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");
+
+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");
+
+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");
+
+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")
+
+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")
+
+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")
+
+font-family: "Roboto"
+font-weight: 400
+{% endcodeExample %}
+
+{% markdown %}
+## `element()`, `progid:...()`, and `expression()`
+
+{% # Arguments are (in order): `dart`, `libsass`, `ruby`, optional feature name, additional details within %}
+{% compatibility "<1.40.0", false, false, "calc()" %}
+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].
+
+[calculation]: ../values/calculations
+{% endcompatibility %}
+
+{% compatibility ">=1.31.0 <1.40.0", false, 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.
+
+[plain CSS function]: ../at-rules/function#plain-css-functions
+
+Dart Sass versions between 1.31.0 and 1.40.0 parse `clamp()` as special
+syntactic function like `element()`.
+
+Dart Sass versions 1.40.0 and later parse `clamp()` as a [calculation].
+
+[calculation]: ../values/calculations
+{% endcompatibility %}
+
+The [`element()`] function is defined in the CSS spec, and because its IDs couldbe parsed as colors, they need special parsing.
+
+[`element()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/element
+
+[`expression()`][] and functions beginning with [`progid:`][] are legacy
+Internet Explorer features that use non-standard syntax. Although they're no
+longer supported by recent browsers, Sass continues to parse them for backwards
+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.
+Nothing is interpreted as a SassScript expression, with the exception that
+[interpolation][] can be used to inject dynamic values.
+{% endmarkdown %}
+
+{% codeExample 'element' %}
+$logo-element: logo-bg;
+
+.logo {
+background: element(##{$logo-element});
+}
+===
+$logo-element: logo-bg
+
+.logo
+background: element(##{$logo-element})
+===
+.logo {
+background: element(#logo-bg);
+}
+{% endcodeExample %}
--- a/source/documentation/syntax/structure.md
+++ b/source/documentation/syntax/structure.md
@ -0,0 +1,124 @@
+---
+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.
+complementary_content: |
+  <nav aria-labelledby="page-sections" class="page-sections sl-c-list-navigation-wrapper sl-c-list-navigation-wrapper--collapsible">
+
+  ### Page Sections{#page-sections}
+
+  - [Statements](#statements){.section}
+    - [Overview](#statements)
+    - [Universal Statements](#universal-statements)
+    - [CSS Statements](#css-statements)
+    - [Top-Level Statements](#top-level-statements)
+    - [Other Statements](#other-statements)
+  - [Expressions](#expressions){.section}
+    - [Overview](#expressions)
+    - [Literals](#literals)
+    - [Operations](#operations)
+    - [Other Expressions](#other-expressions)
+
+  </nav>
+---
+
+## 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
+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.
+
+In SCSS, statements are separated by semicolons (which are optional if the
+statement uses a block). In the indented syntax, they're just separated by
+newlines.
+
+### Universal Statements
+
+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
+  [`@debug`](../at-rules/debug) rules.
+
+### CSS Statements
+
+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).
+
+### 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`.
+
+### Other Statements
+
+* [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.
+
+## 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
+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*.
+
+[value]: ../values
+[mixins]: ../at-rules/mixin
+[functions]: ../at-rules/function
+[`@if` rule]: ../at-rules/control/if
+[arithmetic]: ../operators/numeric
+
+### Literals
+
+The simplest expressions just represent static values:
+
+* [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
+  `"Helvetica Neue"` or `bold`.
+* [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
+  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
+  `("background": red, "foreground": pink)`.
+
+### Operations
+
+Sass defines syntax for a number of operations:
+
+{% render 'documentation/snippets/operator-list', parens:true %}
+
+### Other Expressions
+
+* [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
+  `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.
--- a/source/helpers/components/index.ts
+++ b/source/helpers/components/index.ts
@ -17,6 +17,15 @@ export const funFact = async (contents: string) =>
    contents,
  });

+/**
+ * Returns HTML for a heads up warning related to the main
+ * documentation.
+ */
+export const headsUp = async (contents: string) =>
+  liquidEngine.renderFile('heads_up', {
+    contents,
+  });
+
 /**
 * Returns HTML for a code block with syntax highlighting via [Prism][].
 *
@ -55,4 +64,5 @@ export default function componentsPlugin(eleventyConfig: any) {
  // In the meantime, the args are: `dart`, `libsass`, `ruby`, `feature`
  eleventyConfig.addPairedLiquidShortcode('compatibility', compatibility);
  eleventyConfig.addPairedLiquidShortcode('funFact', funFact);
+  eleventyConfig.addPairedLiquidShortcode('headsUp', headsUp);
 }
--- 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],
+    level: [2,3],
    permalink: renderPermalink,
  });