Soapbox - Another Static Site Generator

Soapbox creates static web sites from markdown, images, plain HTML and other resources. It is an sbt 0.13 plugin and easy to configure via sbt settings or extend with scala code.

Here's what it can do:

Convert markdown using pegdown and copy resources into a web site.
Apply templates, which are scala functions. (Scala's XML syntax works well here.)
Generate a blog and/or a picture gallery based on the site contents.
Generate reveal.js presentations from markdown.
Conveniently incorporate Bootstrap, Highlight.js, Twitter, Disqus and Google Analytics.
Extract content from existing XHTML pages, convert it to markdown and incorporate it into the site.

Update: Now with browser reload for Chrome!

Rationale and Alternatives

There are many alternatives. Jekyll, which powers github pages, is popular and easy to use. The author has successfully deployed Jekyll for internal documentation sites and can recommend it.

In comparison, Soapbox is more scala oriented. It is easy for scala programmers to configure and extend Soapbox.

One could also use sbt with the lwm plugin or similar. In comparison, Soapbox is more specialized for web site generation.

The author started this project as SPublisher and then migrated the most useful features to the sbt environment. Some things, such as RSS, were dropped. Markdown replaces the tomcat notes utility for authoring content.

Quick Start

Create a project with the structure below. Download twitter bootstrap, reveal.js, highlight.js and/or other libraries as subdirectories of lib. (The default templates uses the libraries mentioned.)

Make sure you have sbt 0.13 or better installed and build your site:

sbt siteBuild

And admire the result in target/site.

Soapbox Project Structure

The default directory structure for a Soapbox project looks like this:

+-- build.sbt
|
+--project
|  |
|  +--soapbox.sbt
|  +--Templates.scala
|
+--lib
|  |
|  +--bootstrap
|  +--highlight.js
|  +--reveal.js
|
+--src
|  |
|  +--site
|     |
|     +-- blog.txt
|     +-- tree of markdown, css, js, image and other files
|
+--target
   |
   +--site
      |
      +-- generated web site

build.sbt

This contains the main settings for the site. For example:

siteDomain := "notes.backgroundsignal.com"

analyticsTracker := "UA-9999999-3"

disqusID := "notasvandevos"

twitterID := "a4dev"

blogPath := "index.html"

blogTitle := "Software related Notes by Arnold deVos by date"

siteMenu := Menu( "Main",
  List(
    "Home" -> "index.html", 
    "About" -> "About.html",
    "GitHub" -> "http://github.com/arnolddevos/",
    "Contact" -> "http://www.backgroundsignal.com/contacts/adv.html"
  )
)

See the task and setting reference or here.

soapbox.sbt

This endows sbt with the desired version of soapbox. It has one line:

addSbtPlugin("au.com.langdale" % "soapbox" % "0.4")

lib

Place a copy or clone of twitter bootstrap, reveal.js, highlight.js and/or other such libraries in lib.

Soapbox will copy the relevant resource files from these into the proper positions in the generated site. That is: font, style, script and image file are copied preserving relative pathnames.

Templates.scala

Templates add the page boilerplate to the bare content. They also link to style and script resources.

There are default templates that reference bootstrap, reveal.js and highlight.js. You can override these.

The simplest possible template definition looks like this:

import au.com.langdale.soapbox.Publisher._
import sbt._

object Templates extends Plugin {
  override def projectSettings = Seq(
    siteTemplates += Template("*.md", 
      (title, content) => {
        <html xmlns={XHTML}>
          <head><title>{title}</title></head>
          <body>{content}</body>
        </html>
      }
    )
  )
}

The pattern "*.md" determines which source files are expanded with this template. The template itself is a function (String, NodeSeq) => Elem.

Any number of templates can be appended to siteTemplates, each for a different set of source files. The pattern can be replaced with an explicit FileFilter. The templates need not all reside in Templates.scala. A number of .scala files can be created.

As templates are just scala functions they can be composed as required and common parts factored out. Templates can also reference tasks and settings. For example, a template might use sitePath.value to construct links.

Markdown files

Markdown files should match *.md or *.markdown.
Each will be translated to HTML and expanded into a template producing a .html file. The path of the markdown file relative to src/site is preserved in target/site.

Any file matching *.reveal is processed as markdown but expanded into a slideshow template instead of the usual page template.
Each first or second level heading in the document starts a new slide. You will need to have reveal.js installed under lib for the slideshow to work.

blog.txt

This is used to create a chronological list of pages, the blog.

2012-03-25 An_Incremental_JSON_Generator.html
2010-09-19 Querying_a_Dataset_with_Scala_s_Pattern_Matching.html
2010-09-14 Generators_in_Scala.html
2010-08-11 An_Update_to_the_Scala_Jetty_Wrapper.html
2010-04-16 Pimping_Servlet_and_Jetty.html
2009-11-14 Polyphonic_Scala_Actors_Part_2.html
2009-10-21 Polyphonic_Scala_Actors_Part_1.html

Each line gives a publication date and the pathname of a file in the generated site.

There can be a number of blog listings: all files matching *blog.txt are merged to form a combined listing.

src/site and target/site

The markdown files and all resources needed to generate the site belong under the src/site directory. There is no restriction on the directory hierarchy, which is replicated in the generated site under target/site.

It is often convenient to merge a number of directory trees to form the site. The siteSources setting can be set in build.sbt. It takes a Seq[File].

Browser Reload Support

The browserReload task depends on (ie runs) siteBuild then tells a chrome extension to refresh selected tabs. It is intended to be run continuously like this:

~browserReload

Then:

Load the chrome extension (see below).
Call up a page in your generated site (via a local web browser perhaps).
Click the "reload page if sbt sources change button".

Edit and save a source!

How to Install the Browser Reload Extension

Get the browser reload plugin:

wget https://github.com/arnolddevos/browser-reload/archive/just-the-reload-stuff.zip
unzip browser-reload-just-the-reload-stuff.zip

In google chrome (or in chromium) add the browser reload plugin.

Goto chrome://extensions/
Enable developer mode
Click "Load unpacked extension"
Select browser-reload-just-the-reload-stuff/chrome-extension

nótaí de devos