Add documentation for how to silence deprecations (#1104)

Author: nex3

source/_includes/silencing_deprecations.liquid

@@ -0,0 +1,63 @@
+## Can I Silence the Warnings?
+
+Sass provides a powerful suite of options for managing which deprecation
+warnings you see and when.
+
+### Terse and Verbose Mode
+
+By default, Sass runs in terse mode, where it will only print each type of
+deprecation warning five times before it silences additional warnings. This
+helps ensure that users know when they need to be aware of an upcoming breaking
+change without creating an overwhelming amount of console noise.
+
+If you run Sass in verbose mode instead, it will print *every* deprecation
+warning it encounters. This can be useful for tracking the remaining work to be
+done when fixing deprecations. You can enable verbose mode using the
+[`--verbose` flag] on the command line, or the [`verbose` option] in the
+JavaScript API.
+
+[`--verbose` flag]: /documentation/cli/dart-sass/#verbose
+[`verbose` option]: /documentation/js-api/interfaces/Options/#verbose
+
+{% headsUp %}
+  When running from the [JS API], Sass doesn't share any information across
+  compilations, so by default it'll print five warnings for *each stylesheet*
+  that's compiled. However, you can fix this by writing (or asking the author of
+  your favorite framework's Sass plugin to write) a [custom `Logger`] that only
+  prints five errors per deprecation and can be shared across multiple
+  compilations.
+
+  [JS API]: /documentation/js-api/
+  [custom `Logger`]: https://sass-lang.com/documentation/js-api/interfaces/Logger-1/
+{% endheadsUp %}
+
+### Silencing Deprecations in Dependencies
+
+Sometimes, your dependencies have deprecation warnings that you can't do
+anything about. You can silence deprecation warnings from dependencies while
+still printing them for your app using the [`--quiet-deps` flag] on the command
+line, or the [`quietDeps` option] in the JavaScript API.
+
+[`--quiet-deps` flag]: /documentation/cli/dart-sass/#quiet-deps
+[`quietDeps` option]: /documentation/js-api/interfaces/Options/#quietDeps
+
+For the purposes of this flag, a "dependency" is any stylesheet that's not just
+a series of relative loads from the entrypoint stylesheet. This means anything
+that comes from a load path, and most stylesheets loaded through custom
+importers.
+
+### Silencing Specific Deprecations
+
+If you know that one particular deprecation isn't a problem for you, you can
+silence warnings for that specific deprecation using the
+[`--silence-deprecation` flag] on the command line, or the [`silenceDeprecations`
+option] in the JavaScript API.
+
+[`--silence-deprecation` flag]: /documentation/cli/dart-sass/#silence-deprecation
+[`silenceDeprecations` option]: /documentation/js-api/interfaces/Options/#silenceDeprecations
+
+{% headsUp %}
+  This option is only available in the [modern JS API].
+
+  [modern JS API]: /documentation/js-api/#md:usage
+{% endheadsUp %}

source/documentation/breaking-changes/abs-percent.md

@@ -19,3 +19,4 @@ return `-10%` which in the browser would be `50px`.
 For this reason, we are deprecating the global abs() function with a percentage.
 To preserve the current behavior, use `math.abs()` instead.
 
+{% render 'silencing_deprecations' %}

source/documentation/breaking-changes/bogus-combinators.md

@@ -61,3 +61,5 @@ invalid CSS from the compiled CSS, with one exception: we _won't_ omit selectors
 that begin with a leading combinator, since they may be used from a nested
 `@import` rule or `meta.load-css()` mixin. However, we don't encourage this
 pattern and will drop support for it in Dart Sass 2.0.0.
+
+{% render 'silencing_deprecations' %}

source/documentation/breaking-changes/css-function-mixin.md

@@ -38,3 +38,5 @@ deprecation warning named `css-function-mixin`.
 Between Dart Sass 2.0.0 and the release of Dart Sass's support for plain CSS
 functions and mixins, functions and mixins will not be allowed to have names
 that begin with `--`.
+
+{% render 'silencing_deprecations' %}

source/documentation/breaking-changes/duplicate-var-flags.md

@@ -21,3 +21,5 @@ each `!global` or `!default` flag, this will be a syntax error. This means that
 
 Until Dart Sass 2.0.0 is released, multiple copies of a flag just produce
 deprecation warnings.
+
+{% render 'silencing_deprecations' %}

source/documentation/breaking-changes/function-units.md

@@ -211,3 +211,5 @@ units or with units other than `%` to `color.mix()` or `color.invert()`.
 
 In Dart Sass 2.0.0, `list.nth()` and `list.set-nth()` will throw errors if
 they're passed an index `$n` with a unit.
+
+{% render 'silencing_deprecations' %}

source/documentation/breaking-changes/media-logic.md

@@ -28,3 +28,5 @@ Fortunately, these came up very infrequently in practice.
 First, we emitted deprecation warnings for the previous ambiguous cases. These
 will have suggestions for how to preserve the existing behavior or how to use
 the new CSS syntax.
+
+{% render 'silencing_deprecations' %}

source/documentation/breaking-changes/mixed-decls.md

@@ -116,3 +116,5 @@ declarations in `& {}`:
     &
       font-weight: normal
 {% endcodeExample %}
+
+{% render 'silencing_deprecations' %}

source/documentation/breaking-changes/moz-document.md

@@ -35,3 +35,5 @@ First, we'll emit deprecation warnings for all usages of `@-moz-document` except
 for the empty url-prefix hack.
 
 In Dart Sass 2.0, `@-moz-document` will be treated as an unknown at-rule.
+
+{% render 'silencing_deprecations' %}

source/documentation/breaking-changes/slash-div.md

@@ -131,3 +131,5 @@ use `math.div()` and `list.slash()`.
 $ npm install -g sass-migrator
 $ sass-migrator division **/*.scss
 ```
+
+{% render 'silencing_deprecations' %}

source/documentation/breaking-changes/strict-unary.md

@@ -62,3 +62,5 @@ existing behavior of these stylesheets.
 $ npm install -g sass-migrator
 $ sass-migrator strict-unary **/*.scss
 ```
+
+{% render 'silencing_deprecations' %}

source/documentation/cli/dart-sass.md

@@ -429,6 +429,16 @@ Error: Incompatible units em and px.
   test.scss 1:9  root stylesheet
 ```
 
+#### `--verbose`
+
+This flag tells Sass to emit _all_ deprecation warnings when compiling. By
+default, Sass only emits five warnings for a given deprecation type when
+deprecated features are used, and silences any warnings beyond that.
+
+```shellsession
+$ sass --verbose style.scss style.css
+```
+
 #### `--quiet`
 
 This flag (abbreviated `-q`) tells Sass not to emit any warnings when compiling.