[ANN] Stasis - not another static site framework

[Magnar Sveen]

Stasis

A Clojure library of tools for developing static web sites.

Another static site framework? Why?

Well, that's exactly it. I didn't want to use a framework. I don't like the restrained feeling I get when using them. I prefer coding things over messing around with configuration files.

I want to

• code my own pages
• set up my own configuration
• choose my own templating library
• create my own damn stylesheets

Statis offers a few functions that are pretty useful when creating static web sites.

No more. There are no batteries included.

If you want a framework that makes it really quick and easy to create a blog, you should take a look at these:

• misaki is a Jekyll inspired static site generator in Clojure.
• Madness is a static site generator, based on Enlive and Bootstrap.
• Static is a simple static site generator written in Clojure.
• Ecstatic creates static web pages and blog posts from Hiccup templates and Markdown.
• incise is an extensible static site generator written in Clojure.

They generally come with a folder where you put your blog posts in some templating language, and a set of configuration options about how to set up your blog. They often generate code for you to tweak.

Usage

The core of Stasis is two functions: serve-pages and export-pages. Both take a map from path to contents:

(def pages {"/index.html" "<h1>Welcome!</h1>"})

The basic use case is to serve these live on a local server while developing - and then exporting them as static pages to deploy on some server.

Serving live pages locally

Stasis can create a Ring handler to serve your pages.

(ns example
  (:require [stasis.core :as stasis]))

(def app (stasis/serve-pages pages))

Like with any Ring app, you point to your app in project.clj:

:ring {:handler example/app}

and start it with lein ring server-headless.

Exporting the pages

To export, just give Stasis some pages and a target directory:

(defn export []
  (stasis/export-pages pages target-dir))

When you've got this function, you can create an alias for leiningen:

:aliases {"build-site" ["run" "-m" "example/export"]}

and run lein build-site on the command line. No need for a lein plugin.

Example apps?

The static page that prompted me to write Stasis is currently closed source, but I'm in the process of turning my 4 other static sites over. The simplest, and first to be done, is:

• whattheemacsd.com (source)

  Uses Enlive for templating, and Optimus for frontend optimization.

I'm also working on the Emacs Rocks! webpage, where I'll use hiccup instead of Enlive.

Is it stable?

It's still on a 0.x release, but I feel the API has jelled enough now to open source it. I don't expect any major changes at this point. I'll likely push it to 1.0 at the end of the month.

Again, why not use one of the existing frameworks?

I think the existing frameworks are great if they fit your style. Stasis imposes no styles. There are very few decisions made for you - no markdown vs asciidoc, no enlive vs hiccup. No configuration options. You have to make them.

So, yeah ... I think Stasis would be a great starting point if you want to create the 6th static site framework to go in that list at the top. :-)

- Magnar

[Dmitry Groshev]

And here is a link to the project, just in case you've missed it like I did: https://github.com/magnars/stasis :)

[Magnar Sveen]

Oh, look at that. Thanks! :)

--
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clo...@googlegroups.com
Note that posts from new members are moderated - please be patient with your first post.
To unsubscribe from this group, send email to
clojure+u...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
---
You received this message because you are subscribed to a topic in the Google Groups "Clojure" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/clojure/nHaYzpcQpmc/unsubscribe.
To unsubscribe from this group and all its topics, send an email to clojure+u...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

[Ryan McGowan]

Very minimalist. I appreciate that. As the author of incise I'd like to point out a few things though. :)

1. You did not specifically say that incise forced some sort of templating option though it was implied (along with the other static site generators). Incise does not force any such options on you (in fact hiccup will not even be included in incise-core in 0.2.0). It is also not specific to html file generation though there are some helpful functions built in to incise to support that very common use case. The layouts feature (similar to create-page in what-the-emacs) is entirely opt in as well.
   
2. You can create your own stylesheets too. I'm not sure what this was getting at...
3. While incise does require an input directory and an output directory it is configurable.

Of course, if stasis has been around when I decided I wanted to start a blog, incise probably wouldn't be around. The two tools can be easily contrasted by this statement though:

No configuration options. You have to make them.

Incise's goal is to be extensible so someone can write an asciidoc parser (that may take some user defined configuration options) that leverages all of the other things that have already been done by integrating with it.  This makes sharing implementations easier. The stasis way to do this is for everyone to write it and integrate themselves.  Often the later is more fun and offers a bit more control, but the former is easier.

Those are my initial thoughts at least.

[Magnar Sveen]

Very minimalist. I appreciate that.

Thank you :-) And let me say that out of the five frameworks, I think Incise is the most exciting - with its focus on extensibility.

This makes sharing implementations easier. The stasis way to do this is for everyone to write it and integrate themselves.  Often the later is more fun and offers a bit more control, but the former is easier.

Agreed. Now, I prefer control and fun over ease - but that might be a bad choice in many situations.

My feeling is that both Stasis and Incise have their place, and can live happily alongside each other. Maybe Incise could even use Stasis as a lib to build its more elaborate features on top of?

- Magnar

[Ryan McGowan]

Thanks! I agree. I think they both have there uses as things stand right now.

Maybe Incise could even use Stasis as a lib to build its more elaborate features on top of?

I was thinking the same thing. Unfortunately, I think there are a few blockers right now (serving is done very differently, string content is not required). I'll have to think more about how the stasis way of serving and exporting compares to incise's.

[Magnar Sveen]

Just a heads up that Stasis 1.0.0 has been released. The API has been stable for two months now. I've built three sites with it, and I know of two other sites built with Stasis too: 

• The docs for SinonJS: http://sinonjs.org/ 
• J David Smith's blog at http://atlanis.net/blog/ 

He even wrote a blog post about it here: http://atlanis.net/blog/posts/new-site-stasis.html

So if you were on the fence because of the 0.x release, worry no more. :) Building a static site is an excellent way to have fun with Clojure, and get a lightning fast web site that can handle any amount of traffic.

- Magnar

[Jarrod Swart]

This is a cool project.  I primarily use static site generators to build the front-end for sites that I will use enlive to template inside my app.

I currently use: http://harpjs.com for this purpose because it allows easy integration of LESS and Jade which are auto recompiled & watched by the dev server.  

This allows minimal html/css/js to be handwritten then it gets compiled to the static site, from there I use only enlive for templating.  All in all it is a very fast way to create the front-end templates for web apps.

How does stasis compare to this?  Could I replicate it?  Or is this just too far from the intended workflow of Stasis?

[Magnar Sveen]

Hi Jarrod,

Sounds to me like you're using harpjs mainly as an asset pipeline replacement? Stasis doesn't care about Jade, LESS or any such thing - because that is covered by other libraries that you would use along with it. Stasis is only concerned with 1) serving your pages live in development, and then 2) exporting them to disk. All sites using Stasis that I know of use Optimus for its frontend optimization. It has a LESS asset loader, but no one has made one for Jade. I would guess you could use Twixt instead, which comes bundled with support for both Jade and LESS.

But again - if you're using harpjs mainly for its compilation, Stasis isn't a good fit. You could probably use Twixt directly instead, and do your compilation in the same process that is serving your web pages.

- Magnar

[Jarrod Swart]

Awesome, thanks for bringing these great libraries to my attention!

[Christian Johansen]

I just posted a quite long and detailed post/tutorial on using Stasis for static web sites, including integration testing of all pages, link checker ++

The post also shows off using Optimus for asset optimization, and Enlive and Hiccup for markup generation/manipulation.

http://cjohansen.no/building-static-sites-in-clojure-with-stasis

Christian