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

data/documentation.yml

@@ -66,6 +66,7 @@ toc:
   - 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

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 %>