Static web site generation

Question

I need an easy way to generate static web pages so that I can serve them up with Apache or Nginx. Currently I am using SproutCore's build tool (Abbot) to generate static pages but that is a little bit cumbersome as it is designed for building SproutCore apps, not non-SproutCore HTML pages.

Here are my requirements:

• Javascript must be combined and minified
• CSS files must be combined
• Each image / CSS / Javascript asset must have unique URL for better caching (query string isn't enough)
• Asset URL should be different only when it really changes
• Localization support thorough HTML, CSS, Javascript and image files
• Nice template engine with layouts, partials etc.

Here are possible solutions I have found:

• Create the site using Ruby on Rails, then get all resources using wget like http://usefulfor.com/ruby/2009/03/23/use-rails-to-create-a-static-site-rake-and-subversion/
• Use Middleman: http://middlemanapp.com

Any thoughts on this?

After a longish evaluation process I have decided to use Middleman. It does the trick and I love its simplicity and the fact that I can use existing Rack components with it.

Best Regards,

Pekka Mattila

Cubital

Have you tried Jekyll - github.com/mojombo/jekyll – Greedy

I have tried and I like it but it is slightly too simple to fit my needs. I want to use some of the nifty features from Rails 3.1, such as localization, asset pipeline (Sprockets), Compass, HAML templates, partials etc. My goal is to (compile when CoffeeScript) combine + minify Javascript files, (compile when using SASS) combine CSS files and make unique urls for them (for better caching). Then I want to send all static files excluding HTML files to Amazon S3. – Cubital

Look at this thread, a lot of static web site generators get mentioned: #6182132 – Mendacious

Thanks Michael. I think that I stick with Rails 3.1 + wget or Middleman. Let's see what Thomas Reynolds comments (see the answer below). – Cubital

Rails + wget I found was the simplest solution. However, the blog you mentioned used wget command that didn't get the static page file structure correct. For wget command with right file structure, check this blog post. – Absorbefacient

Answer 1

I'm the creator of Middleman and would be eager to help you get comfortable using Middleman. My main goal is to give users the power of Rails, but focused on static development. Some of the actual code of Middleman is simplified versions of Ab

Fagoting

When I reviewed all the ruby static site generators I could find ~6 months ago, middleman was easily number one. The most powerful, but also the most simple to use because of its use of good rails conventions. – Gur

Hi Thomas, nice to hear from you. I have few questions. 1) is it possible to localize your application easily? It'd be lovely to use already localized strings of Rails: github.com/svenfuchs/rails-i18n/tree/master/rails/locale. 2) What about Rails' asset pipeline? I'd like to define what assets get combined and how. All assets must have different url when they change (caching). 3) Is it possible to use CDN? I want to serve all HTML files from my server and all other resources from CDN. – Cubital

Not sure how my comment above got truncated, I'm pretty new to Stackoverflow. – Fagoting

And apparently, you can't add newlines :-p So... in one big blurb. 1) Middleman includes the Ruby i18n gem and the padrino-helpers library with provides a foundation for internationalization. However, the actual setup of generating multiple pages (usually in different prefixed folders) from a single template is a bit of configuration. I'd be happy to help you set that up. 2) We include the exact same version of Sprockets as Rails 3.1, so you have access to combination and compression. 3) We support the asset_host variable to generate custom prefixes for assets (such as Cloudfront or s3) – Fagoting

Since this was written, the i18n support has become even better. There are some explicit options and nice integration for various generation schemes. – Flatworm

Answer 2

Here's what I do:

• Ruby on Rails 3 with the High Voltage Gem, which makes it easy to serve a static page body using the common templates. It requires a simple entry in the routes (and you can use namespaces to create a hierarchy).

• Apache reverse proxy to stand-alone Passenger (which uses nginx I believe) to run the Rails app. This article describes how to configure it.

Stand-alone passenger will read the URL, see if there is a corresponding file in /public with the .html on it, and serve that. If not found, it will invoke Rails and generate the page. In essence, page caching, with the option of publishing your URLs with or without the .html. There is a section in the Passenger docs about page caching specifically.

As far as combining and minifying js and css, here's a good stackoverflow thread.

