sass 1.62.1 → 1.63.0

package/types/options.d.ts

@@ -32,7 +32,7 @@ export type OutputStyle = 'expanded' | 'compressed';
 
 /**
  * A callback that implements a custom Sass function. This can be passed to
- * [[Options.functions]].
+ * {@link Options.functions}.
  *
  * ```js
  * const result = sass.compile('style.scss', {
@@ -49,21 +49,21 @@ export type OutputStyle = 'expanded' | 'compressed';
  * ```
  *
  * @typeParam sync - A `CustomFunction<'sync'>` must return synchronously, but
- * in return it can be passed to [[compile]] and [[compileString]] in addition
- * to [[compileAsync]] and [[compileStringAsync]].
+ * in return it can be passed to {@link compile} and {@link compileString} in
+ * addition to {@link compileAsync} and {@link compileStringAsync}.
  *
  * A `CustomFunction<'async'>` may either return synchronously or
- * asynchronously, but it can only be used with [[compileAsync]] and
- * [[compileStringAsync]].
+ * asynchronously, but it can only be used with {@link compileAsync} and {@link
+ * compileStringAsync}.
  *
  * @param args - An array of arguments passed by the function's caller. If the
  * function takes [arbitrary
  * arguments](https://sass-lang.com/documentation/at-rules/function#taking-arbitrary-arguments),
- * the last element will be a [[SassArgumentList]].
+ * the last element will be a {@link SassArgumentList}.
  *
  * @returns The function's result. This may be in the form of a `Promise`, but
- * if it is the function may only be passed to [[compileAsync]] and
- * [[compileStringAsync]], not [[compile]] or [[compileString]].
+ * if it is the function may only be passed to {@link compileAsync} and {@link
+ * compileStringAsync}, not {@link compile} or {@link compileString}.
  *
  * @throws any - This function may throw an error, which the Sass compiler will
  * treat as the function call failing. If the exception object has a `message`
@@ -78,12 +78,12 @@ export type CustomFunction<sync extends 'sync' | 'async'> = (
 ) => PromiseOr<Value, sync>;
 
 /**
- * Options that can be passed to [[compile]], [[compileAsync]],
- * [[compileString]], or [[compileStringAsync]].
+ * Options that can be passed to {@link compile}, {@link compileAsync}, {@link
+ * compileString}, or {@link compileStringAsync}.
  *
  * @typeParam sync - This lets the TypeScript checker verify that asynchronous
- * [[Importer]]s, [[FileImporter]]s, and [[CustomFunction]]s aren't passed to
- * [[compile]] or [[compileString]].
+ * {@link Importer}s, {@link FileImporter}s, and {@link CustomFunction}s aren't
+ * passed to {@link compile} or {@link compileString}.
  *
  * @category Options
  */
