Allow custom sorting of collection documents (#7427)

Merge pull request 7427

test/source/_tutorials/dive-in-and-publish-already.md

@@ -0,0 +1,9 @@
+---
+title: "Dive-In and Publish Already!"
+lesson: 3
+approx_time: 30 mins
+---
+
+Jekyll converts Markdown documents to HTML by default. Don't know what's Markdown?
+Read this [documentation](http://daringfireball.net/projects/markdown/)
+While you're at it, might as well learn about [Kramdown](https://kramdown.gettalong.org/)

test/source/_tutorials/extending-with-plugins.md

@@ -0,0 +1,9 @@
+---
+title: "Extending with Plugins"
+lesson: 5
+approx_time: 1 min
+---
+
+A lot can be accomplished by using Jekyll out-of-the-box. But a lot more can be achieved by using plugins that extend Jekyll's functionality. There are numerous plugins supported by the official team and many other third-party plugins provided by the Jekyll Community.
+
+Check this [documentation page](https://jekyllrb.com/docs/plugins/) dedicated to working with plugins.

test/source/_tutorials/getting-started.md

@@ -0,0 +1,7 @@
+---
+title: "Getting Started"
+lesson: 1
+approx_time: 10 mins
+---
+
+The first thing you need is a working installation of Ruby. Install from [the official website](https://www.ruby-lang.org/en/documentation/installation/).

test/source/_tutorials/graduation-day.md

@@ -0,0 +1,10 @@
+---
+title: "Graduation Day"
+lesson: 6
+approx_time: 10 mins
+---
+
+Congratualtions! You now know enough to start Jekylling!
+
+Want to report a bug you found? Or give something back to the community?
+Head over to the [Jekyll Repo](https://github.com/jekyll/jekyll) at GitHub

test/source/_tutorials/lets-roll.md

@@ -0,0 +1,16 @@
+---
+title: "Let's Roll!"
+lesson: 2
+approx_time: 1 min
+---
+
+Now that you have installed Ruby, Jekyll and Bundler, lets get Jekylling!
+Enter the following in your terminal:
+
+    $ jekyll new my blog
+
+Then preview your new project in your browser right away by entering the following and pointing your browser to `http://localhost:4000` :
+
+    $ bundle exec jekyll serve
+
+Go ahead. Try it.

test/source/_tutorials/tip-of-the-iceberg.md

@@ -0,0 +1,6 @@
+---
+title: "Tip of the Iceberg"
+lesson: 4
+---
+
+Now that you know some of the basics, learn more about working with [Jekyll](https://jekyllrb.com).

test/test_collections.rb

@@ -179,6 +179,96 @@ class TestCollections < JekyllUnitTest
     end
   end
 
+  context "with a collection with metadata to sort items by attribute" do
+    setup do
+      @site = fixture_site(
+        "collections" => {
+          "methods"   => {
+            "output" => true,
+          },
+          "tutorials" => {
+            "output"  => true,
+            "sort_by" => "lesson",
+          },
+        }
+      )
+      @site.process
+      @tutorials_collection = @site.collections["tutorials"]
+
+      @actual_array = @tutorials_collection.docs.map(&:relative_path)
+    end
+
+    should "sort documents in a collection with 'sort_by' metadata set to a " \
+           "FrontMatter key 'lesson'" do
+      default_tutorials_array = %w(
+        _tutorials/dive-in-and-publish-already.md
+        _tutorials/extending-with-plugins.md
+        _tutorials/getting-started.md
+        _tutorials/graduation-day.md
+        _tutorials/lets-roll.md
+        _tutorials/tip-of-the-iceberg.md
+      )
+      tutorials_sorted_by_lesson_array = %w(
+        _tutorials/getting-started.md
+        _tutorials/lets-roll.md
+        _tutorials/dive-in-and-publish-already.md
+        _tutorials/tip-of-the-iceberg.md
+        _tutorials/extending-with-plugins.md
+        _tutorials/graduation-day.md
+      )
+      refute_equal default_tutorials_array, @actual_array
+      assert_equal tutorials_sorted_by_lesson_array, @actual_array
+    end
+  end
+
+  context "with a collection with metadata to rearrange items" do
+    setup do
+      @site = fixture_site(
+        "collections" => {
+          "methods"   => {
+            "output" => true,
+          },
+          "tutorials" => {
+            "output" => true,
+            "order"  => [
+              "getting-started.md",
+              "lets-roll.md",
+              "dive-in-and-publish-already.md",
+              "tip-of-the-iceberg.md",
+              "graduation-day.md",
+              "extending-with-plugins.md",
+            ],
+          },
+        }
+      )
+      @site.process
+      @tutorials_collection = @site.collections["tutorials"]
+
+      @actual_array = @tutorials_collection.docs.map(&:relative_path)
+    end
+
+    should "sort documents in a collection in the order outlined in the config file" do
+      default_tutorials_array = %w(
+        _tutorials/dive-in-and-publish-already.md
+        _tutorials/extending-with-plugins.md
+        _tutorials/getting-started.md
+        _tutorials/graduation-day.md
+        _tutorials/lets-roll.md
+        _tutorials/tip-of-the-iceberg.md
+      )
+      tutorials_rearranged_in_config_array = %w(
+        _tutorials/getting-started.md
+        _tutorials/lets-roll.md
+        _tutorials/dive-in-and-publish-already.md
+        _tutorials/tip-of-the-iceberg.md
+        _tutorials/graduation-day.md
+        _tutorials/extending-with-plugins.md
+      )
+      refute_equal default_tutorials_array, @actual_array
+      assert_equal tutorials_rearranged_in_config_array, @actual_array
+    end
+  end
+
   context "in safe mode" do
     setup do
       @site = fixture_site(