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!
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.
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
.
The default directory structure for a Soapbox project looks like this:
+-- build.sbt
|
+--project
| |
| +--soapbox.sbt
| +--Templates.scala
|
+--lib
| |
| +--bootstrap-3.2-dist
| | |
| | +--css
| | +--fonts
| | +--js
| |
| +--highlight
| | |
| |
| +--reveal
| |
|
+--src
| |
| +--site
| |
| +-- blog.txt
| +-- tree of markdown, css, js, image and other files
|
+--target
|
+--site
|
+-- generated web site
This contains the main settings for the site. For example:
siteDomain := "notes.langdale.com.au"
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.langdale.com.au/contacts/adv.html"
)
)
See the task and setting reference or here.
This endows sbt with the desired version of soapbox. It has one line:
addSbtPlugin("au.com.langdale" % "soapbox" % "0.5")
Place a copy or clone of twitter bootstrap, reveal.js, highlight.js
and/or other such libraries in subdirectories of 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 their pathnames relative to their subdirectory of lib.
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 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.
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.
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]
.
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!
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