zenweb 3 is a complete rewrite inspired by Jekyll. Jekyll was designed for github pages and does a great job of it. Unfortunately these design decisions don’t apply to the rest of us. Jekyll is painfully slow because it always builds everything and it only allows liquid for templating which unnecessarily restricts our ability to implement features.
zenweb 3 overcomes these issues. It uses rake to manage dependencies and only builds what is needed. It allows for any markup language to be used at any level so you’re not stuck with liquid or anything else you might not like. Extra markup languages are provided via a simple rubygems plugin system.
index.html.md.erb
will call render_erb
and then render_md
to produce index.html
)layout
configuration._config.yml
files.You can now modify the Rakefile
and set HTML_DIR
to point to the
base directory of your website. If the server is remote, prepend the
hostname with a colon:
1 |
HTML_DIR="example.com:public_html" |
Once this is set, rake push
will use rsync to publish your website
quickly and efficiently. See the tasks below for more info of what you
can do via rake.
zenweb is typically driven entirely through rake tasks. Out of the box it provides the following tasks:
run
publish
generate
push
clean
realclean
debug
Creating a new page is as simple as creating a new file. Really. That’s all there is to it. You can provide an optional YAML header but the rest of the file is just content. File extensions are used to determine how to render the file and stop rendering when they get to a file extension they don’t know.
For example, say you have the file pages/index.html.md.erb
and it
looks like this:
1 2 3 4 5 6 7 |
--- title: My Pages ... This is my website. There are many like it but this one is mine. {{ sitemap }} |
Broken down:
layout
can
come from inherited _config.yml
files.When it comes time to generate this file:
index.html.md.erb
will call render_erb
resulting in index.html.md
.index.html.md
will call render_md
resulting in index.html
.render_html
, so rendering stops..site/pages/index.html
.input filename | renderer | output filename |
---|---|---|
pages/index.html.md.erb | render_erb |
pages/index.html.md |
pages/index.html.md | render_md |
pages/index.html |
pages/index.html | N/A | .site/pages/index.html |
But it doesn’t stop there... If layout
is defined, then
_layouts/<layout-name>*
is looked up. The layout is rendered and the
contents from your page is injected into the body of the layout. If a
layout defines a layout, then the process repeats. This allows you to
organize your site as site-layout(section-layout(page-contents))
or
however you please.
File organization in zenweb is pretty easy and flexible. There is
only 1 file required to get started: the Rakefile
. It needs to contain:
1 |
Rake.application.rake_require "zenweb/tasks" |
and nearly everything else is taken care of.
A simple website might contain the following:
Rakefile
.site/...
.site
._config.yml
_includes/...
include
statements are stored here._layouts/...
index.html.md.erb
blog/_config.yml
blog/index.html.md.erb
blog/2012-01-01-post1.html.md.erb
blog/2012-01-02-post2.html.md.erb
blog/2012-01-03-post3.html.md.erb
blog/...
normal_page1.html.md
subdir/normal_page2.html.md
subdir/normal_page3.html.md
atom.xml.erb
sitemap.xml.erb
sitemap.xml
file to help search-engines index your content.robots.txt
zenweb is quite a bit lighter than jekyll. This can be seen as both a good thing and a bad thing. In some ways, zenweb does less than jekyll. In some ways this gives zenweb more flexibility and certainly more speed.
To objectify this comparison, we can look at the number of dependencies:
gem | deps |
---|---|
Jekyll | 27 |
zenweb | 8 |
Things that zenweb borrowed from jekyll:
Things zenweb doesn’t do out of the box (yet?):
date_fmt
configuration variable that is used when
creating files with YYYY-MM-DD in their filenames.Things zenweb has that jekyll doesn’t:
extra_deps
task.Build Type | Jekyll | zenweb |
---|---|---|
Full Build | 146.2s | 26.6s |
Build 1 page | 148.2s | 4.9s |
Build 0 pages | 147.3s | 2.3s |
Updating a single page on my website (~300 pages) and rsyncing all
changes to the server takes me a mere 3.3 seconds with a single rake
sync
invocation on a semi-slow café network.
Update (2023): my website is now at >2000 pages. For a single page
edit, rake sync
still takes ~3s to clean, generate, and rsync
generated pages up to the server. Time is basically limited to the
time it takes to run rsync and proportional to the number of changes.
gem install zenwebFork me on GitHub If you want to hack on zenweb, clone it from GitHub:
git clone git://github.com/seattlerb/zenweb