sssg/README

============
*** sssg ***
============
Simple Static Site Generator (or sssg) is just what it sounds like. It's
also written in Bash. It's only meant to have the most bare bones
features, and anything further should be implemented via patches.

# Installation
--------------
To install the script, you can simply run the `install.sh` script. By
default this will install the program to `/usr/local/bin/`. If you wish
to install elsewhere, you can do so by specifying the `$PREFIX`
variable.

# Usage
-------
The basic functionality of sssg is to generate pages that use templates
(e.g. for headers and footers), so as to have static web pages, but
without redundancy on the development side.

The basic structure of an sssg project is a root directory with all the
desired HTML files, and two subdirectories:

 - `/_templates/`: used to store HTML templates
 - `/_site/`: where the generated site will be output

These are the default directory names, they can be changed by specifying
flags (see `sssg help` for more information). The sssg will parse all
HTML files found in the root directory that are not in the templates or
generated site directories, looking for includes of templates and
parsing variables.

## Templates
To include a template into an HTML file, you would simply add the line
`#/<file>` to the HTML document where `<file>` is the name of the
template file relative to the `_templates/` directory. For example,
supposing the following file structure:

  /index.html
  /_templates/footer.html
  /_templates/header.html

In order to include `header.html` into the `index.html` document, one
would write `#/header.html` within `index.html`, and likewise could be
done with `footer.html`.

## Variables
Often times we find it necessary to use certain variables in our
templates which depend upon the particular page in which they are being
used. The best example would be page titles. Therefore, variables would
be defined in each individual page, and referenced in the templates. All
variables are strings.

To define a variable in an HTML file, a section must be declared at the
beginning of the file which ends with `%%%`. Within this section,
variables are declared and defined by the syntax `<name>=<string>`. Note
that there is no need to use quotes, as everything after the `=` is
considered part of the string until the end of the line. These variables
can then be used in the template files which are imported with the
syntax `${<name>}`. For example:

index.html:
  my-title=Home Page
  %%%
  #{header.html}
  ...
  #{footer.html}

_templates/header.html:
  ...
  <title>${my-title}</title>
  ...

# Licensing
-----------
This script is licensed under the terms & conditions of the GNU GPL
version 3 or greater (see `LICENSE` file for more information).