ISO week date drops (#5981)

Merge pull request 5981

docs/_docs/permalinks.md

@@ -61,8 +61,19 @@ Here's the full list of placeholders available:
       </td>
       <td>
         <p>
-          Year from the post's filename. May be overridden via the document’s
+          Year from the post’s filename with four digits.
-          <code>date</code> front matter
+          May be overridden via the document’s <code>date</code> front matter.
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>short_year</code></p>
+      </td>
+      <td>
+        <p>
+          Year from the post’s filename without the century. (00..99)
+          May be overridden via the document’s <code>date</code> front matter.
         </p>
       </td>
     </tr>
@@ -72,8 +83,8 @@ Here's the full list of placeholders available:
       </td>
       <td>
         <p>
-          Month from the post's filename. May be overridden via the document’s
+          Month from the post’s filename. (01..12)
-          <code>date</code> front matter
+          May be overridden via the document’s <code>date</code> front matter.
         </p>
       </td>
     </tr>
@@ -83,19 +94,35 @@ Here's the full list of placeholders available:
       </td>
       <td>
         <p>
-          Month without leading zeros from the post's filename. May be
+          Month without leading zeros from the post’s filename. May be
-          overridden via the document’s <code>date</code> front matter
+          overridden via the document’s <code>date</code> front matter.
         </p>
       </td>
     </tr>
+    <tr>
+      <td>
+        <p><code>short_month</code></p>
+      </td>
+      <td>
+        <p>Three-letter month abbreviation, e.g. “Jan”.</p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>long_month</code></p>
+      </td>
+      <td>
+        <p>Full month name, e.g. “January”.</p>
+      </td>
+    </tr>
     <tr>
       <td>
         <p><code>day</code></p>
       </td>
       <td>
         <p>
-          Day from the post's filename. May be overridden via the document’s
+          Day of the month from the post’s filename. (01..31)
-          <code>date</code> front matter
+          May be overridden via the document’s <code>date</code> front matter.
         </p>
       </td>
     </tr>
@@ -105,8 +132,8 @@ Here's the full list of placeholders available:
       </td>
       <td>
         <p>
-          Day without leading zeros from the post's filename. May be overridden
+          Day of the month without leading zeros from the post’s filename.
-          via the document’s <code>date</code> front matter
+          May be overridden via the document’s <code>date</code> front matter.
         </p>
       </td>
     </tr>
@@ -115,18 +142,47 @@ Here's the full list of placeholders available:
         <p><code>y_day</code></p>
       </td>
       <td>
-        <p>Day of the year from the post's filename, with leading zeros.</p>
+        <p>Ordinal day of the year from the post’s filename, with leading zeros. (001..366)</p>
       </td>
     </tr>
     <tr>
       <td>
-        <p><code>short_year</code></p>
+        <p><code>w_year</code></p>
       </td>
       <td>
-        <p>
+        <p>Week year which may differ from the month year for up to three days at the start of January and end of December</p>
-          Year without the century from the post's filename. May be overridden
+      </td>
-          via the document’s <code>date</code> front matter
+    </tr>
-        </p>
+    <tr>
+      <td>
+        <p><code>week</code></p>
+      </td>
+      <td>
+        <p>Week number of the current year, starting with the first week having a majority of its days in January. (01..53)</p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>w_day</code></p>
+      </td>
+      <td>
+        <p>Day of the week, starting with Monday. (1..7)</p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>short_day</code></p>
+      </td>
+      <td>
+        <p>Three-letter weekday abbreviation, e.g. “Sun”.</p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>long_day</code></p>
+      </td>
+      <td>
+        <p>Weekday name, e.g. “Sunday”.</p>
       </td>
     </tr>
     <tr>
@@ -135,7 +191,7 @@ Here's the full list of placeholders available:
       </td>
       <td>
         <p>
-          Hour of the day, 24-hour clock, zero-padded from the post's
+          Hour of the day, 24-hour clock, zero-padded from the post’s
           <code>date</code> front matter. (00..23)
         </p>
       </td>
@@ -146,7 +202,7 @@ Here's the full list of placeholders available:
       </td>
       <td>
         <p>
-          Minute of the hour from the post's <code>date</code> front matter. (00..59)
+          Minute of the hour from the post’s <code>date</code> front matter. (00..59)
         </p>
       </td>
     </tr>
@@ -156,7 +212,7 @@ Here's the full list of placeholders available:
       </td>
       <td>
         <p>
-          Second of the minute from the post's <code>date</code> front matter. (00..59)
+          Second of the minute from the post’s <code>date</code> front matter. (00..59)
         </p>
       </td>
     </tr>
@@ -237,6 +293,14 @@ For posts, Jekyll also provides the following built-in styles for convenience:
         <p><code>/:categories/:year/:y_day/:title:output_ext</code></p>
       </td>
     </tr>
+    <tr>
+      <td>
+        <p><code>weekdate</code></p>
+      </td>
+      <td>
+        <p><code>/:categories/:year/W:week/:short_day/:title.html</code></p>
+      </td>
+    </tr>
     <tr>
       <td>
         <p><code>none</code></p>

lib/jekyll/configuration.rb

@@ -305,6 +305,8 @@ module Jekyll
         "/:categories/:year/:month/:day/:title:output_ext"
       when :ordinal
         "/:categories/:year/:y_day/:title:output_ext"
+      when :weekdate
+        "/:categories/:year/W:week/:short_day/:title:output_ext"
       else
         permalink_style.to_s
       end

lib/jekyll/drops/url_drop.rb

@@ -35,46 +35,89 @@ module Jekyll
         category_set.to_a.join("/")
       end
 
+      # CCYY
       def year
         @obj.date.strftime("%Y")
       end
 
+      # MM: 01..12
       def month
         @obj.date.strftime("%m")
       end
 
+      # DD: 01..31
       def day
         @obj.date.strftime("%d")
       end
 
+      # hh: 00..23
       def hour
         @obj.date.strftime("%H")
       end
 
+      # mm: 00..59
       def minute
         @obj.date.strftime("%M")
       end
 
+      # ss: 00..59
       def second
         @obj.date.strftime("%S")
       end
 
+      # D: 1..31
       def i_day
         @obj.date.strftime("%-d")
       end
 
+      # M: 1..12
       def i_month
         @obj.date.strftime("%-m")
       end
 
+      # MMM: Jan..Dec
       def short_month
         @obj.date.strftime("%b")
       end
 
+      # MMMM: January..December
+      def long_month
+        @obj.date.strftime("%B")
+      end
+
+      # YY: 00..99
       def short_year
         @obj.date.strftime("%y")
       end
 
+      # CCYYw, ISO week year
+      # may differ from CCYY for the first days of January and last days of December
+      def w_year
+        @obj.date.strftime("%G")
+      end
+
+      # WW: 01..53
+      # %W and %U do not comply with ISO 8601-1
+      def week
+        @obj.date.strftime("%V")
+      end
+
+      # d: 1..7 (Monday..Sunday)
+      def w_day
+        @obj.date.strftime("%u")
+      end
+
+      # dd: Mon..Sun
+      def short_day
+        @obj.date.strftime("%a")
+      end
+
+      # ddd: Monday..Sunday
+      def long_day
+        @obj.date.strftime("%A")
+      end
+
+      # DDD: 001..366
       def y_day
         @obj.date.strftime("%j")
       end