Add documentation about relative_permalinks. #1081

site/docs/configuration.md

@@ -253,6 +253,8 @@ show_drafts: nil
 limit_posts: 0
 pygments:    true
 
+relative_permalinks: true
+
 permalink:     date
 paginate_path: 'page:num'
 

site/docs/upgrading.md

@@ -33,6 +33,26 @@ rebuild each time a file changes, just add the `--watch` flag at the end.
     or `jekyll build`.</p>
 </div>
 
+### Absolute Permalinks
+
+In older Jekyll versions, one could use relative permalinks for pages in
+subdirectories. As of Jekyll v1.0, **we introduced absolute permalinks**,
+which do not take advantage of the page's directory position to write the
+permalink. As of Jekyll v1.0.2, a new switch, `relative_permalinks`,
+allows the user to turn relative permalinks on and off at will, in order
+to preserve the old behaviour, or use the new behaviour. As of v1.0.2,
+this switch defaults to `true`, but it will default to `false`
+in v1.1.0 and beyond.
+
+<div class="note warning" id="absolute-permalinks-warning">
+  <h5 markdown="1">Absolute permalinks will be default in v1.1 and on</h5>
+  <p markdown="1">
+    Starting with Jekyll v1.1.0, `relative_permalinks` will default to `false`,
+    meaning all pages will be built using the absolute permalink behaviour.
+    The switch will still exist until v2.0.
+  </p>
+</div>
+
 ### Custom Config File
 
 Rather than passing individual flags via the command line, you can now pass an