# 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](input-files.html)*
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](using-pub.html)*
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](input-files.html) 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](upload.html) to GitHub Pages.