Document RelativizeUrls module

3 files changed, 31 insertions, 5 deletions

diff --git a/examples/brochure/hakyll.hs b/examples/brochure/hakyll.hs
index e84f14c..483265a 100644
--- a/examples/brochure/hakyll.hs
+++ b/examples/brochure/hakyll.hs
@@ -14,5 +14,5 @@ main = hakyll $ do
     forM_ ["about.rst", "index.markdown", "code.lhs"] $ \page -> do
         route   page $ setExtension "html"
         compile page $ defaultPageRead
-            >>> require "templates/default.html" (flip applyTemplate)
+            >>> defaultApplyTemplate "templates/default.html"
             >>> defaultRelativizeUrls
diff --git a/examples/hakyll/tutorial.markdown b/examples/hakyll/tutorial.markdown
index 3fa870f..bf534f3 100644
--- a/examples/hakyll/tutorial.markdown
+++ b/examples/hakyll/tutorial.markdown
@@ -73,7 +73,7 @@ main = hakyll $ do
     forM_ ["about.rst", "index.markdown", "code.lhs"] $ \page -> do
         route   page $ setExtension "html"
         compile page $ defaultPageRead
-            >>> require "templates/default.html" (flip applyTemplate)
+            >>> defaultApplyTemplate "templates/default.html"
             >>> defaultRelativizeUrls
 ~~~~~
 
@@ -133,7 +133,7 @@ Next, we're going to render some pages. We're going to style the results a
 little, so we're going to need a [template]. We simply compile a template using
 the `defaultTemplateRead` compiler, it's good enough in most cases.
 
-[template]: TODO: link
+[template]: /reference/Hakyll-Web-Template.html
 
 We don't use a route for these templates, after all, we don't want to route them
 anywhere, we just want to use them to style our pages a little.
@@ -142,6 +142,13 @@ anywhere, we just want to use them to style our pages a little.
 compile "templates/*" defaultTemplateRead
 ~~~~~
 
+We can conclude that some rules do not *directly* add an output page on our
+site. In this case, we compile the template so it is available to the compiler
+later[^1].
+
+[^1]: Actually, since the rules DSL is declarative, we could also add the
+      template compile rule at the bottom -- this would make no difference.
+
 Now, it's time to actually render our pages. We use the `forM_` monad combinator
 so we can describe all files at once.
 
@@ -162,10 +169,13 @@ DSL there.
 ### The Compiler DSL
 
 The gist of it is that the `Compiler a b` type has two parameters -- it is an
-Arrow, and we can chain compilers using the `>>>` operator.
+Arrow, and we can chain compilers using the `>>>` operator. The [compiler]
+reference page has some more information on this subject.
+
+[compiler]: /reference/Hakyll-Core-Compiler.html
 
 ~~~~~{.haskell}
 compile page $ defaultPageRead
-    >>> require "templates/default.html" (flip applyTemplate)
+    >>> defaultApplyTemplate "templates/default.html"
     >>> defaultRelativizeUrls
 ~~~~~
diff --git a/src/Hakyll/Web/RelativizeUrls.hs b/src/Hakyll/Web/RelativizeUrls.hs
index 2a3b98f..40a5847 100644
--- a/src/Hakyll/Web/RelativizeUrls.hs
+++ b/src/Hakyll/Web/RelativizeUrls.hs
@@ -1,3 +1,19 @@
+-- | This module exposes a function which can relativize URL's on a webpage.
+--
+-- This means that one can deploy the resulting site on
+-- @http:\/\/example.com\/@, but also on @http:\/\/example.com\/some-folder\/@
+-- without having to change anything (simply copy over the files).
+--
+-- To use it, you should use absolute URL's from the site root everywhere. For
+-- example, use
+--
+-- > <img src="/images/lolcat.png" alt="Funny zomgroflcopter" />
+--
+-- in a blogpost. When running this through the relativize URL's module, this
+-- will result in (suppose your blogpost is located at @\/posts\/foo.html@:
+--
+-- > <img src="../images/lolcat.png" alt="Funny zomgroflcopter" />
+--
 module Hakyll.Web.RelativizeUrls
     ( relativizeUrls
     ) where