add random-with-units link to sidenav and fix link in math#random

data/documentation.yml

@@ -1,74 +1,75 @@
 toc:
-- Syntax: /documentation/syntax
-  :children:
-  - 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
-  :children:
-  - 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
-  :children:
-  - <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
+  - Syntax: /documentation/syntax
     :children:
-    - <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
-  :children:
-  - 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
-  :children:
-  - 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
-  :children:
-  - <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
-  :children:
-  - 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
-  - Color Units: /documentation/breaking-changes/color-units
-  - Extending Compound Selectors: /documentation/breaking-changes/extend-compound
-  - CSS Variable Syntax: /documentation/breaking-changes/css-vars
-- Command Line: /documentation/cli
-  :children:
-  - Dart Sass: /documentation/cli/dart-sass
-  - Ruby Sass: /documentation/cli/ruby-sass
-  - Migrator: /documentation/cli/migrator
-- JavaScript API: /documentation/js-api
+      - 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
+    :children:
+      - 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
+    :children:
+      - <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
+        :children:
+          - <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
+    :children:
+      - 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
+    :children:
+      - 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
+    :children:
+      - <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
+    :children:
+      - 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
+      - Color Units: /documentation/breaking-changes/color-units
+      - Extending Compound Selectors: /documentation/breaking-changes/extend-compound
+      - CSS Variable Syntax: /documentation/breaking-changes/css-vars
+      - Random With Units: /documentation/breaking-changes/random-with-units
+  - Command Line: /documentation/cli
+    :children:
+      - Dart Sass: /documentation/cli/dart-sass
+      - Ruby Sass: /documentation/cli/ruby-sass
+      - Migrator: /documentation/cli/migrator
+  - JavaScript API: /documentation/js-api

source/documentation/breaking-changes.html.md.erb

@@ -37,3 +37,6 @@ These breaking changes are coming soon or have recently been released:
 
 * [The syntax for CSS custom property values changed](breaking-changes/css-vars)
   in Dart Sass 1.0.0, LibSass 3.5.0, and Ruby Sass 3.5.0.
+
+* [`random($limit)` with units](breaking-changes/random-with-units) beginning in
+  Dart Sass 1.54.5.

source/documentation/breaking-changes/random-with-units.md.erb

@@ -10,8 +10,19 @@ The function [`random($limit)`] has historically ignored units in `$limit` which
 returned a unitless value. For example `random(100px)` would drop "px" and
 return a value like `42`.
 
+A future implementation of Dart Sass will stop ignoring units for the `$limit`
+argument will return a random integer with the same units.
+
 [`random($limit)`]: ../modules/math#random
 
+<% example(autogen_css: false) do %>
+  // Future Sass, doesn't work yet!
+  @debug math.random(100px); // 42px
+  ===
+  // Future Sass, doesn't work yet!
+  @debug math.random(100px)  // 42px
+<% end %>
+
 ## Transition Period
 
 <% impl_status dart: '1.54.5', libsass: false, ruby: false %>

source/documentation/modules/math.html.md.erb

@@ -541,18 +541,16 @@ title: sass:math
   number between 1 and `$limit`.
 
   <% heads_up do %>
-    `random($limit)` ignores units in `$limit`. This behavior will be deprecated
-    and `random($limit)` will return a random integer with the same units as the
-    `$limit` argument.
+    `random($limit)` ignores units in `$limit`. [This behavior will be
+    deprecated] and `random($limit)` will return a random integer with the same
+    units as the `$limit` argument.
 
     [This behavior will be deprecated]: ../breaking-changes/random-with-units
 
     <% example(autogen_css: false) do %>
       @debug math.random(100px); // 42
-      @debug math.random(10000%); // 9001
       ===
       @debug math.random(100px)  // 42
-      @debug math.random(10000%)  // 9001
     <% end %>
   <% end %>