From 8c64de684842d9650c22edd1c2e5e67d5757e22c Mon Sep 17 00:00:00 2001
From: Phil Pennock <pdp@spodhuis.org>
Date: Fri, 3 Jan 2014 18:36:53 -0500
Subject: [PATCH] Add `canonifyurls` config option.

Be able to inhibit AbsURL canonicalization of content, on a site
configuration basis. Advantages of being able to inhibit this include
making it easier to rendering on other hostnames, and being able to
include resources on http or https depending on how this page was
retrieved, avoiding mixed-mode client complaints without adding latency
for plain http.
---
 content/extras/urls.md            | 21 +++++++++++++++++++++
 content/overview/configuration.md |  3 +++
 2 files changed, 24 insertions(+)
 create mode 100644 content/extras/urls.md

diff --git a/content/extras/urls.md b/content/extras/urls.md
new file mode 100644
index 000000000..b386effba
--- /dev/null
+++ b/content/extras/urls.md
@@ -0,0 +1,21 @@
+---
+title: "URLs"
+date: "2014-01-03"
+aliases:
+  - "/doc/urls/"
+groups: ["extras"]
+groups_weight: 40
+---
+By default, all relative URLs encountered in the input will be canonicalized
+using `baseurl`, so that a link `/css/foo.css` becomes
+`http://yoursite.example.com/css/foo.css`.
+
+Setting `canonifyurls` to `false` will prevent this canonicalization.
+
+Benefits of canonicalization include fixing all URLs to be absolute, which may
+aid with some parsing tasks.  Note though that all real browsers handle this
+client-side without issues.
+
+Benefits of non-canonicalization include being able to have resource inclusion
+be scheme-relative, so that http vs https can be decided based on how this
+page was retrieved.
diff --git a/content/overview/configuration.md b/content/overview/configuration.md
index 5721df133..30a33a7c7 100644
--- a/content/overview/configuration.md
+++ b/content/overview/configuration.md
@@ -30,6 +30,7 @@ indexes:
    category: "categories"
    tag: "tags"
 baseurl: "http://yoursite.example.com/"
+canonifyurls: true
 ...
 {{% /highlight %}}
 
@@ -46,6 +47,7 @@ The following is an example of a json config file with the default values:
        "tag": "tags"
     },
     "baseurl": "http://yoursite.example.com/"
+    "canonifyurls": true
 }
 {{% /highlight %}}
 
@@ -56,6 +58,7 @@ The following is an example of a toml config file with the default values:
     publishdir = "public"
     builddrafts = false
     baseurl = "http://yoursite.example.com/"
+    canonifyurls = true
     [indexes]
        category = "categories"
        tag = "tags"