-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A static website compiler library
--   
--   Hakyll is a static website compiler library. It provides you with the
--   tools to create a simple or advanced static website using a Haskell
--   DSL and formats such as markdown or RST. You can find more
--   information, including a tutorial, on the website:
--   
--   <ul>
--   <li><a>http://jaspervdj.be/hakyll</a></li>
--   </ul>
--   
--   If you seek assistance, there's:
--   
--   <ul>
--   <li>A google group: <a>http://groups.google.com/group/hakyll</a></li>
--   <li>An IRC channel, <tt>#hakyll</tt> on freenode</li>
--   </ul>
--   
--   Additionally, there's the Haddock documentation in the different
--   modules, meant as a reference.
@package hakyll
@version 3.2.7.2


-- | Representation of a directed graph. In Hakyll, this is used for
--   dependency tracking.
module Hakyll.Core.DirectedGraph

-- | Type used to represent a directed graph
data DirectedGraph a

-- | Construction of directed graphs
fromList :: Ord a => [(a, Set a)] -> DirectedGraph a

-- | Deconstruction of directed graphs
toList :: DirectedGraph a -> [(a, Set a)]

-- | Check if a node lies in the given graph
member :: Ord a => a -> DirectedGraph a -> Bool

-- | Get all nodes in the graph
nodes :: Ord a => DirectedGraph a -> Set a

-- | Get a set of reachable neighbours from a directed graph
neighbours :: Ord a => a -> DirectedGraph a -> Set a

-- | Reverse a directed graph (i.e. flip all edges)
reverse :: Ord a => DirectedGraph a -> DirectedGraph a

-- | Find all reachable nodes from a given set of nodes in the directed
--   graph
reachableNodes :: Ord a => Set a -> DirectedGraph a -> Set a


-- | Dump a directed graph in dot format. Used for debugging purposes
module Hakyll.Core.DirectedGraph.Dot

-- | Convert a directed graph into dot format for debugging purposes
toDot :: Ord a => (a -> String) -> DirectedGraph a -> String

-- | Write out the <tt>.dot</tt> file to a given file path. See
--   <a>toDot</a> for more information.
writeDot :: Ord a => FilePath -> (a -> String) -> DirectedGraph a -> IO ()

module Hakyll.Core.DependencyAnalyzer

-- | This data structure represents the state of the dependency analyzer.
--   It holds a complete graph in <a>analyzerGraph</a>, which always
--   contains all items, whether they are to be compiled or not.
--   
--   The <a>analyzerRemains</a> fields holds the items that still need to
--   be compiled, and <a>analyzerDone</a> holds the items which are already
--   compiled. This means that initally, <a>analyzerDone</a> is empty and
--   <a>analyzerRemains</a> contains the items which are out-of-date (or
--   items which have out-of-date dependencies).
--   
--   We also hold the dependency graph from the previous run because we
--   need it when we want to determine when an item is out-of-date. An item
--   is out-of-date when:
--   
--   <ul>
--   <li>the resource from which it compiles is out-of-date, or;</li>
--   <li>any of it's dependencies is out-of-date, or;</li>
--   <li>it's set of dependencies has changed since the previous run.</li>
--   </ul>
data DependencyAnalyzer a
DependencyAnalyzer :: DirectedGraph a -> Set a -> Set a -> DirectedGraph a -> DependencyAnalyzer a

-- | The complete dependency graph
analyzerGraph :: DependencyAnalyzer a -> DirectedGraph a

-- | A set of items yet to be compiled
analyzerRemains :: DependencyAnalyzer a -> Set a

-- | A set of items already compiled
analyzerDone :: DependencyAnalyzer a -> Set a

-- | The dependency graph from the previous run
analyzerPreviousGraph :: DependencyAnalyzer a -> DirectedGraph a
data Signal a
Build :: a -> Signal a
Cycle :: [a] -> Signal a
Done :: Signal a

-- | Construct a dependency analyzer
makeDependencyAnalyzer :: (Ord a, Show a) => DirectedGraph a -> (a -> Bool) -> DirectedGraph a -> DependencyAnalyzer a

-- | Step a dependency analyzer
step :: (Ord a, Show a) => DependencyAnalyzer a -> (Signal a, DependencyAnalyzer a)

-- | Step until done, creating a set of items we need to build -- mostly
--   used for debugging purposes
stepAll :: (Ord a, Show a) => DependencyAnalyzer a -> Maybe (Set a)
instance Show a => Show (DependencyAnalyzer a)
instance Show a => Show (Signal a)
instance (Ord a, Show a) => Monoid (DependencyAnalyzer a)


-- | Produce pretty, thread-safe logs
module Hakyll.Core.Logger

-- | Logger structure. Very complicated.
data Logger

-- | Create a new logger
makeLogger :: (String -> IO ()) -> IO Logger

-- | Flush the logger (blocks until flushed)
flushLogger :: Logger -> IO ()

-- | Start a section in the log
section :: MonadIO m => Logger -> String -> m ()

-- | Execute a monadic action and log the duration
timed :: MonadIO m => Logger -> String -> m a -> m a

-- | Log something at the same level as <a>timed</a>, but without the
--   timing
report :: MonadIO m => Logger -> String -> m ()

-- | Log an error that was thrown in the compilation phase
thrown :: MonadIO m => Logger -> String -> m ()


-- | Miscellaneous HTML manipulation functions
module Hakyll.Web.Util.Html

-- | Strip all HTML tags from a string
--   
--   Example:
--   
--   <pre>
--   stripTags "&lt;p&gt;foo&lt;/p&gt;"
--   </pre>
--   
--   Result:
--   
--   <pre>
--   "foo"
--   </pre>
--   
--   This also works for incomplete tags
--   
--   Example:
--   
--   <pre>
--   stripTags "&lt;p&gt;foo&lt;/p"
--   </pre>
--   
--   Result:
--   
--   <pre>
--   "foo"
--   </pre>
stripTags :: String -> String

-- | HTML-escape a string
--   
--   Example:
--   
--   <pre>
--   escapeHtml "Me &amp; Dean"
--   </pre>
--   
--   Result:
--   
--   <pre>
--   "Me &amp;amp; Dean"
--   </pre>
escapeHtml :: String -> String


-- | Provides utilities to manipulate URL's
module Hakyll.Web.Urls

-- | Apply a function to each URL on a webpage
withUrls :: (String -> String) -> String -> String

-- | Convert a filepath to an URL starting from the site root
--   
--   Example:
--   
--   <pre>
--   toUrl "foo/bar.html"
--   </pre>
--   
--   Result:
--   
--   <pre>
--   "/foo/bar.html"
--   </pre>
toUrl :: FilePath -> String

-- | Get the relative url to the site root, for a given (absolute) url
toSiteRoot :: String -> String

-- | Check if an URL links to an external HTTP(S) source
isExternal :: String -> Bool


-- | Miscellaneous string manipulation functions.
module Hakyll.Core.Util.String

-- | Trim a string (drop spaces, tabs and newlines at both sides).
trim :: String -> String

-- | A simple (but inefficient) regex replace funcion
replaceAll :: String -> (String -> String) -> String -> String

-- | A simple regex split function. The resulting list will contain no
--   empty strings.
splitAll :: String -> String -> [String]


-- | Various arrow utility functions
module Hakyll.Core.Util.Arrow
constA :: Arrow a => c -> a b c
sequenceA :: Arrow a => [a b c] -> a b [c]
unitA :: Arrow a => a b ()