Rails has excellent i18n/l10n support.

Rails template engine is very nice to work with. And you can use HAML if you prefer.

For your 3rd and 4th points, I'm a little confused. You want css and js combined, but then you want each to have it's own URL. In Rails, the "cache => true" directive on asset tags takes care of adding a query string parameter that changes when the content does, which is a fairly traditional scheme. I'm not sure what context you are working in where that would not work. Any CDN I've ever used works fine with that, as does an web server implementing the HTTP spec correctly. Anyway, changing the actual path or file in the URL would require changing all references to it. Maybe I'm misunderstanding?

Elderberry

Thank you for this idea! My writing was misleading. I want combine all css files into one css file and all Javascript files into one js file. My idea was to have HTML and CSS with URLs to assets. The URL scheme would be something like this: cloudfrontXYZ.amazon.com/<unique id>/image.jpg. Unique id would be, for example, an SHA1 from image.jpg. – Cubital

I get that you wouldn't combine the css with the javascript. That would just be silly! I think you can follow that thread about how to combine and minify (aka scrunch) each, and let rails cache => true on the asset tags and passenger handle retagging the asset for cache-busting. Perhaps your requirements are more specific than I'm understanding, and that's why you want something unique in the path portion of the URI. In which case, yes, a simple, weak hash generator would be sufficient. Then I'd assume your page templates would be able to look up or derive the new path and re-render the HTML. – Elderberry

Answer 3

Monkeyman has the template engine you need, I think. Think of it as Middleman's little Scala brother. Nowhere as mature or feature rich yet, but we'll get there eventually. The current incarnation supports HAML, Jade, SSP for layouts, Markdown for content and a couple of other things.

Intermarry

+1 Wilfred, wow, can you tell me what advantage one gets over MiddleMan here? I am working in Scala and have grown frustrated over lack of IDE support for Scala template-engines (Scalate, Play, etc.) Assume the same here with your project, plain text no-IDE assist in Jade, SSP, etc., correct? Would love to have compile-time type safety across the board, but does not seem a reality as of early 2012... – Matchmaker

The benefit for me is that I am working on projects where we use SCAML, SSP and all of that. But you are right, you don't get a lot of support from IDEs to author SCAML templates. I use Emacs haml-mode and IntelliJ's HAML support. That helps in getting your HAML right, not the Scala part. But generally speaking, that's not the biggest issue if you precompile your templates or (as in Monkeyman) are able to hit refresh and get detailed error messages on where it went wrong. – Intermarry

Right, the lack of IDE support has me leaning toward generating static html templates with CoffeeScript & LESS generated js/css, and then "only" use Scala on the back end; i.e. no template-engine, pre-compile static html in Middleman, Rails, whatever. Saying that, I'm going to check out Monkeyman regardless, ideally one could use the same stack for everything (Scala has SBT Coffeescript & LESS, just frigging template-engine IDE support is non-existent, years after Scalate and friends came on the scene, arggghhh ;-)) – Matchmaker

Answer 4

Without any special order

• jekyll - quite simple
• middleman - a lot of funcionalities
• nanoc - a lot of funcionalities
• stasis - use controllers
• staticmatic
• frank
• gumdrop
• ruby on rails + wget
• ruby on rails + high voltage + apache reverse proxy

Sanity

Answer 5

You should probably also checkout mod_pagespeed. It will at least give you this:

• Javascript must be combined and minified
• CSS files must be combined
• Each image / CSS / Javascript asset must have unique URL for better caching (query string isn't enough)
• Asset URL should be different only when it really changes

It won't give you this:

• Localization support thorough HTML, CSS, Javascript and image files
• Nice template engine with layouts, partials etc.

Intermarry

Answer 6

You can have a look at docpad. It's written in coffeescript and runs on Nodejs. It is document based, where you write some documents and layouts, it will compile them and write them in the out directory. You can write documents in a lot of languages via plugins

It also supports multiple level of file compilation. For example from eco to markdown to html.

Another great feature of it is that you can query on other documents being generated in a document. For example in the first page, you have something like this to get all blog posts:

database.findAll({url : /posts/})

Which will return all documents having posts in their url.

Thready