From 61faef46cce602feff9b8deb20dba5c2c01c4c93 Mon Sep 17 00:00:00 2001
From: Parker Moore <parkrmoore@gmail.com>
Date: Sun, 12 May 2013 14:07:30 +0200
Subject: [PATCH] Add documentation about relative_permalinks. #1081

---
 site/docs/configuration.md |  2 ++
 site/docs/upgrading.md     | 20 ++++++++++++++++++++
 2 files changed, 22 insertions(+)

diff --git a/site/docs/configuration.md b/site/docs/configuration.md
index d8da48b4..ffdbf6ef 100644
--- a/site/docs/configuration.md
+++ b/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'
 
diff --git a/site/docs/upgrading.md b/site/docs/upgrading.md
index 6c5b42d2..2e85533e 100644
--- a/site/docs/upgrading.md
+++ b/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