Override collection url template

features/collections.feature

@@ -29,6 +29,20 @@ Feature: Collections
     And I should see "Methods metadata: bar" in "_site/collection_metadata.html"
     And I should see "<p>Whatever: foo.bar</p>" in "_site/methods/configuration.html"
 
+  Scenario: Rendered collection at a custom URL
+    Given I have an "index.html" page that contains "Collections: {{ site.collections }}"
+    And I have fixture collections
+    And I have a "_config.yml" file with content:
+    """
+    collections:
+      methods:
+        output: true
+        permalink: /:collection/:path/
+    """
+    When I run jekyll build
+    Then the _site directory should exist
+    And I should see "<p>Whatever: foo.bar</p>" in "_site/methods/configuration/index.html"
+
   Scenario: Rendered document in a layout
     Given I have an "index.html" page that contains "Collections: {{ site.collections }}"
     And I have a default layout that contains "<div class='title'>Tom Preston-Werner</div> {{content}}"

lib/jekyll/collection.rb

@@ -132,6 +132,13 @@ def write?
       !!metadata['output']
     end
 
+    # The URL template to render collection's documents at.
+    #
+    # Returns the URL template to render collection's documents at.
+    def url_template
+      metadata.fetch('permalink', "/:collection/:path:output_ext")
+    end
+
     # Extract options for this collection from the site configuration.
     #
     # Returns the metadata for this collection

lib/jekyll/document.rb

@@ -92,7 +92,7 @@ def render_with_liquid?
     #
     # Returns the URL template for the document.
     def url_template
-      "/:collection/:path:output_ext"
+      collection.url_template
     end
 
     # Construct a Hash of key-value pairs which contain a mapping between

site/docs/collections.md

@@ -56,6 +56,54 @@ For example, if you have `_my_collection/some_subdir/some_doc.md`,
 it will be rendered using Liquid and the Markdown converter of your
 choice and written out to `<dest>/my_collection/some_subdir/some_doc.html`.
 
+As for posts with [Permalinks](../Permalinks/), document URL can be customized by setting a `permalink` metadata to the collection:
+
+{% highlight yaml %}
+collections:
+  my_collection:
+    output: true
+    permalink: /awesome/:path/
+{% endhighlight %}
+
+For example, if you have `_my_collection/some_subdir/some_doc.md`, it will be written out to `<dest>/awesome/some_subdir/some_doc/index.html`.
+
+<div class="mobile-side-scroller">
+<table>
+  <thead>
+    <tr>
+      <th>Variable</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>
+        <p><code>collection</code></p>
+      </td>
+      <td>
+        <p>Label of the containing collection</p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>path</code></p>
+      </td>
+      <td>
+        <p>Path to the document relative to the collection's directory</p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>output_ext</code></p>
+      </td>
+      <td>
+        <p>Extension of the output file</p>
+      </td>
+    </tr>
+  </tbody>
+</table>
+</div>
+
 ## Liquid Attributes
 
 ### Collections

test/test_collections.rb

@@ -38,6 +38,10 @@ def fixture_site(overrides = {})
       assert_equal @collection.label, "methods"
     end
 
+    should "have default url template" do
+      assert_equal @collection.url_template, "/:collection/:path:output_ext"
+    end
+
     should "contain no docs when initialized" do
       assert_empty @collection.docs
     end
@@ -91,6 +95,24 @@ def fixture_site(overrides = {})
     end
   end
 
+  context "a collection with permalink" do
+    setup do
+      @site = fixture_site({
+        "collections" => {
+          "methods" => {
+            "permalink" => "/awesome/:path/"
+          }
+        }
+      })
+      @site.process
+      @collection = @site.collections["methods"]
+    end
+
+    should "have custom url template" do
+      assert_equal @collection.url_template, "/awesome/:path/"
+    end
+  end
+
   context "with a collection" do
     setup do
       @site = fixture_site({