SwBuilder (Static Website Builder) is a SConstruct script to build static webpages from page contents, partials and templates. It works mainly by substituting page contents and partials into templates, so you don't need to update every page when you modify your template or partials.
- Blog support.
- Markdown support.
- Javascript/CSS minify.
- YAML metadata.
- Mustache templates.
- Various small utilities.
- Best working utilities.
- Templates: HTML templates are style files for your website. They are
incomplete HTML files with placeholders for content, partials and other stuff.
- File extension:
.templateor.blog_template. - Place content:
{{content}}. - Place partials:
{{partial: partial_name}}.
- File extension:
- Partials: Contents that are common to many pages, for example sidebars, menus.
- Metadata: Key-Value pairs (nesting is allowed) of strings.
Including global metadata and per-page metadata. User defined metadata are allowed. For example:
build_time: Time the build script run.build_time_iso: ISO format ofbuild_time.blog: Special entry for blog pages.
To use SwBuilder, install the following dependencies first:
- SCons
- Python Modules:
- json, yaml: JSON/YAML support.
- pystache: Mustache rendering.
- pytz: For timezone definitions.
- PIL: For image manipulation.
- Commandline Tools:
- LaTeX: For LaTeX rendering support.
- ImageMagick: For image manipulation.
- multimarkdown: Markdown rendering.
- uglifyjs, cleancss: JS/CSS minification.
Not all the dependencies are required, it depends on what feature you use.
-
Put the SConstruct file in the directory of your website sources. The output files will be generated in the
deployfolder, and temporary files in thetempfolder. -
Create templates along with CSS files and Javascript files.
-
Write the
SConstructfile to define your webpages. Remember that this is a python file, so feel free to use other python expressions to ease your configuration. -
Run
sconsto build your website.
A template is just a text file with extension template or blog_template.
You need to define the place to put page content by writing {{content}} in the template.
For example:
<!DOCTYPE html>
<html>
<head>
<!-- Use {{metadata-key}} to reference page metadata. -->
<title>{{title}} - My Website</title>
</head>
<body>
<h1>{{title}}</h1>
<!-- Put page content here -->
{{content}}
</body>
</html>
Each page has its contents and metadata, you can use {{key}} to refer them in your template or pages.
A page can be defined by a html file or a markdown file.
For example a html file:
<!--{
title: Page Title
key: value
nested:
key: value
}--->
<p>This is the page content</p>
<!-- yields 'value' -->
<p>{{nested.key}}</p>
<!-- Use {{ref: path}} to reference another file. -->
<a href="{{ref: folder/page.html}}">link</a>
<img src="{{ref: folder/image.png}}" />
<!-- Use {{js: path}} to include Javascript -->
<script type="text/javascript" src="{{js: script.js}}"></script>
Use <!--{ yaml contents }--> to define YAML metadata for the page, it can be referred from the page or the templates.
If your website is not directly under a domain, it's difficult to reference pages from a template.
Static Website Builder provides a useful {{ref: path}} directive, as well as {{js: path}}, they will be replaced with
the actual path (relative to current page) in the build process. For example, {{ref: a.html}} will be replaced as a.html in b.html, but ../a.html in folder/b.html.
First you should import SwBuilder. Copy site_scons to your project,
and write the following code at the beginning of your SConstruct.
from SwBuilder import *
Note that the targets files are relative to the deploy folder.
Define a partial:
Partial("name", "file.html")
Partial("name", "file.md")
Define a page:
Page("target.html", "source.html", "mytemplate.template")
Page("target.html", "source.md", "mytemplate.template")
Page("target.html", "source.html", "mytemplate.template", title = "mytitle")
Define an image or a binary file:
Image("target.png", "source.png")
Binary("target.png", "source.png")
Use TargetList and Find to defined targets by wildcard matching.
TargetList(Image, "images", Find("*.jpg", "images"))
Define a concatenated and minified Javascript/CSS file:
Javascript("target.js", ["source1.js", "source2.js"])
CSS("target.css", ["source1.css", "source2.css"])
To define blog posts, first call BlogInit:
BlogInit("blog") # Desired blog directory: 'blog'
Then, pass definition of tags as an yaml:
- name: Tag Display Name
key: tag_key
Call BlogTags to load the yaml:
BlogTags("blog/tags.yaml")
Then call BlogPost to add blog posts:
BlogPost("blog/article.md")
# Use FindFiles to add all matched files conveniently.
SourceList(BlogPost, FindFiles("blog/*.md"))
Each blog post should contain yaml metadata as follows:
title: Blog Title
blog:
permlink: permanent-link-of-the-blog
summary: short summary, not required.
date: 2009-01-01 10:12:14 Asia/Shanghai
tags: [ tag1, tah2 ]
Next, you may add images for blog:
TargetList(Image, "blog/images", Find("*.jpg", "blog/images"))
TargetList(Image, "blog/images", Find("*.png", "blog/images"))
Call BlogFinalize when all the article files are added.
BlogFinalize()
Finally, generate articles and lists:
# Generate articles with given template:
BlogGenerateArticles("template.blog_template")
# Generate article list with given template and list template.
# Mustache templated should be used in blog/index.html to render lists.
BlogGenerateList("blog/index.html", "template.blog_template")
BlogGenerateTags("blog/index.html", "template.blog_template")
Use HTML comments to create math formulas:
<!-- math: latex_code -->: in a $ ... $ environment.
<!-- lmath: latex_code --> : in a displaymath environment.
Copyright (c) 2012-2014, Donghao Ren
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
* The name of Donghao Ren may not be used to endorse or promote products
derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL DONGHAO REN BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.