From 42bf5675e9d65a93ad0251932ad1b894bf3e7d9d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C2=B7Y?= <jinsyin@gmail.com>
Date: Wed, 20 Nov 2019 23:31:49 +0800
Subject: [PATCH] Disambiguate the placeholder of permalink (#7906)

Merge pull request 7906
---
 docs/_docs/permalinks.md | 69 ++++++++++++++++++++++++++++++++++++----
 1 file changed, 62 insertions(+), 7 deletions(-)

diff --git a/docs/_docs/permalinks.md b/docs/_docs/permalinks.md
index ccf3ede2..24e98c13 100644
--- a/docs/_docs/permalinks.md
+++ b/docs/_docs/permalinks.md
@@ -34,12 +34,13 @@ You can use placeholders to your desired output. For example:
 permalink: /:categories/:year/:month/:day/:title:output_ext
 ```
 
-Note that pages and collections don't have time or categories, these aspects of
-the permalink style are ignored for the output.
+Note that pages and collections (excluding `posts` and `drafts`) don't have time
+and categories (for pages, the above `:title` is equivalent to `:basename`), these
+aspects of the permalink style are ignored for the output.
 
 For example, a permalink style of
-`/:categories/:year/:month/:day/:title:output_ext` for posts becomes
-`/:title.html` for pages and collections.
+`/:categories/:year/:month/:day/:title:output_ext` for the `posts` collection becomes
+`/:title.html` for pages and collections (excluding `posts` and `drafts`).
 
 ### Placeholders
 
@@ -329,8 +330,8 @@ Rather than typing `permalink: /:categories/:year/:month/:day/:title/`, you can
 
 ### Collections
 
-For collections, you have the option to override the global permalink in the
-collection configuration in `_config.yml`:
+For collections (including `posts` and `drafts`), you have the option to override
+the global permalink in the collection configuration in `_config.yml`:
 
 ```yaml
 collections:
@@ -363,7 +364,10 @@ Collections have the following placeholders available:
         <p><code>:path</code></p>
       </td>
       <td>
-        <p>Path to the document relative to the collection's directory.</p>
+        <p>
+          Path to the document relative to the collection's directory,
+          including base filename of the document.
+        </p>
       </td>
     </tr>
     <tr>
@@ -400,3 +404,54 @@ Collections have the following placeholders available:
   </tbody>
 </table>
 </div>
+
+### Pages
+
+For pages, you have to use front matter to override the global permalink,
+and if you set a permalink via front matter defaults in `_config.yml`,
+it will be ignored.
+
+Pages have the following placeholders available:
+
+<div class="mobile-side-scroller">
+<table>
+  <thead>
+    <tr>
+      <th>Variable</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>
+        <p><code>:path</code></p>
+      </td>
+      <td>
+        <p>
+          Path to the page relative to the site's source directory, excluding
+          base filename of the page.
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>:basename</code></p>
+      </td>
+      <td>
+        <p>The page's base filename</p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>:output_ext</code></p>
+      </td>
+      <td>
+        <p>
+          Extension of the output file. (Included by default and usually
+          unnecessary.)
+        </p>
+      </td>
+    </tr>
+  </tbody>
+</table>
+</div>