Select new platform for static generation

[oubiwann]

Tasks:

• Evaluate past and current experience of Jekyll and gh-pages for LFE docs site
• Evaluate past and current experience of Jekyll and gh-pages for LFE blog site
• Evaluate other possible static site generators
• Evaluate pros and cons of rolling an LFE static site generator
• Determine impact/possible inclusion in LFE Dragon
• Prototype an LFE static site generator (see https://github.com/lfe/docs3/issues)

There have been several emails sent to the LFE mail list, many private email conversations, comments on Twitter and in Github tickets, not to mention a slew of tickets created in several github repos (and orgs) on this topic. Perhaps most pertinent is this recent email to the list:

• https://groups.google.com/d/msg/lisp-flavoured-erlang/2qXFgqts2Uc/54O3YXrxJAAJ

In it I outline the justification for building our own static site generator. If this work is of general usefulness, it could very well end up as part of the new LFE Dragon "framework" (see Milestone 1).

It really boils down to this:

1. We very badly need to revamp our docs
2. This is not a fun job and no one wants to do it
3. The current tool chain (Ruby/Jekyll) makes this even more unpleasant for LFE/OTP devs
4. No solution meets our rather diverse and edge-casey needs
5. If someone's going to volunteer to do this job, we need to make it fun (and productive) for that person

No decision has been made yet and is pending the process of discovery going on here:

• https://github.com/lfe/docs3/issues

That project and those tickets have the assumption that "everything will work out" (which, of course, is not a given). If that does turn out to be true, then that work will be what is used to manage LFE documentation and is what we'll use to roll out our next version. If it does not turn out to be true, we will continue with the platform selection process.

[oubiwann]

Addressing task:

Evaluate past and current experience of Jekyll and gh-pages for LFE docs site

This was essentially covered in the email to the mail list linked in the ticket description above.

[yurrriq]

I know of a couple potential alternatives to Jekyll that might be more up our alley:

• Cryogen (Clojure)
• Hakyll (Haskell)

I've also had pretty good success in the past with org-publish in Emacs, but you're a Vim guy, right?

[oubiwann]

I've used Cryogen before and was pretty okay with it. There's also an Erlang one:

• lambdapad

But the real issue isn't so much what platform is a "good" or even "close" fit, but rather, how do we make document maintenance sustainable and repeatable for LFE devs. The combination of this with the fact that regardless of what we choose, we're going to have to customize the hell out of it, brings us back to the central thesis of the current effort: we need an LFE solution.

Incidentally, I'm a bit-of-everything: vim, emacs, sublime, and even atom on occasion ;-)

[oubiwann]

Addressing task:

Evaluate past and current experience of Jekyll and gh-pages for LFE blog site

The blog has been a much nicer experience, but this is not so much due to the platform as to the fact that our needs are fairly simple.

That being said, on more than on occasion @rvirding or I have wished for a feature or a change that required digging into Ruby, and we either gave up on it or slogged through some Ruby to implement a bare-minimum of the desired feature/change.

I would certainly not go through all this effort for something as straight-forward as a blog ... however ... if we do end up with an LFE static site generator, and it's easy to use, it will be wonderful to migrate the blog and then be able to easily add whatever new features we need (and accept PRs from other LFE devs who want to add features).

[yurrriq]

If we do end up creating an LFE site generation tool it could be a great way to dogfood dragon too. 😎

[oubiwann]

Addressing task:

Evaluate other possible static site generators

I've used many of these in the past (including Mason, way back in my Perl days!). More recently I've spent time with Jekyll and Cryogen. As commented earlier, the problem with all of these is that we'll end up needing to write lots of extra code or creating special cases/plugins/etc. It's just going to be more fun if we can do this in LFE.

I'm going to mark this particular task as "done" but if the LFE static gen work doesn't pan out, we can come back and un-mark this and do another round.

[yurrriq]

Sounds good to me. Seems like we can check off the next task too, as rolling our own is likely the best option at this point.

[oubiwann]

So I've recently been using the best static generator I've ever found: https://github.com/magnars/stasis

The beauty of this one? Simplicity. It makes no assumptions about anything. It simply provides a clean, logical process for:

1. gathering a site's pages into a data structure (which is transformed into routes under the covers), and
2. exporting this collection of pages to an output directory (where all the HTML is written)

[oubiwann]

See https://github.com/lfex/poise