From 567ca1d106479efa0c97c6043ea8f1fdc3cc940b Mon Sep 17 00:00:00 2001
From: Hashim Khan <64767361+Hashim1999164@users.noreply.github.com>
Date: Thu, 13 Aug 2026 05:21:35 +0500
Subject: [PATCH] Docs: clarify that sort and sort_natural are stable

---
 lib/liquid/standardfilters.rb | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/lib/liquid/standardfilters.rb b/lib/liquid/standardfilters.rb
index ed6141566..13fda8ade 100644
--- a/lib/liquid/standardfilters.rb
+++ b/lib/liquid/standardfilters.rb
@@ -395,6 +395,9 @@ def join(input, glue = ' ')
     # @liquid_category array
     # @liquid_summary
     #   Sorts the items in an array in case-sensitive alphabetical, or numerical, order.
+    # @liquid_description
+    #   The sort is stable: items that compare as equal keep their original relative order.
+    #   Pass an optional property name to sort objects by that property, for example `array | sort: "name"`.
     # @liquid_syntax array | sort
     # @liquid_return [array[untyped]]
     def sort(input, property = nil)
@@ -421,6 +424,8 @@ def sort(input, property = nil)
     # @liquid_summary
     #   Sorts the items in an array in case-insensitive alphabetical order.
     # @liquid_description
+    #   The sort is stable: items that compare as equal keep their original relative order.
+    #
     #   > Caution:
     #   > You shouldn't use the `sort_natural` filter to sort numerical values. When comparing items an array, each item is converted to a
     #   > string, so sorting on numerical values can lead to unexpected results.