From 5ef94a725ef1a149e05c897ad86de3333ec1896a Mon Sep 17 00:00:00 2001
From: Joe Mooring <joe.mooring@veriphor.com>
Date: Mon, 5 May 2025 16:01:46 -0700
Subject: [PATCH] content: Document alternative to shuffle for large
 collections

---
 content/en/functions/collections/Shuffle.md | 33 +++++++++++++++++++--
 1 file changed, 31 insertions(+), 2 deletions(-)

diff --git a/content/en/functions/collections/Shuffle.md b/content/en/functions/collections/Shuffle.md
index 3a27c099a..a2cb03b24 100644
--- a/content/en/functions/collections/Shuffle.md
+++ b/content/en/functions/collections/Shuffle.md
@@ -12,8 +12,37 @@ aliases: [/functions/shuffle]
 ---
 
 ```go-html-template
-{{ shuffle (seq 1 2 3) }} → [3 1 2] 
-{{ shuffle (slice "a" "b" "c") }} → [b a c] 
+{{ collections.Shuffle (seq 1 2 3) }} → [3 1 2] 
+{{ collections.Shuffle (slice "a" "b" "c") }} → [b a c] 
 ```
 
 The result will vary from one build to the next.
+
+To render an unordered list of 5 random pages from a page collection:
+
+```go-html-template
+<ul>
+  {{ $p := site.RegularPages }}
+  {{ range $p | collections.Shuffle | first 5 }}
+    <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+  {{ end }}
+</ul>
+```
+
+For better performance with large collections, use the [`math.Rand`] and [`collections.Index`] functions instead:
+
+```go-html-template
+<ul>
+  {{ $p := site.RegularPages }}
+  {{ range seq 5 }}
+    {{ with math.Rand | mul $p.Len | math.Floor | int }}
+      {{ with index $p . }}
+        <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+      {{ end }}
+    {{ end }}
+  {{ end }}
+</ul>
+```
+
+[`collections.Index`]:/functions/collections/indexfunction/
+[`math.Rand`]: /functions/math/rand/