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.
- Author: Donghao Ren
- License: GPLv3
- Blog support.
- Markdown support.
- Javascript/CSS minify.
- YAML metadata.
- Mustache templates.
- Various small 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
- json, yaml: JSON/YAML support.
- pystache: Mustache rendering.
- pytz: For timezone definitions.
-
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
WebsiteMetafile 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.
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"])