@@ -127,7 +127,7 @@ export interface Options<sync extends 'sync' | 'async'> {
    * This option takes an object whose keys are Sass function signatures like
    * you'd write for the [`@function
    * rule`](https://sass-lang.com/documentation/at-rules/function) and whose
-   * values are [[CustomFunction]]s.
+   * values are {@link CustomFunction}s.
    *
    * Functions are passed JavaScript representations of [Sass value
    * types](https://sass-lang.com/documentation/js-api#value-types), and must
@@ -137,18 +137,18 @@ export interface Options<sync extends 'sync' | 'async'> {
    * and as close to the standards set by Sass's core functions as possible. Some
    * good guidelines to follow include:
    *
-   * * Use `Value.assert*` methods, like [[Value.assertString]], to cast untyped
-   *   `Value` objects to more specific types. For values that were passed
-   *   directly as arguments, pass in the argument name as well. This ensures
-   *   that the user gets good error messages when they pass in the wrong type
-   *   to your function.
+   * * Use `Value.assert*` methods, like {@link Value.assertString}, to cast
+   *   untyped `Value` objects to more specific types. For values that were
+   *   passed directly as arguments, pass in the argument name as well. This
+   *   ensures that the user gets good error messages when they pass in the
+   *   wrong type to your function.
    *
-   * * Individual classes may have more specific `assert*` methods, like
-   *   [[SassNumber.assertInt]], which should be used when possible.
+   * * Individual classes may have more specific `assert*` methods, like {@link
+   *   SassNumber.assertInt}, which should be used when possible.
    *
    * * In Sass, every value counts as a list. Rather than trying to detect the
-   *   [[SassList]] type, you should use [[Value.asList]] to treat all values as
-   *   lists.
+   *   {@link SassList} type, you should use {@link Value.asList} to treat all
+   *   values as lists.
    *
    * * When manipulating values like lists, strings, and numbers that have
    *   metadata (comma versus space separated, bracketed versus unbracketed,
@@ -160,9 +160,8 @@ export interface Options<sync extends 'sync' | 'async'> {
    *
    * * In Sass, lists and strings use one-based indexing and use negative
    *   indices to index from the end of value. Functions should follow these
-   *   conventions. [[Value.sassIndexToListIndex]] and
-   *   [[SassString.sassIndexToStringIndex]] can be used to do this
-   *   automatically.
+   *   conventions. {@link Value.sassIndexToListIndex} and {@link
+   *   SassString.sassIndexToStringIndex} can be used to do this automatically.
    *
    * * String indexes in Sass refer to Unicode code points while JavaScript
    *   string indices refer to UTF-16 code units. For example, the character
@@ -170,9 +169,9 @@ export interface Options<sync extends 'sync' | 'async'> {
    *   is represented in UTF-16 as two code units (`0xD83D` and `0xDE0A`). So in
    *   JavaScript, `"a😊b".charCodeAt(1)` returns `0xD83D`, whereas in Sass
    *   `str-slice("a😊b", 1, 1)` returns `"😊"`. Functions should follow Sass's
-   *   convention. [[SassString.sassIndexToStringIndex]] can be used to do this
-   *   automatically, and the [[SassString.sassLength]] getter can be used to
-   *   access a string's length in code points.
+   *   convention. {@link SassString.sassIndexToStringIndex} can be used to do
+   *   this automatically, and the {@link SassString.sassLength} getter can be
+   *   used to access a string's length in code points.
    *
    * @example
    *
@@ -209,9 +208,10 @@ export interface Options<sync extends 'sync' | 'async'> {
    * - The importer that was used to load the current stylesheet, with the
    *   loaded URL resolved relative to the current stylesheet's canonical URL.
    *
-   * - Each [[Importer]] or [[FileImporter]] in [[importers]], in order.
+   * - Each {@link Importer} or {@link FileImporter} in {@link importers}, in
+   *   order.
    *
-   * - Each load path in [[loadPaths]], in order.
+   * - Each load path in {@link loadPaths}, in order.
    *
    * If none of these return a Sass file, the load fails and Sass throws an
    * error.
@@ -225,7 +225,7 @@ export interface Options<sync extends 'sync' | 'async'> {
    * [`@use`](https://sass-lang.com/documentation/at-rules/use) and
    * [`@import`](https://sass-lang.com/documentation/at-rules/import).
    *
-   * A load path `loadPath` is equivalent to the following [[FileImporter]]:
+   * A load path `loadPath` is equivalent to the following {@link FileImporter}:
    *
    * ```js
    * {
@@ -245,10 +245,10 @@ export interface Options<sync extends 'sync' | 'async'> {
    * An object to use to handle warnings and/or debug messages from Sass.
    *
    * By default, Sass emits warnings and debug messages to standard error, but
-   * if [[Logger.warn]] or [[Logger.debug]] is set, this will invoke them
-   * instead.
+   * if {@link Logger.warn} or {@link Logger.debug} is set, this will invoke
+   * them instead.
    *
-   * The special value [[Logger.silent]] can be used to easily silence all
+   * The special value {@link Logger.silent} can be used to easily silence all
    * messages.
    *
    * @category Messages
@@ -258,18 +258,18 @@ export interface Options<sync extends 'sync' | 'async'> {
   /**
    * If this option is set to `true`, Sass won’t print warnings that are caused
    * by dependencies. A “dependency” is defined as any file that’s loaded
-   * through [[loadPaths]] or [[importer]]. Stylesheets that are imported
-   * relative to the entrypoint are not considered dependencies.
+   * through {@link loadPaths} or {@link importers}. Stylesheets that are
+   * imported relative to the entrypoint are not considered dependencies.
    *
    * This is useful for silencing deprecation warnings that you can’t fix on
    * your own. However, please <em>also</em> notify your dependencies of the deprecations
    * so that they can get fixed as soon as possible!
    *
-   * **Heads up!** If [[compileString]] or [[compileStringAsync]] is called
-   * without [[StringWithoutImporter.url]], <em>all</em> stylesheets it loads
-   * will be considered dependencies. Since it doesn’t have a path of its own,
-   * everything it loads is coming from a load path rather than a relative
-   * import.
+   * **Heads up!** If {@link compileString} or {@link compileStringAsync} is
+   * called without {@link StringOptionsWithoutImporter.url}, <em>all</em>
+   * stylesheets it loads will be considered dependencies. Since it doesn’t have
+   * a path of its own, everything it loads is coming from a load path rather
+   * than a relative import.
    *
    * @defaultValue `false`
    * @category Messages
@@ -278,7 +278,7 @@ export interface Options<sync extends 'sync' | 'async'> {
 
   /**
    * Whether or not Sass should generate a source map. If it does, the source
-   * map will be available as [[CompileResult.sourceMap]].
+   * map will be available as {@link CompileResult.sourceMap}.
    *
    * **Heads up!** Sass doesn't automatically add a `sourceMappingURL` comment
    * to the generated CSS. It's up to callers to do that, since callers have
@@ -293,7 +293,7 @@ export interface Options<sync extends 'sync' | 'async'> {
   /**
    * Whether Sass should include the sources in the generated source map.
    *
-   * This option has no effect if [[sourceMap]] is `false`.
+   * This option has no effect if {@link sourceMap} is `false`.
    *
    * @defaultValue `false`
    * @category Output
@@ -301,7 +301,7 @@ export interface Options<sync extends 'sync' | 'async'> {
   sourceMapIncludeSources?: boolean;
 
   /**
-   * The [[OutputStyle]] of the compiled CSS.
+   * The {@link OutputStyle} of the compiled CSS.
    *
    * @example
    *
@@ -345,22 +345,23 @@ export interface Options<sync extends 'sync' | 'async'> {
 }
 
 /**
- * Options that can be passed to [[compileString]] or [[compileStringAsync]].
+ * Options that can be passed to {@link compileString} or {@link
+ * compileStringAsync}.
  *
- * If the [[StringOptionsWithImporter.importer]] field isn't passed, the
+ * If the {@link StringOptionsWithImporter.importer} field isn't passed, the
  * entrypoint file can load files relative to itself if a `file://` URL is
- * passed to the [[url]] field.
+ * passed to the {@link url} field.
  *
  * @typeParam sync - This lets the TypeScript checker verify that asynchronous
- * [[Importer]]s, [[FileImporter]]s, and [[CustomFunction]]s aren't passed to
- * [[compile]] or [[compileString]].
+ * {@link Importer}s, {@link FileImporter}s, and {@link CustomFunction}s aren't
+ * passed to {@link compile} or {@link compileString}.
  *
  * @category Options
  */
 export interface StringOptionsWithoutImporter<sync extends 'sync' | 'async'>
   extends Options<sync> {
   /**
-   * The [[Syntax]] to use to parse the entrypoint stylesheet.
+   * The {@link Syntax} to use to parse the entrypoint stylesheet.
    *
    * @default `'scss'`
    *
@@ -371,9 +372,10 @@ export interface StringOptionsWithoutImporter<sync extends 'sync' | 'async'>
   /**
    * The canonical URL of the entrypoint stylesheet.
    *
-   * A relative load's URL is first resolved relative to [[url]], then resolved
-   * to a file on disk if it's a `file://` URL. If it can't be resolved to a
-   * file on disk, it's then passed to [[importers]] and [[loadPaths]].
+   * A relative load's URL is first resolved relative to {@link url}, then
+   * resolved to a file on disk if it's a `file://` URL. If it can't be resolved
+   * to a file on disk, it's then passed to {@link importers} and {@link
+   * loadPaths}.
    *
    * @category Input
    */
@@ -381,15 +383,16 @@ export interface StringOptionsWithoutImporter<sync extends 'sync' | 'async'>
 }
 
 /**
- * Options that can be passed to [[compileString]] or [[compileStringAsync]].
+ * Options that can be passed to {@link compileString} or {@link
+ * compileStringAsync}.
  *
- * If the [[StringOptionsWithImporter.importer]] field is passed, the entrypoint
- * file uses it to load files relative to itself and the [[url]] field is
- * mandatory.
+ * If the {@link StringOptionsWithImporter.importer} field is passed, the
+ * entrypoint file uses it to load files relative to itself and the {@link url}
+ * field is mandatory.
  *
  * @typeParam sync - This lets the TypeScript checker verify that asynchronous
- * [[Importer]]s, [[FileImporter]]s, and [[CustomFunction]]s aren't passed to
- * [[compile]] or [[compileString]].
+ * {@link Importer}s, {@link FileImporter}s, and {@link CustomFunction}s aren't
+ * passed to {@link compile} or {@link compileString}.
  *
  * @category Options
  */
@@ -399,9 +402,9 @@ export interface StringOptionsWithImporter<sync extends 'sync' | 'async'>
    * The importer to use to handle loads that are relative to the entrypoint
    * stylesheet.
    *
-   * A relative load's URL is first resolved relative to [[url]], then passed to
-   * [[importer]]. If the importer doesn't recognize it, it's then passed to
-   * [[importers]] and [[loadPaths]].
+   * A relative load's URL is first resolved relative to {@link url}, then
+   * passed to {@link importer}. If the importer doesn't recognize it, it's then
+   * passed to {@link importers} and {@link loadPaths}.
    *
    * @category Input
    */
@@ -409,8 +412,8 @@ export interface StringOptionsWithImporter<sync extends 'sync' | 'async'>
 
   /**
    * The canonical URL of the entrypoint stylesheet. If this is passed along
-   * with [[importer]], it's used to resolve relative loads in the entrypoint
-   * stylesheet.
+   * with {@link importer}, it's used to resolve relative loads in the
+   * entrypoint stylesheet.
    *
    * @category Input
    */
@@ -418,15 +421,16 @@ export interface StringOptionsWithImporter<sync extends 'sync' | 'async'>
 }
 
 /**
- * Options that can be passed to [[compileString]] or [[compileStringAsync]].
+ * Options that can be passed to {@link compileString} or {@link
+ * compileStringAsync}.
  *
- * This is a [[StringOptionsWithImporter]] if it has a
- * [[StringOptionsWithImporter.importer]] field, and a
- * [[StringOptionsWithoutImporter]] otherwise.
+ * This is a {@link StringOptionsWithImporter} if it has a {@link
+ * StringOptionsWithImporter.importer} field, and a {@link
+ * StringOptionsWithoutImporter} otherwise.
  *
  * @typeParam sync - This lets the TypeScript checker verify that asynchronous
- * [[Importer]]s, [[FileImporter]]s, and [[CustomFunction]]s aren't passed to
- * [[compile]] or [[compileString]].
+ * {@link Importer}s, {@link FileImporter}s, and {@link CustomFunction}s aren't
+ * passed to {@link compile} or {@link compileString}.
  *
  * @category Options
  */

package/types/util/promise_or.d.ts

@@ -2,10 +2,10 @@
  * A utility type for choosing between synchronous and asynchronous return
  * values.
  *
- * This is used as the return value for plugins like [[CustomFunction]],
- * [[Importer]], and [[FileImporter]] so that TypeScript enforces that
- * asynchronous plugins are only passed to [[compileAsync]] and
- * [[compileStringAsync]], not [[compile]] or [[compileString]].
+ * This is used as the return value for plugins like {@link CustomFunction},
+ * {@link Importer}, and {@link FileImporter} so that TypeScript enforces that
+ * asynchronous plugins are only passed to {@link compileAsync} and {@link
+ * compileStringAsync}, not {@link compile} or {@link compileString}.
  *
  * @typeParam sync - If this is `'sync'`, this can only be a `T`. If it's
  * `'async'`, this can be either a `T` or a `Promise<T>`.

package/types/value/argument_list.d.ts

@@ -8,8 +8,8 @@ import {SassList, ListSeparator} from './list';
  * type](https://sass-lang.com/documentation/values/lists#argument-lists).
  *
  * An argument list comes from a rest argument. It's distinct from a normal
- * [[SassList]] in that it may contain a keyword map as well as the positional
- * arguments.
+ * {@link SassList} in that it may contain a keyword map as well as the
+ * positional arguments.
  *
  * @category Custom Function
  */
@@ -19,13 +19,13 @@ export class SassArgumentList extends SassList {
    *
    * @param contents - The positional arguments that make up the primary
    * contents of the list. This may be either a plain JavaScript array or an
-   * immutable [[List]] from the [`immutable`
+   * immutable {@link List} from the [`immutable`
    * package](https://immutable-js.com/).
    *
    * @param keywords - The keyword arguments attached to this argument list,
    * whose names should exclude `$`. This can be either a plain JavaScript
-   * object with argument names as fields, or an immutable [[OrderedMap]] from
-   * the [`immutable` package](https://immutable-js.com/)
+   * object with argument names as fields, or an immutable {@link OrderedMap}
+   * from the [`immutable` package](https://immutable-js.com/)
    *
    * @param separator - The separator for this list. Defaults to `','`.
    */
@@ -40,7 +40,7 @@ export class SassArgumentList extends SassList {
    *
    * The argument names don't include `$`.
    *
-   * @returns An immutable [[OrderedMap]] from the [`immutable`
+   * @returns An immutable {@link OrderedMap} from the [`immutable`
    * package](https://immutable-js.com/).
    */
   get keywords(): OrderedMap<string, Value>;

package/types/value/function.d.ts

@@ -16,7 +16,7 @@ export class SassFunction extends Value {
    * @param signature - The function signature, like you'd write for the
    * [`@function rule`](https://sass-lang.com/documentation/at-rules/function).
    * @param callback - The callback that's invoked when this function is called,
-   * just like for a [[CustomFunction]].
+   * just like for a {@link CustomFunction}.
    */
   constructor(signature: string, callback: (args: Value[]) => Value);
 }

package/types/value/index.d.ts

@@ -27,8 +27,8 @@ export const sassNull: Value;
 /**
  * The abstract base class of Sass's value types.
  *
- * This is passed to and returned by [[CustomFunction]]s, which are passed into
- * the Sass implementation using [[Options.functions]].
+ * This is passed to and returned by {@link CustomFunction}s, which are passed
+ * into the Sass implementation using {@link Options.functions}.
  *
  * @category Custom Function
  */
@@ -41,7 +41,7 @@ export abstract class Value implements ValueObject {
    * All SassScript values can be used as lists. Maps count as lists of pairs,
    * and all other values count as single-value lists.
    *
-   * @returns An immutable [[List]] from the [`immutable`
+   * @returns An immutable {@link List} from the [`immutable`
    * package](https://immutable-js.com/).
    */
   get asList(): List<Value>;
@@ -61,7 +61,7 @@ export abstract class Value implements ValueObject {
   get isTruthy(): boolean;
 
   /**
-   * Returns JavaScript's `null` value if this is [[sassNull]], and returns
+   * Returns JavaScript's `null` value if this is {@link sassNull}, and returns
    * `this` otherwise.
    */
   get realNull(): null | Value;
@@ -76,7 +76,7 @@ export abstract class Value implements ValueObject {
 
   /**
    * Converts `sassIndex` into a JavaScript-style index into the list returned
-   * by [[asList]].
+   * by {@link asList}.
    *
    * Sass indexes are one-based, while JavaScript indexes are zero-based. Sass
    * indexes may also be negative in order to index from the end of the list.
@@ -85,7 +85,7 @@ export abstract class Value implements ValueObject {
    * @param name - The name of the function argument `sassIndex` came from
    * (without the `$`) if it came from an argument. Used for error reporting.
    * @throws `Error` If `sassIndex` isn't a number, if that number isn't an
-   * integer, or if that integer isn't a valid index for [[asList]].
+   * integer, or if that integer isn't a valid index for {@link asList}.
    */
   sassIndexToListIndex(sassIndex: Value, name?: string): number;
 
@@ -106,9 +106,9 @@ export abstract class Value implements ValueObject {
   get(index: number): Value | undefined;
 
   /**
-   * Throws if `this` isn't a [[SassBoolean]].
+   * Throws if `this` isn't a {@link SassBoolean}.
    *
-   * **Heads up!** Functions should generally use [[isTruthy]] rather than
+   * **Heads up!** Functions should generally use {@link isTruthy} rather than
    * requiring a literal boolean.
    *
    * @param name - The name of the function argument `this` came from (without
@@ -117,7 +117,7 @@ export abstract class Value implements ValueObject {
   assertBoolean(name?: string): SassBoolean;
 
   /**
-   * Throws if `this` isn't a [[SassColor]].
+   * Throws if `this` isn't a {@link SassColor}.
    *
    * @param name - The name of the function argument `this` came from (without
    * the `$`) if it came from an argument. Used for error reporting.
@@ -125,7 +125,7 @@ export abstract class Value implements ValueObject {
   assertColor(name?: string): SassColor;
 
   /**
-   * Throws if `this` isn't a [[SassFunction]].
+   * Throws if `this` isn't a {@link SassFunction}.
    *
    * @param name - The name of the function argument `this` came from (without
    * the `$`) if it came from an argument. Used for error reporting.
@@ -133,7 +133,7 @@ export abstract class Value implements ValueObject {
   assertFunction(name?: string): SassFunction;
 
   /**
-   * Throws if `this` isn't a [[SassMap]].
+   * Throws if `this` isn't a {@link SassMap}.
    *
    * @param name - The name of the function argument `this` came from (without
    * the `$`) if it came from an argument. Used for error reporting.
@@ -141,7 +141,7 @@ export abstract class Value implements ValueObject {
   assertMap(name?: string): SassMap;
 
   /**
-   * Throws if `this` isn't a [[SassNumber]].
+   * Throws if `this` isn't a {@link SassNumber}.
    *
    * @param name - The name of the function argument `this` came from (without
    * the `$`) if it came from an argument. Used for error reporting.
@@ -149,7 +149,7 @@ export abstract class Value implements ValueObject {
   assertNumber(name?: string): SassNumber;
 
   /**
-   * Throws if `this` isn't a [[SassString]].
+   * Throws if `this` isn't a {@link SassString}.
    *
    * @param name - The name of the function argument `this` came from (without
    * the `$`) if it came from an argument. Used for error reporting.

package/types/value/list.d.ts

@@ -21,7 +21,7 @@ export class SassList extends Value {
    * Creates a new list.
    *
    * @param contents - The contents of the list. This may be either a plain
-   * JavaScript array or an immutable [[List]] from the [`immutable`
+   * JavaScript array or an immutable {@link List} from the [`immutable`
    * package](https://immutable-js.com/).
    *
    * @param options.separator - The separator to use between elements of this

package/types/value/map.d.ts

@@ -13,13 +13,13 @@ export class SassMap extends Value {
    * Creates a new map.
    *
    * @param contents - The contents of the map. This is an immutable
-   * [[OrderedMap]] from the [`immutable` package](https://immutable-js.com/).
+   * `OrderedMap` from the [`immutable` package](https://immutable-js.com/).
    * Defaults to an empty map.
    */
   constructor(contents?: OrderedMap<Value, Value>);
 
   /**
-   * Returns the contents of this map as an immutable [[OrderedMap]] from the
+   * Returns the contents of this map as an immutable {@link OrderedMap} from the
    * [`immutable` package](https://immutable-js.com/).
    */
   get contents(): OrderedMap<Value, Value>;
@@ -33,7 +33,7 @@ export class SassMap extends Value {
    */
   get(key: Value): Value | undefined;
 
-  /** Inherited from [[Value.get]]. */
+  /** Inherited from {@link Value.get}. */
   get(index: number): SassList | undefined;
 
   /** @hidden */