vktec's simple site system.
vs3 is the spiritual successor to vsg, my super simple static site generator written in Python. vs3 aims to be even more simple, but also more powerful because it supports dynamic content.
vs3 is written in Bash, and its templating is based on Bash. However, you do not need to know how to use Bash to use vs3. Here's a sample vs3 template:
<!DOCTYPE html>
<title>
$> e "$title"
|
$> e "$site_name"
</title>
$> echo "$content"
This template creates a simple HTML page with a <title> element
containing the HTML-escaped page name and site title. In the body of
the resulting HTML, it places the non-escaped content of the page.
Pages are written in Markdown (with a few extra bits; see below), and might look something like this:
$$$
title='My page title'
$$$
# Hello, world!
This is a **Markdown** page.
The block with $$$ on either side is interpreted directly, as Bash code.
This allows you to set variables that affect the template. You can also
use the same syntax as in templates ($> code) to inject the output of
commands into your page as Markdown.
vs3 works by transforming templates and source files into Bash scripts, which it then runs to generate page content. This transformation is done automatically (ie. there is no "build" step), but the results are cached so that it is only performed when the source files are updated.
vs3 is not a CGI script, but it is designed to be easy to use
from one. It outputs the rendered page to stdout and accepts command
line arguments as normal. Because arbitrary bash code can be run in pages
and templates, you could even use CGI environment variables from within
them to create a truly dynamic website with vs3.
vs3 does not have many dependencies. It should run with most
versions of Bash (though see the security notes below), and its only other
dependency is the markdown command. If you want to use a different
Markdown implementation with a different command name, modify the source
code (don't worry, it's a tiny program).
The HTML escaping provided by vs3 is not perfect. It's not even close to perfect. HTML escaping is hard, and I've not tried to do it perfectly. Context is crucial, but here are some rules of thumb:
eshould be fine for the content of HTML tags (except<script>and<style>tags which are special and you shouldn't be using user-generated content in anyway).- Always use
attrfor setting attributes of HTML tags dynamically.attrbasically just usesewith double quotes, but you shouldn't do that manually in case a security flaw comes up and I changeattrto patch it. - Beware of command injection. If you're doing a variable expansion into a Bash command, quote it.
- Context matters. If in doubt, consult the source code.
Also, vs3 is written in Bash, for which there have been vulnerabilities in the past (ShellShock). Please ensure you are running an up-to-date version of Bash.