Configuration (destination directories and command-line customization)

[ramanshah]

I love hakyll! First issue. :)

• Through poking around in the code and docs, I was able to understand how to configure hakyll, e.g. to publish to GitHub Pages idiomatically in just a few lines of Haskell, using hakyllWith.
• I'd love pointers on how to add custom command-line options. My particular use-case is to be able to build a few versions of my site: a "coming soon" version, a production version, and a staged version including future posts from my blogging queue. I assume one could do this with hakyllWithArgs but haven't yet figured out how to do it. If there's a tutorial handy, I haven't found it yet and would love a link.
• I think I'm going to get some hackathon time this Saturday, and I'd love to use it to help document these really great features, e.g. with simple examples. I would appreciate pointers on where such documentation should live and how to build any artifacts. The goal is to close this issue with a PR with a bit of useful new documentation. Thanks for your patience; I am fairly new to the Haskell ecosystem.

[ramanshah]

The Haddock docs for hakyll seem to have a very terse style. In the interest of respecting the style, I don't think such examples belong in there. Likely, once my blog is live, I'll write a blog post of my own covering these functions. When that happens, I'll send a PR adding my post to the "External Articles."

I'd still love any pointers on how to use hakyllWithArgs. Even a global search of open GitHub doesn't reveal any working examples.

[jaspervdj]

hakyllWithArgs is used to call Hakyll as a library, but I'm not sure if anyone is using it at this point.

I'd welcome all documentation improvements, but doing this as an external article also sounds fine!

[ramanshah]

Thanks for the info @jaspervdj . I think I just comprehended what I was stuck on but would appreciate a correction if I'm wrong:

It appears that the set of Hakyll verbs is statically fixed here. The set of verbs is baked into the algebraic type declaration of Command, so the set of behaviors from Hakyll's point of view is non-extensible. In other words, I can't add ask Hakyll to add or change a command in its list of commands.

To achieve my desired result (a few flavors of my site, configured at the command line), I'd do the following:

• Write my own main with its own command-line options and help text, e.g., with optparse-applicative.
• Use my own command-line options in my own program logic.
• Use Hakyll by marshalling my own command-line options into an Options. Patch this into hakyllWithArgs calls.

Is that about right?

It would be cool to be able to re-use some or all of Hakyll's set of commands in a custom configuration. In particular, the stuff buried inside a function here would have value in a custom Hakyll site generator. My hunch is that an applicative data structure, mirroring the applicative options parser, would deduplicate the commands in the code and make Hakyll more extensible. What's your appetite level for such a change?

[jaspervdj]

I think your approach sounds right! Let me know if Hakyll should expose more of what's going on in the command-line option parsing.

[ramanshah]

Since we last discussed, I ended up working around the customization issue by refactoring my project around the Rules monad and building three (extremely short) main executables for the three flavors of site. Like this:

SiteRules.hs

siteRules :: Rules ()
siteRules = do
    match "images/*" $ do
        route   idRoute
        compile copyFileCompiler
    -- etc.

Prelaunch.hs

prelaunchRule :: Rules ()
prelaunchRule = match "prelaunch.html" $ do
    route $ constRoute "index.html"
    compile copyFileCompiler

main :: IO ()
main = githubHakyll prelaunchRule

Production.hs

main :: IO ()
main = githubHakyll siteRules

That's adequate for my needs - so maybe what we have is good enough as long as there's enough tutorial coverage in the blogosphere?

[bergus]

@ramanshah Sure, did you write a blog post on this? :-)

What I did to distinguish production and dev/staging was to use environment variables (very useful for continuous integration), and read them through a combination of System.Environment.lookupEnv and Hakyll.unsafeCompiler.

[ramanshah]

@bergus I have written the post's content, but the site/blog is not live yet. Alas. Coming "soon" - sorry.

Thanks for the pointer on unsafeCompiler!