-- | An identifier is a type used to uniquely identify a resource,
--   target...
--   
--   One can think of an identifier as something similar to a file path. An
--   identifier is a path as well, with the different elements in the path
--   separated by <tt>/</tt> characters. Examples of identifiers are:
--   
--   <ul>
--   <li><pre>posts/foo.markdown</pre></li>
--   <li><pre>index</pre></li>
--   <li><pre>error/404</pre></li>
--   </ul>
--   
--   The most important difference between an <a>Identifier</a> and a file
--   path is that the identifier for an item is not necesserily the file
--   path.
--   
--   For example, we could have an <tt>index</tt> identifier, generated by
--   Hakyll. The actual file path would be <tt>index.html</tt>, but we
--   identify it using <tt>index</tt>.
--   
--   <tt>posts/foo.markdown</tt> could be an identifier of an item that is
--   rendered to <tt>posts/foo.html</tt>. In this case, the identifier is
--   the name of the source file of the page.
--   
--   An <a>Identifier</a> carries the type of the value it identifies. This
--   basically means that an <tt>Identifier (Page String)</tt> refers to a
--   page.
--   
--   It is a phantom type parameter, meaning you can safely change this if
--   you know what you are doing. You can change the type using the
--   <a>castIdentifier</a> function.
--   
--   If the <tt>a</tt> type is not known, Hakyll traditionally uses
--   <tt>Identifier ()</tt>.
module Hakyll.Core.Identifier

-- | An identifier used to uniquely identify a value
data Identifier a
Identifier :: Maybe String -> String -> Identifier a
identifierGroup :: Identifier a -> Maybe String
identifierPath :: Identifier a -> String

-- | Discard the phantom type parameter of an identifier
castIdentifier :: Identifier a -> Identifier b

-- | Parse an identifier from a string
parseIdentifier :: String -> Identifier a

-- | Convert an identifier to a relative <a>FilePath</a>
toFilePath :: Identifier a -> FilePath

-- | Set the identifier group for some identifier
setGroup :: Maybe String -> Identifier a -> Identifier a
instance Typeable1 Identifier
instance Eq (Identifier a)
instance Ord (Identifier a)
instance IsString (Identifier a)
instance Show (Identifier a)
instance Binary (Identifier a)
instance Monoid (Identifier a)


