tsunami

tsunami is a self-contained static site generator written in perl. it takes a collection of markdown files (among others) and transforms them into simple, lightweight html that can be styled by the user. however, it also includes a default stylesheet.

tsunami is designed to be modified according to the needs of each site. new translation functions can be defined relatively simply, and the html structure of the generated documents is hardcoded. (this is partly to gently discourage use of this generator to produce sites loaded down with unnecessary javascript.)

this compiler is named "tsunami" because its code is a disaster.

license

unless indicated otherwise in the headers of individual files, the contents of this repository are released under the Affero General Public License v3.

dependencies

tsunami's only dependency is a working Perl 5 installation.

directory hierarchy

the first thing to understand is how your tsunami project is laid out. its root directory contains three folders (src, cfg, and out) and the scripts pub.pl and up.sh.

the src directory contains your input files. in other words, whenever you want to add something to the site, you'll do it by putting it in here. by default, it also contains the doc directory, which holds this documentation. you may want to move it somewhere else before you publish your real site, but leaving it in place won't do any harm.

• see: input files

the cfg directory contains top-level configuration for the site. currently the only items here are links and sitename. both of these files can contain comments, which are text ignored by the software that builds the site. a line can be marked as a comment by starting it with whitespace (spaces or tabs). blank lines are ignored.

• links is used to change the contents of the navigation bar just under the header. take a look at the file for a more detailed explanation of how to use it.
• sitename contains one or two lines, a title and a subtitle for the site. these are printed at the top of every page.

out only exists if you have run pub.pl at least once. it contains a generated site ready to upload. never edit files in out! any changes you make will be overwritten as soon as you regenerate the site.

build script

the program that examines the input files and generates a site from them is pub.pl. whenever you change the configuration or the contents of src, you can run pub.pl to update out to reflect the changes.

• see: using pub.pl

whenever you run pub.pl, it iterates over everything in src and builds a matching directory tree in out. it populates this tree with the “compiled” form of each file it finds. see input files for more information on this process.

pub.pl is the core of the toolchain and is the only thing you need to start a new tsunami project, as long as you remember to put the configuration and input files in the right place.

upload script

the file up.sh is a script that automates uploading your site to GitHub Pages.