content: Document the collections.D function

Author: jmooring

.cspell.json

@@ -144,6 +144,7 @@
     "Samsa",
     "Stucki",
     "Thénardier",
+    "Vitter",
     "WASI",
     "# ----------------------------------------------------------------------",
     "# cspell: ignore operating systems and software packages",

assets/css/styles.css

@@ -129,3 +129,8 @@ body {
   text-decoration: none;
   padding-left: .0625em;
 }
+
+/* Code spans within paragraphs. */
+p > code {
+  white-space: nowrap;
+}

content/en/_common/installation/04-build-from-source.md

@@ -7,7 +7,7 @@ _comment: Do not remove front matter.
 To build the extended or extended/deploy edition from source you must:
 
 1. Install [Git]
-1. Install [Go] version 1.23.0 or later
+1. Install [Go] version 1.24.0 or later
 1. Install a C compiler, either [GCC] or [Clang]
 1. Update your `PATH` environment variable as described in the [Go documentation]
 

content/en/contribute/development.md

@@ -32,7 +32,7 @@ For a complete guide to contributing to Hugo, see the [Contribution Guide].
 To build the extended or extended/deploy edition from source you must:
 
 1. Install [Git]
-1. Install [Go] version 1.23.0 or later
+1. Install [Go] version 1.24.0 or later
 1. Install a C compiler, either [GCC] or [Clang]
 1. Update your `PATH` environment variable as described in the [Go documentation]
 

content/en/functions/collections/D.md

@@ -0,0 +1,53 @@
+---
+title: collections.D
+description: Returns a slice of sequentially ordered random integers.
+categories: []
+keywords: [random]
+params:
+  functions_and_methods:
+    returnType: '[]int'
+    signatures: [collections.D SEED N HIGH]
+---
+
+{{< new-in 0.149.0 />}}
+
+The `collections.D` function returns a slice of `N` sequentially ordered unique random integers in the half-open [interval](g) [0, `HIGH`) using the provided `SEED` value. This function implements J. S. Vitter's Method&nbsp;D[^1] for sequential random sampling, a fast and efficient algorithm for this task.
+
+See [this article][] for a detailed explanation.
+
+```go-html-template
+{{ collections.D 6 7 42 }} → [4, 9, 10, 20, 22, 24, 41]
+```
+
+The example above generates the _same_ random numbers each time it is called. To generate a _different_ set of 7 random numbers in the same range, change the seed value.
+
+```go-html-template
+{{ collections.D 2 7 42 }} → [3, 11, 19, 25, 32, 33, 38]
+```
+
+> [!note]
+> All arguments are cast to integers, so setting the seed to `3.14` is the same as setting it to `3`.
+
+A common use case is the selection of random pages from a page collection. For example, to render a list of 5 random pages using the [day of the year][] as the seed value:
+
+```go-html-template
+<ul>
+  {{ $p := site.RegularPages }}
+  {{ range collections.D now.YearDay 5 ($p | len) }}
+    {{ with (index $p .) }}
+      <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+    {{ end }}
+  {{ end }}
+</ul>
+```
+
+The construct above is significantly faster than using the [`collections.Shuffle`][] function.
+
+> [!note]
+> The slice created by this function is limited to 1 million elements.
+
+[^1]: J. S. Vitter, "An efficient algorithm for sequential random sampling," _ACM Trans. Math. Soft._, vol. 13, pp. 58&ndash;67, Mar. 1987.
+
+[this article]: https://getkerf.wordpress.com/2016/03/30/the-best-algorithm-no-one-knows-about/
+[`collections.Shuffle`]: /functions/collections/shuffle/
+[day of the year]: /methods/time/yearday/

content/en/functions/collections/Seq.md

@@ -32,4 +32,4 @@ A contrived example of iterating over a sequence of integers:
 ```
 
 > [!note]
-> The slice created by the `seq` function is limited to 2000 elements.
+> The slice created by this function is limited to 1 million elements.

content/en/functions/collections/Shuffle.md

@@ -2,7 +2,7 @@
 title: collections.Shuffle
 description: Returns a random permutation of a given array or slice.
 categories: []
-keywords: []
+keywords: [random]
 params:
   functions_and_methods:
     aliases: [shuffle]
@@ -27,3 +27,9 @@ To render an unordered list of 5 random pages from a page collection:
   {{ end }}
 </ul>
 ```
+
+{{< new-in 0.149.0 />}}
+
+Using the [`collections.D`][] function for the same task is significantly faster.
+
+[`collections.D`]: /functions/collections/D/

content/en/functions/math/Rand.md

@@ -2,7 +2,7 @@
 title: math.Rand
 description: Returns a pseudo-random number in the half-open interval [0.0, 1.0).
 categories: []
-keywords: []
+keywords: [random]
 params:
   functions_and_methods:
     aliases: []

data/keywords.yaml

@@ -7,6 +7,7 @@
 # will decrease over time, though the initial implementation will require some
 # effort.
 
+- highlight
 - menu
+- random
 - resource
-- highlight