GOPHERSPACE.DE - P H O X Y
gophering on codemadness.org
<- Back


# Saait: a boring HTML page generator

Last modification on 2020-07-20

Saait is the most boring static HTML page generator.

Meaning of saai (dutch): boring. Pronunciation: site

Read the README for more information about it.

I used to use »shellscripts« to generate the static pages, but realised I
wanted a small program that works on each platform consistently.  There are
many incompatibilities or unimplemented features in base tools across different
platforms: Linux, UNIX, Windows.


This site is created using saait.


## Features

* Single small binary that handles all the things. At run-time no dependency on
  other tools.
* Few lines of code (about 575 lines of C) and no dependencies except: a C
  compiler and libc.
* Works on most platforms: tested on Linux, *BSD, Windows.
* Simple template syntax.
* Uses HTML output by default, but can easily be modified to generate any
  textual content, like gopher pages, wiki pages or other kinds of documents.
* Out-of-the-box supports: creating an index page of all pages, Atom feed,
  twtxt.txt feed, sitemap.xml and urllist.txt.


## Cons

* Simple template syntax, but very basic. Requires C knowledge to extend it if
  needed.
* Only basic (no nested) template blocks supported.


## Clone

        git clone git://git.codemadness.org/saait


## Browse

You can browse the source-code at:

* https://git.codemadness.org/saait/
* gopher://codemadness.org/1/git/saait


## Download releases

Releases are available at:

* https://codemadness.org/releases/saait/
* gopher://codemadness.org/1/releases/saait


## Documentation / man page

Below is the saait(1) man page, which includes usage examples.

        
        SAAIT(1)                    General Commands Manual                      SAAIT(1)
        
        NAME
             saait  the most boring static page generator
        
        SYNOPSIS
             saait [-c configfile] [-o outputdir] [-t templatesdir] pages...
        
        DESCRIPTION
             saait writes HTML pages to the output directory.
        
             The arguments pages are page config files, which are processed in the
             given order.
        
             The options are as follows:
        
             -c configfile
                     The global configuration file, the default is "config.cfg". Each
                     page configuration file inherits variables from this file. These
                     variables can be overwritten per page.
        
             -o outputdir
                     The output directory, the default is "output".
        
             -t templatesdir
                     The templates directory, the default is "templates".
        
        DIRECTORY AND FILE STRUCTURE
             A recommended directory structure for pages, although the names can be
             anything:
             pages/001-page.cfg
             pages/001-page.html
             pages/002-page.cfg
             pages/002-page.html
        
             The directory and file structure for templates must be:
             templates//header.ext
             templates//item.ext
             templates//footer.ext
        
             The following filename prefixes are detected for template blocks and
             processed in this order:
        
             "header."
                     Header block.
        
             "item."
                     Item block.
        
             "footer."
                     Footer block.
        
             The files are saved as output/, for example
             templates/atom.xml/* will become: output/atom.xml. If a template block
             file does not exist then it is treated as if it was empty.
        
             Template directories starting with a dot (".") are ignored.
        
             The "page" templatename is special and will be used per page.
        
        CONFIG FILE
             A config file has a simple key=value configuration syntax, for example:
        
             # this is a comment line.
             filename = example.html
             title = Example page
             description = This is an example page
             created = 2009-04-12
             updated = 2009-04-14
        
             The following variable names are special with their respective defaults:
        
             contentfile
                     Path to the input content filename, by default this is the path
                     of the config file with the last extension replaced to ".html".
        
             filename
                     The filename or relative file path for the output file for this
                     page.  By default the value is the basename of the contentfile.
                     The path of the written output file is the value of filename
                     appended to the outputdir path.
        
             A line starting with # is a comment and is ignored.
        
             TABs and spaces before and after a variable name are ignored.  TABs and
             spaces before a value are ignored.
        
        TEMPLATES
             A template (block) is text.  Variables are replaced with the values set
             in the config files.
        
             The possible operators for variables are:
        
             $             Escapes a XML string, for example: < to the entity <.
        
             #             Literal raw string value.
        
             %             Insert contents of file of the value of the variable.
        
             For example in a HTML item template:
        
             

                     

                             

${title}


                             


                                     Last modification on 
                                     ${updated}
                             


                     

                     %{contentfile}
             

        
        EXIT STATUS
             The saait utility exits 0 on success, and >0 if an error occurs.
        
        EXAMPLES
             A basic usage example:
        
             1.   Create a directory for a new site:
        
                  mkdir newsite
        
             2.   Copy the example pages, templates, global config file and example
                  stylesheets to a directory:
        
                  cp -r pages templates config.cfg style.css print.css newsite/
        
             3.   Change the current directory to the created directory.
        
                  cd newsite/
        
             4.   Change the values in the global config.cfg file.
        
             5.   If you want to modify parts of the header, like the navigation menu
                  items, you can change the following two template files:
                  templates/page/header.html
                  templates/index.html/header.html
        
             6.   Create any new pages in the pages directory. For each config file
                  there has to be a corresponding HTML file.  By default this HTML
                  file has the path of the config file, but with the last extension
                  (".cfg" in this case) replaced to ".html".
        
             7.   Create an output directory:
        
                  mkdir -p output
        
             8.   After any modifications the following commands can be used to
                  generate the output and process the pages in descending order:
        
                  find pages -type f -name '*.cfg' -print0 | sort -zr | xargs -0 saait
        
             9.   Copy the modified stylesheets to the output directory also:
        
                  cp style.css print.css output/
        
             10.  Open output/index.html locally in your webbrowser to review the
                  changes.
        
             11.  To synchronize files, you can securely transfer them via SSH using
                  rsync:
        
                  rsync -av output/ user@somehost:/var/www/htdocs/
        
        TRIVIA
             The most boring static page generator.
        
             Meaning of saai (dutch): boring, pronunciation of saait: site
        
        SEE ALSO
             find(1), sort(1), xargs(1)
        
        AUTHORS
             Hiltjo Posthuma