From 9ad0d38f431c02e848bc675c0ff9f582d49c5e32 Mon Sep 17 00:00:00 2001 From: "Ivan N. Veselov" Date: Sat, 4 May 2013 17:48:37 +0300 Subject: Added a comment explaining "teaserContext" function. --- src/Hakyll/Web/Template/Context.hs | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/Hakyll/Web/Template/Context.hs b/src/Hakyll/Web/Template/Context.hs index 7751423..d3c228e 100644 --- a/src/Hakyll/Web/Template/Context.hs +++ b/src/Hakyll/Web/Template/Context.hs @@ -92,6 +92,9 @@ defaultContext = missingField -------------------------------------------------------------------------------- +-- | A context with "teaser" key which contain a teaser of the item. +-- The item is loaded from the given snapshot (which should be saved +-- in the user code before any templates are applied). teaserContext :: Snapshot -> Context String teaserContext snapshot = field "teaser" $ \item -> (needlePrefix teaserSeparator . itemBody) <$> -- cgit v1.2.3 From 0e6441885c8a1567b688e0fa83fd84d59f079af2 Mon Sep 17 00:00:00 2001 From: "Ivan N. Veselov" Date: Sat, 4 May 2013 17:57:51 +0300 Subject: Changed the teaser separator to "more" to use the same format as WordPress does. --- src/Hakyll/Web/Template/Context.hs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Hakyll/Web/Template/Context.hs b/src/Hakyll/Web/Template/Context.hs index d3c228e..74c2e8d 100644 --- a/src/Hakyll/Web/Template/Context.hs +++ b/src/Hakyll/Web/Template/Context.hs @@ -103,7 +103,7 @@ teaserContext snapshot = field "teaser" $ \item -> -------------------------------------------------------------------------------- teaserSeparator :: String -teaserSeparator = "" +teaserSeparator = "" -------------------------------------------------------------------------------- -- cgit v1.2.3 From 98127118fb6f9f2a08e9063cf9e635205aff3475 Mon Sep 17 00:00:00 2001 From: "Ivan N. Veselov" Date: Sat, 4 May 2013 19:13:56 +0300 Subject: Added a tutorial on using teasers functionality. --- web/tutorials/using-teasers-in-hakyll.markdown | 95 ++++++++++++++++++++++++++ 1 file changed, 95 insertions(+) create mode 100644 web/tutorials/using-teasers-in-hakyll.markdown diff --git a/web/tutorials/using-teasers-in-hakyll.markdown b/web/tutorials/using-teasers-in-hakyll.markdown new file mode 100644 index 0000000..db24bfe --- /dev/null +++ b/web/tutorials/using-teasers-in-hakyll.markdown @@ -0,0 +1,95 @@ +--- +title: Using teasers in Hakyll +author: Ivan Veselov +--- + +## Introduction + +Sometimes it is convenient to have an excerpt of a post displayed on +the index page along with a "Read more..." link to encourage your +readers to read the rest of the post. + +You can do this in Hakyll by using "teasers" functionality. + +## Marking teasers in posts + +First, you have to put a tag in your post which separates the teaser +from the rest of the article. We use `` for this to mimic +the [WordPress convention](http://codex.wordpress.org/Customizing_the_Read_More): + +``` markdown +--- +title: My teasering post +--- +In this post I'll try to explain how to use teasers. + + + +And here I am proceeding with the explanation. + +``` + +This is an HTML comment, so it doesn't have any visual impact on the +post, it is there solely for semantic purposes. + +## Referring to teasers in templates + +Now, we want to refer to the teaser in the template. We can do this +pretty intuitively by using `$teaser$` key: + +``` html +
  • + $date$ - $title$ +

    Teaser: $teaser$

    + Read more +
    • +``` + +## Gluing together + +The only thing left is to glue those things together. An important +question here is on what stage of the compilation we want to extract a +teaser. Usually, we want to use pandoc output, i.e. raw HTML without +any templates applied (since we do not want some surrounding +JavaScript or common text from the templates to be included in the +teaser). We can specify this by using snapshots: we save the snapshot +during compilation and load it to resolve `$teaser$` key later: + +``` haskell +match "posts/*" $ do + route $ setExtension ".html" + compile $ + pandocCompiler + -- save immediately after pandoc, but before the templates are applied + >>= saveSnapshot "content" + >>= loadAndApplyTemplate "templates/post.html" defaultContext + ... +``` + +You can read more about snapshots in +[Snapshots tutorial](/tutorials/05-snapshots-feeds.html). + +Then we use this snapshot while generating teasers using +`teaserContext` function: + +``` haskell + loadAndApplyTemplate + "template/postitem.html" + (teaserContext "content" <> defaultContext) + item +``` + +Here, we've just added a new context which knows how to handle +`$teaser$` key to the default context (note that we passed the same +snapshot name `"content"` which we used while saving). + +## Known issues + +Since we use an HTML comment `` to separate the teaser, +sometimes `pandoc` can "eat" the comment while converting (for example +this happens with literate Haskell source). In order to overcome this +problem you may try to use something like this as a separator: + +``` html +
    +``` -- cgit v1.2.3