@@ -2,9 +2,28 @@
22-- This is where the 'Routes' type comes in; it determines where a certain
33-- target should be written.
44--
5−-- When a route is applied (using 'runRoute'), it either returns a 'Just'
6−-- 'FilePath' (meaning the target should be written to that file path), or
7−-- 'Nothing' (meaning this target should not be written anywhere).
5+-- Suppose we have an item @foo\/bar.markdown@. We can render this to
6+-- @foo\/bar.html@ using:
7+--
8+-- > route "foo/bar.markdown" (setExtension ".html")
9+--
10+-- If we do not want to change the extension, we can use 'idRoute', the simplest
11+-- route available:
12+--
13+-- > route "foo/bar.markdown" idRoute
14+--
15+-- That will route @foo\/bar.markdown@ to @foo\/bar.markdown@.
16+--
17+-- Note that the extension says nothing about the content! If you set the
18+-- extension to @.html@, it is your own responsibility to ensure that the
19+-- content is indeed HTML.
20+--
21+-- Finally, some special cases:
22+--
23+-- * If there is no route for an item, this item will not be routed, so it will
24+-- not appear in your site directory.
25+--
26+-- * If an item matches multiple routes, the first rule will be chosen.
827--
928module Hakyll.Core.Routes
1029 ( Routes