Ability to customize the output filepath (#94)

- Introduced `forEvery` to run a Shake action over a pattern of files when they change.
- Removed `buildHtmlMulti` (use `forEvery` with `buildHtml` instead)

CHANGELOG.md

@@ -9,6 +9,10 @@
 - MMark, extensions removed:
   - `ghcSyntaxHighlighter`: we already have `skylighting` (which supports more parsers than Haskell)
   - `obfuscateEmail`: requires JS, which is not documented.
+- API changes:
+  - Introduced `forEvery` to run a Shake action over a pattern of files when they change.
+  - Removed `buildHtmlMulti` (use `forEvery` with `buildHtml` instead)
+  - Exposed `Rib.Shake.writeFileCached`
 
 ## 0.6.0.0
 

README.md

@@ -40,9 +40,8 @@ custom framework.
 Here is how your code may look like if you were to generate your static site
 using Rib:
 
-``` haskell
--- | A generated page corresponds to either an index of sources, or an
--- individual source.
+```haskell
+-- | This will be our type representing generated pages.
 --
 -- Each `Source` specifies the parser type to use. Rib provides `MMark` and
 -- `Pandoc`; but you may define your own as well.
@@ -74,8 +73,8 @@ generateSite = do
   -- - File patterns to build
   -- - Function that will generate the HTML (see below)
   srcs <-
-    Rib.buildHtmlMulti MMark.parse [[relfile|*.md|]] $
-      renderPage . Page_Single
+    Rib.forEvery [[relfile|*.md|]] $ \srcPath ->
+      Rib.buildHtml srcPath MMark.parse $ renderPage . Page_Single
   -- Write an index.html linking to the aforementioned files.
   Rib.writeHtml [relfile|index.html|] $
     renderPage (Page_Index srcs)
@@ -88,14 +87,14 @@ renderPage page = with html_ [lang_ "en"] $ do
     title_ $ case page of
       Page_Index _ -> "My website!"
       Page_Single src -> toHtml $ title $ getMeta src
-    style_ [type_ "text/css"] $ Clay.render pageStyle
+    style_ [type_ "text/css"] $ C.render pageStyle
   body_ $ do
     with div_ [id_ "thesite"] $ do
-      with a_ [href_ "/"] "Back to Home"
-      hr_ []
+      with div_ [class_ "header"] $
+        with a_ [href_ "/"] "Back to Home"
       case page of
         Page_Index srcs -> div_ $ forM_ srcs $ \src ->
-          with li_ [class_ "links"] $ do
+          with li_ [class_ "pages"] $ do
             let meta = getMeta src
             b_ $ with a_ [href_ (Rib.sourceUrl src)] $ toHtml $ title meta
             maybe mempty renderMarkdown $ description meta
@@ -110,18 +109,20 @@ renderPage page = with html_ [lang_ "en"] $ do
 -- | Define your site CSS here
 pageStyle :: Css
 pageStyle = "div#thesite" ? do
-  margin (em 4) (pc 20) (em 1) (pc 20)
-  "li.links" ? do
-    listStyleType none
-    marginTop $ em 1
-    "b" ? fontSize (em 1.2)
-    "p" ? sym margin (px 0)
+  C.margin (em 4) (pc 20) (em 1) (pc 20)
+  ".header" ? do
+    C.marginBottom $ em 2
+  "li.pages" ? do
+    C.listStyleType C.none
+    C.marginTop $ em 1
+    "b" ? C.fontSize (em 1.2)
+    "p" ? sym C.margin (px 0)
 
 -- | Metadata in our markdown sources
 data SrcMeta
   = SrcMeta
       { title :: Text,
-        -- | Description is optional, hence it is a `Maybe`
+        -- | Description is optional, hence `Maybe`
         description :: Maybe Text
       }
   deriving (Show, Eq, Generic, FromJSON)

src/Rib/Shake.hs

@@ -9,15 +9,16 @@
 module Rib.Shake
   ( -- * Basic helpers
     buildStaticFiles,
-    buildHtmlMulti,
     buildHtml,
-    buildHtml_,
+    buildHtml',
+    forEvery,
 
     -- * Reading only
     readSource,
 
     -- * Writing only
     writeHtml,
+    writeFileCached,
 
     -- * Misc
     RibSettings (..),
@@ -100,48 +101,48 @@ readSource sourceReader k = do
     Right v ->
       pure v
 
--- | Convert the given pattern of source files into their HTML.
-buildHtmlMulti ::
-  -- | How to parse the source file
-  SourceReader repr ->
+-- | Run the given action when any file matching the patterns changes
+forEvery ::
   -- | Source file patterns (relative to `ribInputDir`)
   [Path Rel File] ->
-  -- | How to render the given source to HTML
-  (Source repr -> Html ()) ->
-  -- | Result
-  Action [Source repr]
-buildHtmlMulti parser pats r = do
+  (Path Rel File -> Action a) ->
+  Action [a]
+forEvery pats f = do
   input <- ribInputDir
   fs <- getDirectoryFiles' input pats
-  forP fs $ \k -> do
-    outfile <- liftIO $ replaceExtension ".html" k
-    buildHtml parser outfile k r
+  forP fs f
 
--- | Like `buildHtmlMulti` but operate on a single file.
---
--- Also explicitly takes the output file path.
+-- | Like buildHtml' with default outfile
 buildHtml ::
-  SourceReader repr ->
-  -- | Path to the output HTML file (relative to `ribOutputDir`)
-  Path Rel File ->
   -- | Path to the source file (relative to `ribInputDir`)
   Path Rel File ->
+  -- | How to parse the source file
+  SourceReader repr ->
+  -- | How to render the given source to HTML
   (Source repr -> Html ()) ->
   Action (Source repr)
-buildHtml parser outfile k r = do
-  src <- Source k outfile <$> readSource parser k
+buildHtml k parser r = buildHtml' k parser replaceExtHtml r
+  where
+    replaceExtHtml _ = liftIO $ replaceExtension ".html" k
+
+-- | Generate a HTML file
+buildHtml' ::
+  -- | Path to the source file (relative to `ribInputDir`)
+  Path Rel File ->
+  -- | How to parse the source file
+  SourceReader repr ->
+  -- | Output file name to use (relative to `ribOutputDir`)
+  (repr -> Action (Path Rel File)) ->
+  -- | How to render the given source to HTML
+  (Source repr -> Html ()) ->
+  Action (Source repr)
+buildHtml' k parser outfileFn r = do
+  v <- readSource parser k
+  outfile <- outfileFn v
+  let src = Source k outfile v
   writeHtml outfile $ r src
   pure src
 
--- | Like `buildHtml` but discards its result.
-buildHtml_ ::
-  SourceReader repr ->
-  Path Rel File ->
-  Path Rel File ->
-  (Source repr -> Html ()) ->
-  Action ()
-buildHtml_ parser outfile k = void . buildHtml parser outfile k
-
 -- | Write a single HTML file with the given HTML value
 --
 -- The HTML text value will be cached, so subsequent writes of the same value