-- | Module providing pattern matching and capturing on <a>Identifier</a>s.
--   <a>Pattern</a>s come in two kinds:
--   
--   <ul>
--   <li>Simple glob patterns, like <tt>foo/*</tt>;</li>
--   <li>Custom, arbitrary predicates of the type <tt>Identifier -&gt;
--   Bool</tt>.</li>
--   </ul>
--   
--   They both have advantages and disadvantages. By default, globs are
--   used, unless you construct your <a>Pattern</a> using the
--   <a>predicate</a> function.
--   
--   A very simple pattern could be, for example, <tt>foo/bar</tt>. This
--   pattern will only match the exact <tt>foo/bar</tt> identifier.
--   
--   To match more than one identifier, there are different captures that
--   one can use:
--   
--   <ul>
--   <li><tt>*</tt>: matches at most one element of an identifier;</li>
--   <li><tt>**</tt>: matches one or more elements of an identifier.</li>
--   </ul>
--   
--   Some examples:
--   
--   <ul>
--   <li><tt>foo/*</tt> will match <tt>foo/bar</tt> and <tt>foo/foo</tt>,
--   but not <tt>foo/bar/qux</tt>;</li>
--   <li><tt>**</tt> will match any identifier;</li>
--   <li><tt>foo/**</tt> will match <tt>foo/bar</tt> and
--   <tt>foo/bar/qux</tt>, but not <tt>bar/foo</tt>;</li>
--   <li><tt>foo/*.html</tt> will match all HTML files in the <tt>foo/</tt>
--   directory.</li>
--   </ul>
--   
--   The <a>capture</a> function allows the user to get access to the
--   elements captured by the capture elements in the pattern.
--   
--   Like an <a>Identifier</a>, a <a>Pattern</a> also has a type parameter.
--   This is simply an extra layer of safety, and can be discarded using
--   the <a>castPattern</a> function.
module Hakyll.Core.Identifier.Pattern

-- | Type that allows matching on identifiers
data Pattern a

-- | Discard the phantom type parameter
castPattern :: Pattern a -> Pattern b

-- | Parse a pattern from a string
parseGlob :: String -> Pattern a

-- | Create a <a>Pattern</a> from an arbitrary predicate
--   
--   Example:
--   
--   <pre>
--   predicate (\i -&gt; matches "foo/*" i &amp;&amp; not (matches "foo/bar" i))
--   </pre>
predicate :: (Identifier a -> Bool) -> Pattern a

-- | Create a <a>Pattern</a> from a list of <a>Identifier</a>s it should
--   match
list :: [Identifier a] -> Pattern a

-- | Create a <a>Pattern</a> from a regex
--   
--   Example:
--   
--   <pre>
--   regex "^foo/[^x]*$
--   </pre>
regex :: String -> Pattern a

-- | Create a <a>Pattern</a> which matches if the identifier is in a
--   certain group (or in no group)
inGroup :: Maybe String -> Pattern a

-- | Inverts a pattern, e.g.
--   
--   <pre>
--   complement "foo/bar.html"
--   </pre>
--   
--   will match <i>anything</i> except <tt>"foo/bar.html"</tt>
complement :: Pattern a -> Pattern a

-- | Check if an identifier matches a pattern
matches :: Pattern a -> Identifier a -> Bool

-- | Given a list of identifiers, retain only those who match the given
--   pattern
filterMatches :: Pattern a -> [Identifier a] -> [Identifier a]

-- | Match a glob against a pattern, generating a list of captures
capture :: Pattern a -> Identifier a -> Maybe [String]

-- | Create an identifier from a pattern by filling in the captures with a
--   given string
--   
--   Example:
--   
--   <pre>
--   fromCapture (parseGlob "tags/*") "foo"
--   </pre>
--   
--   Result:
--   
--   <pre>
--   "tags/foo"
--   </pre>
fromCapture :: Pattern a -> String -> Identifier a

-- | Create an identifier from a pattern by filling in the captures with
--   the given list of strings
fromCaptures :: Pattern a -> [String] -> Identifier a
instance Eq GlobComponent
instance Show GlobComponent
instance Monoid (Pattern a)
instance IsString (Pattern a)


-- | Module exporting the simple <a>Resource</a> type
module Hakyll.Core.Resource

-- | A resource
newtype Resource
Resource :: String -> Resource
unResource :: Resource -> String

-- | Create a resource from an identifier
fromIdentifier :: Identifier a -> Resource

-- | Map the resource to an identifier. Note that the group will not be
--   set!
toIdentifier :: Resource -> Identifier a
instance Eq Resource
instance Show Resource
instance Ord Resource


-- | Once a target is compiled, the user usually wants to save it to the
--   disk. This is where the <a>Routes</a> type comes in; it determines
--   where a certain target should be written.
--   
--   Suppose we have an item <tt>foo/bar.markdown</tt>. We can render this
--   to <tt>foo/bar.html</tt> using:
--   
--   <pre>
--   route "foo/bar.markdown" (setExtension ".html")
--   </pre>
--   
--   If we do not want to change the extension, we can use <a>idRoute</a>,
--   the simplest route available:
--   
--   <pre>
--   route "foo/bar.markdown" idRoute
--   </pre>
--   
--   That will route <tt>foo/bar.markdown</tt> to
--   <tt>foo/bar.markdown</tt>.
--   
--   Note that the extension says nothing about the content! If you set the
--   extension to <tt>.html</tt>, it is your own responsibility to ensure
--   that the content is indeed HTML.
--   
--   Finally, some special cases:
--   
--   <ul>
--   <li>If there is no route for an item, this item will not be routed, so
--   it will not appear in your site directory.</li>
--   <li>If an item matches multiple routes, the first rule will be
--   chosen.</li>
--   </ul>
module Hakyll.Core.Routes

-- | Type used for a route
data Routes

-- | Apply a route to an identifier
runRoutes :: Routes -> Identifier a -> Maybe FilePath

-- | A route that uses the identifier as filepath. For example, the target
--   with ID <tt>foo/bar</tt> will be written to the file <tt>foo/bar</tt>.
idRoute :: Routes

-- | Set (or replace) the extension of a route.
--   
--   Example:
--   
--   <pre>
--   runRoute (setExtension "html") "foo/bar"
--   </pre>
--   
--   Result:
--   
--   <pre>
--   Just "foo/bar.html"
--   </pre>
--   
--   Example:
--   
--   <pre>
--   runRoute (setExtension "html") "posts/the-art-of-trolling.markdown"
--   </pre>
--   
--   Result:
--   
--   <pre>
--   Just "posts/the-art-of-trolling.html"
--   </pre>
setExtension :: String -> Routes

-- | Apply the route if the identifier matches the given pattern, fail
--   otherwise
matchRoute :: Pattern a -> Routes -> Routes

-- | Create a custom route. This should almost always be used with
--   <a>matchRoute</a>
customRoute :: (Identifier a -> FilePath) -> Routes

-- | Create a gsub route
--   
--   Example:
--   
--   <pre>
--   runRoutes (gsubRoute "rss/" (const "")) "tags/rss/bar.xml"
--   </pre>
--   
--   Result:
--   
--   <pre>
--   Just "tags/bar.xml"
--   </pre>
gsubRoute :: String -> (String -> String) -> Routes

-- | Compose routes so that <tt>f <a>composeRoutes</a> g</tt> is more or
--   less equivalent with <tt>f &gt;&gt;&gt; g</tt>.
--   
--   Example:
--   
--   <pre>
--   let routes = gsubRoute "rss/" (const "") `composeRoutes` setExtension "xml"
--   in runRoutes routes "tags/rss/bar"
--   </pre>
--   
--   Result:
--   
--   <pre>
--   Just "tags/bar.xml"
--   </pre>
--   
--   If the first route given fails, Hakyll will not apply the second
--   route.
composeRoutes :: Routes -> Routes -> Routes
instance Monoid Routes


-- | Describes writable items; items that can be saved to the disk
module Hakyll.Core.Writable

-- | Describes an item that can be saved to the disk
class Writable a
write :: Writable a => FilePath -> a -> IO ()
instance Writable (Identifier a)
instance Writable Html
instance Writable [Word8]
instance Writable ByteString
instance Writable ByteString
instance Writable [Char]
instance Writable ()


-- | A module containing a box datatype representing a compiled item. This
--   item can be of any type, given that a few restrictions hold:
--   
--   <ul>
--   <li>we need a <a>Typeable</a> instance to perform type-safe
--   casts;</li>
--   <li>we need a <a>Binary</a> instance so we can serialize these items
--   to the cache;</li>
--   <li>we need a <a>Writable</a> instance so the results can be
--   saved.</li>
--   </ul>
module Hakyll.Core.CompiledItem

-- | Box type for a compiled item
data CompiledItem
CompiledItem :: a -> CompiledItem

-- | Box a value into a <a>CompiledItem</a>
compiledItem :: (Binary a, Typeable a, Writable a) => a -> CompiledItem

-- | Unbox a value from a <a>CompiledItem</a>
unCompiledItem :: (Binary a, Typeable a, Writable a) => CompiledItem -> a
instance Typeable CompiledItem
instance Writable CompiledItem


-- | Module providing a function to parse a page from a file
module Hakyll.Web.Page.Read
readPage :: String -> Page String


-- | Re-exports all different template reading modules
module Hakyll.Web.Template.Read

-- | Construct a <tt>Template</tt> from a string.
readTemplate :: String -> Template

-- | Read a hamlet template using the default settings
readHamletTemplate :: String -> Template

-- | Read a hamlet template using the specified settings
readHamletTemplateWith :: HamletSettings -> String -> Template


-- | Exports a datastructure for the top-level hakyll configuration
module Hakyll.Core.Configuration
data HakyllConfiguration
HakyllConfiguration :: FilePath -> FilePath -> (FilePath -> Bool) -> String -> HakyllConfiguration

-- | Directory in which the output written
destinationDirectory :: HakyllConfiguration -> FilePath

-- | Directory where hakyll's internal store is kept
storeDirectory :: HakyllConfiguration -> FilePath

-- | Function to determine ignored files
--   
--   In <a>defaultHakyllConfiguration</a>, the following files are ignored:
--   
--   <ul>
--   <li>files starting with a <tt>.</tt></li>
--   <li>files ending with a <tt>~</tt></li>
--   <li>files ending with <tt>.swp</tt></li>
--   </ul>
--   
--   Note that the files in <tt>destinationDirectory</tt> and
--   <tt>storeDirectory</tt> will also be ignored. Note that this is the
--   configuration parameter, if you want to use the test, you should use
--   <tt>shouldIgnoreFile</tt>.
ignoreFile :: HakyllConfiguration -> FilePath -> Bool

-- | Here, you can plug in a system command to upload/deploy your site.
--   
--   Example:
--   
--   <pre>
--   rsync -ave 'ssh -p 2217' _site jaspervdj@jaspervdj.be:hakyll
--   </pre>
--   
--   You can execute this by using
--   
--   <pre>
--   ./hakyll deploy
--   </pre>
deployCommand :: HakyllConfiguration -> String

-- | Check if a file should be ignored
shouldIgnoreFile :: HakyllConfiguration -> FilePath -> Bool

-- | Default configuration for a hakyll application
defaultHakyllConfiguration :: HakyllConfiguration


-- | A module containing various file utility functions
module Hakyll.Core.Util.File

-- | Given a path to a file, try to make the path writable by making all
--   directories on the path.
makeDirectories :: FilePath -> IO ()

-- | Get all contents of a directory. Note that files starting with a dot
--   (.) will be ignored.
getRecursiveContents :: Bool -> FilePath -> IO [FilePath]

-- | Check if a file is obsolete, given it's dependencies. When the file
--   does not exist, it is always obsolete. Other wise, it is obsolete if
--   any of it's dependencies has a more recent modification time than the
--   file.
isFileObsolete :: FilePath -> [FilePath] -> IO Bool

-- | Check if a file is meant for Hakyll internal use, i.e. if it is
--   located in the destination or store directory
isFileInternal :: HakyllConfiguration -> FilePath -> Bool


-- | A store for stroing and retreiving items
module Hakyll.Core.Store

-- | Data structure used for the store
data Store

-- | Result when an item from the store
data StoreGet a
Found :: a -> StoreGet a
NotFound :: StoreGet a
WrongType :: TypeRep -> TypeRep -> StoreGet a

-- | Initialize the store
makeStore :: FilePath -> IO Store

-- | Store an item
storeSet :: (Binary a, Typeable a) => Store -> String -> Identifier a -> a -> IO ()

-- | Load an item
storeGet :: (Binary a, Typeable a) => Store -> String -> Identifier a -> IO (StoreGet a)
instance Show a => Show (StoreGet a)
instance Eq a => Eq (StoreGet a)


-- | This module provides an API for resource providers. Resource providers
--   allow Hakyll to get content from resources; the type of resource
--   depends on the concrete instance.
--   
--   A resource is represented by the <a>Resource</a> type. This is
--   basically just a newtype wrapper around <tt>Identifier</tt> -- but it
--   has an important effect: it guarantees that a resource with this
--   identifier can be provided by one or more resource providers.
--   
--   Therefore, it is not recommended to read files directly -- you should
--   use the provided <a>Resource</a> methods.
module Hakyll.Core.Resource.Provider

-- | A value responsible for retrieving and listing resources
data ResourceProvider
ResourceProvider :: [Resource] -> (Resource -> IO String) -> (Resource -> IO ByteString) -> (Resource -> IO UTCTime) -> MVar (Map Resource Bool) -> ResourceProvider

-- | A list of all resources this provider is able to provide
resourceList :: ResourceProvider -> [Resource]

-- | Retrieve a certain resource as string
resourceString :: ResourceProvider -> Resource -> IO String

-- | Retrieve a certain resource as lazy bytestring
resourceLBS :: ResourceProvider -> Resource -> IO ByteString

-- | Check when a resource was last modified
resourceModificationTime :: ResourceProvider -> Resource -> IO UTCTime

-- | Cache keeping track of modified items
resourceModifiedCache :: ResourceProvider -> MVar (Map Resource Bool)

-- | Create a resource provider
makeResourceProvider :: [Resource] -> (Resource -> IO String) -> (Resource -> IO ByteString) -> (Resource -> IO UTCTime) -> IO ResourceProvider

-- | Check if a given identifier has a resource
resourceExists :: ResourceProvider -> Resource -> Bool

-- | Retrieve a digest for a given resource
resourceDigest :: ResourceProvider -> Resource -> IO ByteString

-- | Check if a resource was modified
resourceModified :: ResourceProvider -> Store -> Resource -> IO Bool


-- | This module provides a declarative DSL in which the user can specify
--   the different rules used to run the compilers.
--   
--   The convention is to just list all items in the <a>RulesM</a> monad,
--   routes and compilation rules.
--   
--   A typical usage example would be:
--   
--   <pre>
--   main = hakyll $ do
--       match "posts/*" $ do
--           route   (setExtension "html")
--           compile someCompiler
--       match "css/*" $ do
--           route   idRoute
--           compile compressCssCompiler
--   </pre>
module Hakyll.Core.Rules

-- | The monad used to compose rules
data RulesM a

-- | Simplification of the RulesM type; usually, it will not return any
--   result.
type Rules = RulesM ()

-- | Only compile/route items satisfying the given predicate
match :: Pattern a -> RulesM b -> RulesM b

-- | Greate a group of compilers
--   
--   Imagine you have a page that you want to render, but you also want the
--   raw content available on your site.
--   
--   <pre>
--   match "test.markdown" $ do
--       route $ setExtension "html"
--       compile pageCompiler
--   
--   match "test.markdown" $ do
--       route idRoute
--       compile copyPageCompiler
--   </pre>
--   
--   Will of course conflict! In this case, Hakyll will pick the first
--   matching compiler (<tt>pageCompiler</tt> in this case).
--   
--   In case you want to have them both, you can use the <a>group</a>
--   function to create a new group. For example,
--   
--   <pre>
--   match "test.markdown" $ do
--       route $ setExtension "html"
--       compile pageCompiler
--   
--   group "raw" $ do
--       match "test.markdown" $ do
--           route idRoute
--           compile copyPageCompiler
--   </pre>
--   
--   This will put the compiler for the raw content in a separate group
--   (<tt>"raw"</tt>), which causes it to be compiled as well.
group :: String -> RulesM a -> RulesM a

-- | Add a compilation rule to the rules.
--   
--   This instructs all resources to be compiled using the given compiler.
--   When no resources match the current selection, nothing will happen. In
--   this case, you might want to have a look at <a>create</a>.
compile :: (Binary a, Typeable a, Writable a) => Compiler Resource a -> RulesM (Pattern a)

-- | Add a compilation rule
--   
--   This sets a compiler for the given identifier. No resource is needed,
--   since we are creating the item from scratch. This is useful if you
--   want to create a page on your site that just takes content from other
--   items -- but has no actual content itself. Note that the group of the
--   given identifier is replaced by the group set via <a>group</a> (or
--   <a>Nothing</a>, if <a>group</a> has not been used).
create :: (Binary a, Typeable a, Writable a) => Identifier a -> Compiler () a -> RulesM (Identifier a)

-- | Add a route.
--   
--   This adds a route for all items matching the current pattern.
route :: Routes -> Rules

-- | Get a list of resources matching the current pattern. This will also
--   set the correct group to the identifiers.
resources :: RulesM [Identifier a]

-- | Apart from regular compilers, one is also able to specify
--   metacompilers. Metacompilers are a special class of compilers: they
--   are compilers which produce other compilers.
--   
--   This is needed when the list of compilers depends on something we
--   cannot know before actually running other compilers. The most typical
--   example is if we have a blogpost using tags.
--   
--   Every post has a collection of tags. For example,
--   
--   <pre>
--   post1: code, haskell
--   post2: code, random
--   </pre>
--   
--   Now, we want to create a list of posts for every tag. We cannot write
--   this down in our <a>Rules</a> DSL directly, since we don't know what
--   tags the different posts will have -- we depend on information that
--   will only be available when we are actually compiling the pages.
--   
--   The solution is simple, using <a>metaCompile</a>, we can add a
--   compiler that will parse the pages and produce the compilers needed
--   for the different tag pages.
--   
--   And indeed, we can see that the first argument to <a>metaCompile</a>
--   is a <a>Compiler</a> which produces a list of (<a>Identifier</a>,
--   <a>Compiler</a>) pairs. The idea is simple: <a>metaCompile</a>
--   produces a list of compilers, and the corresponding identifiers.
--   
--   For simple hakyll systems, it is no need for this construction. More
--   formally, it is only needed when the content of one or more items
--   determines which items must be rendered.
metaCompile :: (Binary a, Typeable a, Writable a) => Compiler () [(Identifier a, Compiler () a)] -> Rules

-- | Version of <a>metaCompile</a> that allows you to specify a custom
--   identifier for the metacompiler.
metaCompileWith :: (Binary a, Typeable a, Writable a) => Identifier () -> Compiler () [(Identifier a, Compiler () a)] -> Rules

-- | Generate a fresh Identifier with a given prefix
freshIdentifier :: String -> RulesM (Identifier a)


-- | A concrete <a>ResourceProvider</a> that gets it's resources from the
--   filesystem
module Hakyll.Core.Resource.Provider.File

-- | Create a filesystem-based <a>ResourceProvider</a>
fileResourceProvider :: HakyllConfiguration -> IO ResourceProvider


-- | A Compiler manages targets and dependencies between targets
--   
--   The most distinguishing property of a <a>Compiler</a> is that it is an
--   Arrow. A compiler of the type <tt>Compiler a b</tt> is simply a
--   compilation phase which takes an <tt>a</tt> as input, and produces a
--   <tt>b</tt> as output.
--   
--   Compilers are chained using the <a>&gt;&gt;&gt;</a> arrow operation.
--   If we have a compiler
--   
--   <pre>
--   getResourceString :: Compiler Resource String
--   </pre>
--   
--   which reads the resource, and a compiler
--   
--   <pre>
--   readPage :: Compiler String (Page String)
--   </pre>
--   
--   we can chain these two compilers to get a
--   
--   <pre>
--   (getResourceString &gt;&gt;&gt; readPage) :: Compiler Resource (Page String)
--   </pre>
--   
--   Most compilers can be created by combining smaller compilers using
--   <a>&gt;&gt;&gt;</a>.
--   
--   More advanced constructions are also possible using arrow, and
--   sometimes these are needed. For a good introduction to arrow, you can
--   refer to
--   
--   <a>http://en.wikibooks.org/wiki/Haskell/Understanding_arrows</a>
--   
--   A construction worth writing a few paragraphs about here are the
--   <a>require</a> functions. Different variants of this function are
--   exported here, but they all serve more or less the same goal.
--   
--   When you use only <a>&gt;&gt;&gt;</a> to chain your compilers, you get
--   a linear pipeline -- it is not possible to add extra items from other
--   compilers along the way. This is where the <a>require</a> functions
--   come in.
--   
--   This function allows you to reference other items, which are then
--   added to the pipeline. Let's look at this crappy ASCII illustration
--   which represents a pretty common scenario:
--   
--   <pre>
--   read resource &gt;&gt;&gt; pandoc render &gt;&gt;&gt; layout &gt;&gt;&gt; relativize URL's
--   
--   @templates/fancy.html@
--   </pre>
--   
--   We want to construct a pipeline of compilers to go from our resource
--   to a proper webpage. However, the <tt>layout</tt> compiler takes more
--   than just the rendered page as input: it needs the
--   <tt>templates/fancy.html</tt> template as well.
--   
--   This is an example of where we need the <tt>require</tt> function. We
--   can solve this using a construction that looks like:
--   
--   <pre>
--   ... &gt;&gt;&gt; pandoc render &gt;&gt;&gt; require &gt;&gt;&gt; layout &gt;&gt;&gt; ...
--                                |
--   @templates/fancy.html@ ------/
--   </pre>
--   
--   This illustration can help us understand the type signature of
--   <a>require</a>.
--   
--   <pre>
--   require :: (Binary a, Typeable a, Writable a)
--           =&gt; Identifier a
--           -&gt; (b -&gt; a -&gt; c)
--           -&gt; Compiler b c
--   </pre>
--   
--   Let's look at it in detail:
--   
--   <pre>
--   (Binary a, Typeable a, Writable a)
--   </pre>
--   
--   These are constraints for the <tt>a</tt> type. <tt>a</tt> (the
--   template) needs to have certain properties for it to be required.
--   
--   <pre>
--   Identifier a
--   </pre>
--   
--   This is simply <tt>templates/fancy.html</tt>: the <a>Identifier</a> of
--   the item we want to <a>require</a>, in other words, the name of the
--   item we want to add to the pipeline somehow.
--   
--   <pre>
--   (b -&gt; a -&gt; c)
--   </pre>
--   
--   This is a function given by the user, specifying <i>how</i> the two
--   items shall be merged. <tt>b</tt> is the output of the previous
--   compiler, and <tt>a</tt> is the item we just required -- the template.
--   This means <tt>c</tt> will be the final output of the <a>require</a>
--   combinator.
--   
--   <pre>
--   Compiler b c
--   </pre>
--   
--   Indeed, we have now constructed a compiler which takes a <tt>b</tt>
--   and produces a <tt>c</tt>. This means that we have a linear pipeline
--   again, thanks to the <a>require</a> function. So, the <a>require</a>
--   function actually helps to reduce to complexity of Hakyll
--   applications!
--   
--   Note that require will fetch a previously compiled item: in our
--   example of the type <tt>a</tt>. It is <i>very</i> important that the
--   compiler which produced this value, produced the right type as well!
module Hakyll.Core.Compiler

-- | The compiler arrow
data Compiler a b

-- | Run a compiler, yielding the resulting target and it's dependencies.
--   This version of <a>runCompilerJob</a> also stores the result
runCompiler :: Compiler () CompileRule -> Identifier () -> ResourceProvider -> [Identifier ()] -> Routes -> Store -> Bool -> Logger -> IO (Throwing CompileRule)

-- | Get the identifier of the item that is currently being compiled
getIdentifier :: Compiler a (Identifier b)

-- | Get the resource that is currently being compiled
getResource :: Compiler a Resource

-- | Get the route we are using for this item
getRoute :: Compiler a (Maybe FilePath)

-- | Get the route for a specified item
getRouteFor :: Compiler (Identifier a) (Maybe FilePath)

-- | Get the resource we are compiling as a string
getResourceString :: Compiler Resource String

-- | Get the resource we are compiling as a lazy bytestring
getResourceLBS :: Compiler Resource ByteString

-- | Overloadable function for <a>getResourceString</a> and
--   <a>getResourceLBS</a>
getResourceWith :: (ResourceProvider -> Resource -> IO a) -> Compiler Resource a

-- | Wait until another compiler has finished before running this compiler
fromDependency :: Identifier a -> Compiler b b

-- | Variant of <a>require</a> which drops the current value
require_ :: (Binary a, Typeable a, Writable a) => Identifier a -> Compiler b a

-- | Require another target. Using this function ensures automatic handling
--   of dependencies
require :: (Binary a, Typeable a, Writable a) => Identifier a -> (b -> a -> c) -> Compiler b c

-- | Arrow-based variant of <a>require</a>
requireA :: (Binary a, Typeable a, Writable a) => Identifier a -> Compiler (b, a) c -> Compiler b c

-- | Variant of <a>requireAll</a> which drops the current value
requireAll_ :: (Binary a, Typeable a, Writable a) => Pattern a -> Compiler b [a]

-- | Require a number of targets. Using this function ensures automatic
--   handling of dependencies
requireAll :: (Binary a, Typeable a, Writable a) => Pattern a -> (b -> [a] -> c) -> Compiler b c

-- | Arrow-based variant of <a>requireAll</a>
requireAllA :: (Binary a, Typeable a, Writable a) => Pattern a -> Compiler (b, [a]) c -> Compiler b c
cached :: (Binary a, Typeable a, Writable a) => String -> Compiler Resource a -> Compiler Resource a

-- | Create an unsafe compiler from a function in IO
unsafeCompiler :: (a -> IO b) -> Compiler a b

-- | Compiler for debugging purposes
traceShowCompiler :: Show a => Compiler a a

-- | Map over a compiler
mapCompiler :: Compiler a b -> Compiler [a] [b]

-- | Log and time a compiler
timedCompiler :: String -> Compiler a b -> Compiler a b

-- | Choose a compiler by identifier
--   
--   For example, assume that most content files need to be compiled
--   normally, but a select few need an extra step in the pipeline:
--   
--   <pre>
--   compile $ pageCompiler &gt;&gt;&gt; byPattern id
--       [ ("projects.md", addProjectListCompiler)
--       , ("sitemap.md", addSiteMapCompiler)
--       ]
--   </pre>
byPattern :: Compiler a b -> [(Pattern (), Compiler a b)] -> Compiler a b

-- | Choose a compiler by extension
--   
--   Example:
--   
--   <pre>
--   match "css/*" $ do
--     route $ setExtension "css"
--     compile $ byExtension (error "Not a (S)CSS file")
--               [ (".css",  compressCssCompiler)
--               , (".scss", sass)
--               ]
--   </pre>
--   
--   This piece of code will select the <tt>compressCssCompiler</tt> for
--   <tt>.css</tt> files, and the <tt>sass</tt> compiler (defined
--   elsewhere) for <tt>.scss</tt> files.
byExtension :: Compiler a b -> [(String, Compiler a b)] -> Compiler a b


-- | A Compiler that supports unix filters.
module Hakyll.Core.UnixFilter

-- | Use a unix filter as compiler. For example, we could use the
--   <tt>rev</tt> program as a compiler.
--   
--   <pre>
--   rev :: Compiler Resource String
--   rev = getResourceString &gt;&gt;&gt; unixFilter "rev" []
--   </pre>
--   
--   A more realistic example: one can use this to call, for example, the
--   sass compiler on CSS files. More information about sass can be found
--   here:
--   
--   <a>http://sass-lang.com/</a>
--   
--   The code is fairly straightforward, given that we use <tt>.scss</tt>
--   for sass:
--   
--   <pre>
--   match "style.scss" $ do
--       route   $ setExtension "css"
--       compile $ getResourceString &gt;&gt;&gt; unixFilter "sass" ["-s", "--scss"]
--                                   &gt;&gt;&gt; arr compressCss
--   </pre>
unixFilter :: String -> [String] -> Compiler String String

-- | Variant of <a>unixFilter</a> that should be used for binary files
--   
--   <pre>
--   match "music.wav" $ do
--       route   $ setExtension "ogg"
--       compile $ getResourceLBS &gt;&gt;&gt; unixFilter "oggenc" ["-"]
--   </pre>
unixFilterLBS :: String -> [String] -> Compiler ByteString ByteString


-- | Exports simple compilers to just copy files
module Hakyll.Core.Writable.CopyFile

-- | Newtype construct around <a>FilePath</a> which will copy the file
--   directly
newtype CopyFile
CopyFile :: FilePath -> CopyFile
unCopyFile :: CopyFile -> FilePath
copyFileCompiler :: Compiler Resource CopyFile
instance Typeable CopyFile
instance Show CopyFile
instance Eq CopyFile
instance Ord CopyFile
instance Binary CopyFile
instance Writable CopyFile


-- | This module exposes a writable type <a>WritableTuple</a> which is a
--   simple newtype wrapper around a tuple.
--   
--   The idea is that, given a tuple <tt>(a, b)</tt>, <tt>a</tt> is the
--   value you actually want to save to the disk, and <tt>b</tt> is some
--   additional info that you <i>don't</i> want to save, but that you need
--   later, for example in a <a>require</a> clause.
module Hakyll.Core.Writable.WritableTuple
newtype WritableTuple a b
WritableTuple :: (a, b) -> WritableTuple a b
unWritableTuple :: WritableTuple a b -> (a, b)
writableTupleFst :: WritableTuple a b -> a
writableTupleSnd :: WritableTuple a b -> b
writableTupleCompiler :: Compiler (a, b) (WritableTuple a b)
instance Typeable2 WritableTuple
instance (Show a, Show b) => Show (WritableTuple a b)
instance (Eq a, Eq b) => Eq (WritableTuple a b)
instance (Ord a, Ord b) => Ord (WritableTuple a b)
instance (Binary a, Binary b) => Binary (WritableTuple a b)
instance Writable a => Writable (WritableTuple a b)


-- | Module used for CSS compression. The compression is currently in a
--   simple state, but would typically reduce the number of bytes by about
--   25%.
module Hakyll.Web.CompressCss

-- | Compiler form of <a>compressCss</a>
compressCssCompiler :: Compiler Resource String

-- | Compress CSS to speed up your site.
compressCss :: String -> String


-- | Provides various functions to manipulate the metadata fields of a page
module Hakyll.Web.Page.Metadata

-- | Get a metadata field. If the field does not exist, the empty string is
--   returned.
getField :: String -> Page a -> String

-- | Get a field in a <a>Maybe</a> wrapper
getFieldMaybe :: String -> Page a -> Maybe String

-- | Version of <a>trySetField</a> which overrides any previous value
setField :: String -> String -> Page a -> Page a

-- | Add a metadata field. If the field already exists, it is not
--   overwritten.
trySetField :: String -> String -> Page a -> Page a

-- | Arrow-based variant of <a>setField</a>. Because of it's type, this
--   function is very usable together with the different <a>require</a>
--   functions.
setFieldA :: Arrow a => String -> a x String -> a (Page b, x) (Page b)

-- | Set a field of a page to the contents of another page
setFieldPage :: String -> Identifier (Page String) -> Compiler (Page a) (Page a)

-- | Do something with a metadata value, but keep the old value as well. If
--   the key given is not present in the metadata, nothing will happen. If
--   the source and destination keys are the same, the value will be
--   changed (but you should use <a>changeField</a> for this purpose).
renderField :: String -> String -> (String -> String) -> Page a -> Page a

-- | Change a metadata value.
--   
--   <pre>
--   import Data.Char (toUpper)
--   changeField "title" (map toUpper)
--   </pre>
--   
--   Will put the title in UPPERCASE.
changeField :: String -> (String -> String) -> Page a -> Page a

-- | Make a copy of a metadata field (put the value belonging to a certain
--   key under some other key as well)
copyField :: String -> String -> Page a -> Page a

-- | When the metadata has a field called <tt>published</tt> in one of the
--   following formats then this function can render the date.
--   
--   <ul>
--   <li><tt>Sun, 01 Feb 2000 13:00:00 UT</tt> (RSS date format)</li>
--   <li><tt>2000-02-01T13:00:00Z</tt> (Atom date format)</li>
--   <li><tt>February 1, 2000 1:00 PM</tt> (PM is usually uppercase)</li>
--   <li><tt>February 1, 2000</tt> (assumes 12:00 AM for the time)</li>
--   </ul>
--   
--   Alternatively, when the metadata has a field called <tt>path</tt> in a
--   <tt>folder/yyyy-mm-dd-title.extension</tt> format (the convention for
--   pages) and no <tt>published</tt> metadata field set, this function can
--   render the date.
--   
--   <pre>
--   renderDateField "date" "%B %e, %Y" "Date unknown"
--   </pre>
--   
--   Will render something like <tt>January 32, 2010</tt>.
renderDateField :: String -> String -> String -> Page a -> Page a

-- | This is an extended version of <a>renderDateField</a> that allows you
--   to specify a time locale that is used for outputting the date. For
--   more details, see <a>renderDateField</a>.
renderDateFieldWith :: TimeLocale -> String -> String -> String -> Page a -> Page a

-- | Set the modification time as a field in the page
renderModificationTime :: String -> String -> Compiler (Page String) (Page String)
renderModificationTimeWith :: TimeLocale -> String -> String -> Compiler (Page String) (Page String)

-- | Copy the body of a page to a metadata field
copyBodyToField :: String -> Page String -> Page String

-- | Copy a metadata field to the page body
copyBodyFromField :: String -> Page String -> Page String

-- | Compare pages by the date and time parsed as in
--   <a>renderDateField</a>, where <a>LT</a> implies earlier, and <a>GT</a>
--   implies later. For more details, see <a>renderDateField</a>.
comparePagesByDate :: Page a -> Page a -> Ordering


-- | A module dealing with pandoc file extensions and associated file types
module Hakyll.Web.Pandoc.FileType

-- | Datatype to represent the different file types Hakyll can deal with by
--   default
data FileType
Binary :: FileType
Css :: FileType
Html :: FileType
LaTeX :: FileType
LiterateHaskell :: FileType -> FileType
Markdown :: FileType
OrgMode :: FileType
PlainText :: FileType
Rst :: FileType
Textile :: FileType

-- | Get the file type for a certain file. The type is determined by
--   extension.
fileType :: FilePath -> FileType

-- | Get the file type for the current file
getFileType :: Compiler a FileType
instance Eq FileType
instance Ord FileType
instance Show FileType
instance Read FileType


-- | Module exporting pandoc bindings
module Hakyll.Web.Pandoc

-- | Read a string using pandoc, with the default options
readPandoc :: FileType -> Maybe (Identifier a) -> String -> Pandoc

-- | Read a string using pandoc, with the supplied options
readPandocWith :: ParserState -> FileType -> Maybe (Identifier a) -> String -> Pandoc

-- | Write a document (as HTML) using pandoc, with the default options
writePandoc :: Pandoc -> String

-- | Write a document (as HTML) using pandoc, with the supplied options
writePandocWith :: WriterOptions -> Pandoc -> String

-- | Read the resource using pandoc
pageReadPandoc :: Compiler (Page String) (Page Pandoc)

-- | Read the resource using pandoc
pageReadPandocWith :: ParserState -> Compiler (Page String) (Page Pandoc)

-- | Read the resource using pandoc. This is a (rarely needed) variant,
--   which comes in very useful when the parser state is the result of some
--   arrow.
pageReadPandocWithA :: Compiler (ParserState, Page String) (Page Pandoc)

-- | Render the resource using pandoc
pageRenderPandoc :: Compiler (Page String) (Page String)

-- | Render the resource using pandoc
pageRenderPandocWith :: ParserState -> WriterOptions -> Compiler (Page String) (Page String)

-- | The default reader options for pandoc parsing in hakyll
defaultHakyllParserState :: ParserState

-- | The default writer options for pandoc rendering in hakyll
defaultHakyllWriterOptions :: WriterOptions


-- | This module provides means for reading and applying <a>Template</a>s.
--   
--   Templates are tools to convert data (pages) into a string. They are
--   perfectly suited for laying out your site.
--   
--   Let's look at an example template:
--   
--   <pre>
--   &lt;html&gt;
--       &lt;head&gt;
--           &lt;title&gt;My crazy homepage - $title$&lt;/title&gt;
--       &lt;/head&gt;
--       &lt;body&gt;
--           &lt;div id="header"&gt;
--               &lt;h1&gt;My crazy homepage - $title$&lt;/h1&gt;
--           &lt;/div&gt;
--           &lt;div id="content"&gt;
--               $body$
--           &lt;/div&gt;
--           &lt;div id="footer"&gt;
--               By reading this you agree that I now own your soul
--           &lt;/div&gt;
--       &lt;/body&gt;
--   &lt;/html&gt;
--   </pre>
--   
--   We can use this template to render a <a>Page</a> which has a body and
--   a <tt>$title$</tt> metadata field.
--   
--   As you can see, the format is very simple -- <tt>$key$</tt> is used to
--   render the <tt>$key$</tt> field from the page, everything else is
--   literally copied. If you want to literally insert <tt>"$key$"</tt>
--   into your page (for example, when you're writing a Hakyll tutorial)
--   you can use
--   
--   <pre>
--   &lt;p&gt;
--       A literal $$key$$.
--   &lt;/p&gt;
--   </pre>
--   
--   Because of it's simplicity, these templates can be used for more than
--   HTML: you could make, for example, CSS or JS templates as well.
--   
--   In addition to the native format, Hakyll also supports hamlet
--   templates. For more information on hamlet templates, please refer to:
--   <a>http://hackage.haskell.org/package/hamlet</a>. Internally, hamlet
--   templates are converted to hakyll templates -- which means that you
--   can only use variable insertion (and not all hamlet's features).
--   
--   This is an example of a valid hamlet template. You should place them
--   in files with a <tt>.hamlet</tt> extension:
--   
--   <pre>
--   !!!
--   &lt;html&gt;
--       &lt;head&gt;
--           &lt;meta charset="UTF-8"&gt;
--           &lt;title&gt; MyAweSomeCompany - #{title}
--       &lt;body&gt;
--           &lt;h1&gt; MyAweSomeCompany - #{title}
--           &lt;div id="navigation"&gt;
--               &lt;a href="/index.html"&gt; Home
--               &lt;a href="/about.html"&gt; About
--               &lt;a href="/code.html"&gt; Code
--           #{body}
--   </pre>
module Hakyll.Web.Template

-- | Datatype used for template substitutions.
data Template

-- | Substitutes <tt>$identifiers</tt> in the given <tt>Template</tt> by
--   values from the given <a>Page</a>. When a key is not found, it is left
--   as it is.
applyTemplate :: Template -> Page String -> Page String

-- | A version of <a>applyTemplate</a> which allows you to give a fallback
--   option, which can produce the value for a key if it is missing.
applyTemplateWith :: (String -> String) -> Template -> Page String -> Page String

-- | Apply a page as it's own template. This is often very useful to fill
--   in certain keys like <tt>$root</tt> and <tt>$url</tt>.
applySelf :: Page String -> Page String

-- | Read a template. If the extension of the file we're compiling is
--   <tt>.hml</tt> or <tt>.hamlet</tt>, it will be considered as a Hamlet
--   template, and parsed as such.
templateCompiler :: Compiler Resource Template

-- | Version of <a>templateCompiler</a> that enables custom settings.
templateCompilerWith :: HamletSettings -> Compiler Resource Template
applyTemplateCompiler :: Identifier Template -> Compiler (Page String) (Page String)

-- | A version of <a>applyTemplateCompiler</a> which allows you to pass a
--   function which is called for a key when it is missing.
applyTemplateCompilerWith :: (String -> String) -> Identifier Template -> Compiler (Page String) (Page String)


-- | A page is a key-value mapping, representing a page on your site
--   
--   A page is an important concept in Hakyll. It is a key-value mapping,
--   and has one field with an arbitrary type. A <a>Page</a> thus consists
--   of
--   
--   <ul>
--   <li>metadata (of the type <tt>Map String String</tt>);</li>
--   <li>the actual value (of the type <tt>a</tt>).</li>
--   </ul>
--   
--   Usually, the value will be a <a>String</a> as well, and the value will
--   be the body of the page.
--   
--   However, this is certainly no restriction. For example, <tt>Page
--   ByteString</tt> could be used to represent a binary item (e.g. an
--   image) and some metadata.
--   
--   Pages can be constructed using Haskell, but they are usually parsed
--   from a file. The file format for pages is pretty straightforward.
--   
--   <pre>
--   This is a simple page
--   consisting of two lines.
--   </pre>
--   
--   This is a valid page with two lines. If we load this in Hakyll, there
--   would be no metadata, and the body would be the given text. Let's look
--   at a page with some metadata:
--   
--   <pre>
--   ---
--   title: Alice's Adventures in Wonderland
--   author: Lewis Caroll
--   year: 1865
--   ---
--   
--   Chapter I
--   =========
--   
--   Down the Rabbit-Hole
--   --------------------
--   
--   Alice was beginning to get very tired of sitting by her sister on the bank,
--   and of having nothing to do: once or twice she had peeped into the book her
--   sister was reading, but it had no pictures or conversations in it, "and
--   what is the use of a book," thought Alice "without pictures or
--   conversation?"
--   
--   ...
--   </pre>
--   
--   As you can see, we construct a metadata header in Hakyll using
--   <tt>---</tt>. Then, we simply list all <tt>key: value</tt> pairs, and
--   end with <tt>---</tt> again. This page contains three metadata fields
--   and a body. The body is given in markdown format, which can be easily
--   rendered to HTML by Hakyll, using pandoc.
module Hakyll.Web.Page

-- | Type used to represent pages
data Page a
Page :: Map String String -> a -> Page a
pageMetadata :: Page a -> Map String String
pageBody :: Page a -> a

-- | Create a page from a body, without metadata
fromBody :: a -> Page a

-- | Create a metadata page, without a body
fromMap :: Monoid a => Map String String -> Page a

-- | Convert a page to a map. The body will be placed in the <tt>body</tt>
--   key.
toMap :: Page String -> Map String String

-- | Read a page (do not render it)
readPageCompiler :: Compiler Resource (Page String)

-- | Read a page, add default fields, substitute fields and render using
--   pandoc
pageCompiler :: Compiler Resource (Page String)

-- | A version of <a>pageCompiler</a> which allows you to specify your own
--   pandoc options
pageCompilerWith :: ParserState -> WriterOptions -> Compiler Resource (Page String)

-- | An extension of <a>pageCompilerWith</a> which allows you to specify a
--   custom pandoc transformer for the content
pageCompilerWithPandoc :: ParserState -> WriterOptions -> (Pandoc -> Pandoc) -> Compiler Resource (Page String)

-- | This is another, even more advanced version of
--   <a>pageCompilerWithPandoc</a>. This function allows you to provide an
--   arrow which is applied before the fields in a page are rendered. This
--   means you can use this extra customizable stage to add custom fields
--   which are inserted in the page.
pageCompilerWithFields :: ParserState -> WriterOptions -> (Pandoc -> Pandoc) -> Compiler (Page String) (Page String) -> Compiler Resource (Page String)

-- | Add a number of default metadata fields to a page. These fields
--   include:
--   
--   <ul>
--   <li><pre>$url$</pre></li>
--   <li><pre>$category$</pre></li>
--   <li><pre>$title$</pre></li>
--   <li><pre>$path$</pre></li>
--   </ul>
addDefaultFields :: Compiler (Page a) (Page a)


-- | Module providing BlazeHtml support for hakyll
module Hakyll.Web.Blaze

-- | Get a field from a page and convert it to HTML. This version does not
--   escape the given HTML
getFieldHtml :: String -> Page a -> Html

-- | Version of <a>getFieldHtml</a> that escapes the HTML content
getFieldHtml' :: String -> Page a -> Html

-- | Get the body as HTML
getBodyHtml :: Page String -> Html

-- | Version of <a>getBodyHtml</a> that escapes the HTML content
getBodyHtml' :: Page String -> Html


-- | A Module that allows easy rendering of RSS feeds.
--   
--   The main rendering functions (<tt>renderRss</tt>, <tt>renderAtom</tt>)
--   all assume that you pass the list of items so that the most recent
--   entry in the feed is the first item in the list.
--   
--   Also note that the pages should have (at least) the following fields
--   to produce a correct feed:
--   
--   <ul>
--   <li><tt>$title$</tt>: Title of the item</li>
--   <li><tt>$description$</tt>: Description to appear in the feed</li>
--   <li><tt>$url$</tt>: URL to the item - this is usually set
--   automatically.</li>
--   </ul>
--   
--   In addition, the posts should be named according to the rules for
--   <tt>Hakyll.Page.Metadata.renderDateField</tt>.
module Hakyll.Web.Feed

-- | This is a data structure to keep the configuration of a feed.
data FeedConfiguration
FeedConfiguration :: String -> String -> String -> String -> FeedConfiguration

-- | Title of the feed.
feedTitle :: FeedConfiguration -> String

-- | Description of the feed.
feedDescription :: FeedConfiguration -> String

-- | Name of the feed author.
feedAuthorName :: FeedConfiguration -> String

-- | Absolute root URL of the feed site (e.g.
--   <tt>http:<i></i>jaspervdj.be</tt>)
feedRoot :: FeedConfiguration -> String

-- | Render an RSS feed with a number of items.
renderRss :: FeedConfiguration -> Compiler [Page String] String

-- | Render an Atom feed with a number of items.
renderAtom :: FeedConfiguration -> Compiler [Page String] String
instance Show FeedConfiguration
instance Eq FeedConfiguration


-- | Wraps pandocs bibiliography handling
--   
--   In order to add a bibliography, you will need a bibliography file
--   (e.g. <tt>.bib</tt>) and a CSL file (<tt>.csl</tt>). Both need to be
--   compiled with their respective compilers (<a>biblioCompiler</a> and
--   <a>cslCompiler</a>). Then, you can refer to these files when you use
--   <a>pageReadPandocBiblio</a>. This function also takes a parser state
--   for completeness -- you can use <a>defaultHakyllParserState</a> if
--   you're unsure.
module Hakyll.Web.Pandoc.Biblio
data CSL
cslCompiler :: Compiler Resource CSL
newtype Biblio
Biblio :: [Reference] -> Biblio
biblioCompiler :: Compiler Resource Biblio
pageReadPandocBiblio :: ParserState -> Identifier CSL -> Identifier Biblio -> Compiler (Page String) (Page Pandoc)
instance Typeable CSL
instance Typeable Biblio
instance Binary CSL
instance Show CSL
instance Writable CSL
instance Show Biblio
instance Writable Biblio
instance Binary Biblio


-- | This module exposes a function which can relativize URL's on a
--   webpage.
--   
--   This means that one can deploy the resulting site on
--   <tt>http://example.com/</tt>, but also on
--   <tt>http://example.com/some-folder/</tt> 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
--   
--   <pre>
--   &lt;img src="/images/lolcat.png" alt="Funny zomgroflcopter" /&gt;
--   </pre>
--   
--   in a blogpost. When running this through the relativize URL's module,
--   this will result in (suppose your blogpost is located at
--   <tt>/posts/foo.html</tt>:
--   
--   <pre>
--   &lt;img src="../images/lolcat.png" alt="Funny zomgroflcopter" /&gt;
--   </pre>
module Hakyll.Web.Urls.Relativize

-- | Compiler form of <a>relativizeUrls</a> which automatically picks the
--   right root path
relativizeUrlsCompiler :: Compiler (Page String) (Page String)

-- | Relativize URL's in HTML
relativizeUrls :: String -> String -> String


-- | Module containing some specialized functions to deal with tags. This
--   Module follows certain conventions. My advice is to stick with them if
--   possible.
--   
--   More concrete: all functions in this module assume that the tags are
--   located in the <tt>tags</tt> field, and separated by commas. An
--   example file <tt>foo.markdown</tt> could look like:
--   
--   <pre>
--   ---
--   author: Philip K. Dick
--   title: Do androids dream of electric sheep?
--   tags: future, science fiction, humanoid
--   ---
--   The novel is set in a post-apocalyptic near future, where the Earth and
--   its populations have been damaged greatly by Nuclear...
--   </pre>
--   
--   All the following functions would work with such a format. In addition
--   to tags, Hakyll also supports categories. The convention when using
--   categories is to place pages in subdirectories.
--   
--   An example, the page
--   <tt>posts/coding/2010-01-28-hakyll-categories.markdown</tt> Tags or
--   categories are read using the <tt>readTags</tt> and
--   <tt>readCategory</tt> functions. This module only provides functions
--   to work with tags: categories are represented as tags. This is
--   perfectly possible: categories only have an additional restriction
--   that a page can only have one category (instead of multiple tags).
module Hakyll.Web.Tags

-- | Data about tags
data Tags a
Tags :: [(String, [Page a])] -> Tags a
tagsMap :: Tags a -> [(String, [Page a])]

-- | Higher-level function to read tags
readTagsWith :: (Page a -> [String]) -> [Page a] -> Tags a

-- | Read a tagmap using the <tt>tags</tt> metadata field
readTags :: [Page a] -> Tags a

-- | Read a tagmap using the <tt>category</tt> metadata field
readCategory :: [Page a] -> Tags a

-- | Render a tag cloud in HTML
renderTagCloud :: (String -> Identifier (Page a)) -> Double -> Double -> Compiler (Tags a) String

-- | Render a simple tag list in HTML, with the tag count next to the item
renderTagList :: (String -> Identifier (Page a)) -> Compiler (Tags a) (String)

-- | Render tags with links
renderTagsField :: String -> (String -> Identifier a) -> Compiler (Page a) (Page a)

-- | Render the category in a link
renderCategoryField :: String -> (String -> Identifier a) -> Compiler (Page a) (Page a)

-- | Sort tags using supplied function. First element of the tuple passed
--   to the comparing function is the actual tag name.
sortTagsBy :: ((String, [Page a]) -> (String, [Page a]) -> Ordering) -> Compiler (Tags a) (Tags a)

-- | Sample sorting function that compares tags case insensitively.
caseInsensitiveTags :: (String, [Page a]) -> (String, [Page a]) -> Ordering
instance Typeable1 Tags
instance Show a => Show (Tags a)
instance Writable (Tags a)
instance Binary a => Binary (Tags a)


-- | Provides an easy way to combine several pages in a list. The
--   applications are obvious:
--   
--   <ul>
--   <li>A post list on a blog</li>
--   <li>An image list in a gallery</li>
--   <li>A sitemap</li>
--   </ul>
module Hakyll.Web.Page.List

-- | Set a field of a page to a listing of pages
setFieldPageList :: ([Page String] -> [Page String]) -> Identifier Template -> String -> Pattern (Page String) -> Compiler (Page String) (Page String)

-- | Create a list of pages
pageListCompiler :: ([Page String] -> [Page String]) -> Identifier Template -> Compiler [Page String] String

-- | Sort pages chronologically. This function assumes that the pages have
--   a <tt>year-month-day-title.extension</tt> naming scheme -- as is the
--   convention in Hakyll.
chronological :: [Page a] -> [Page a]

-- | The reverse of <a>chronological</a>
recentFirst :: [Page a] -> [Page a]

-- | Deprecated, see <a>chronological</a>
sortByBaseName :: [Page a] -> [Page a]


-- | This is the module which binds it all together
module Hakyll.Core.Run

-- | Run all rules needed, return the rule set used
run :: HakyllConfiguration -> RulesM a -> IO RuleSet
instance Functor Runtime
instance Applicative Runtime
instance Monad Runtime


-- | Module providing the main hakyll function and command-line argument
--   parsing
module Hakyll.Main

-- | This usualy is the function with which the user runs the hakyll
--   compiler
hakyll :: RulesM a -> IO ()

-- | A variant of <a>hakyll</a> which allows the user to specify a custom
--   configuration
hakyllWith :: HakyllConfiguration -> RulesM a -> IO ()


-- | Top-level module exporting all modules that are interesting for the
--   user
module Hakyll
