saait
-----

The most boring static page generator.

Meaning of saai (dutch): boring
Pronounciation:          site

Some parts are intentionally hardcoded in C for simplicity.


Build and install
-----------------

$ make
# make install


Dependencies
------------

- C compiler (C99), tested on gcc and clang.
- libc
- POSIX make (optional).
- mandoc for documentation: https://mdocml.bsd.lv/ (optional).


Tested and works on
-------------------

- OpenBSD
- Linux (glibc).
- Windows (mingw and cygwin).


Documentation
-------------

See the man page of saait(1).


Man page
--------

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 .cfg 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 the values from this file.  The
	     values 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, but the names can be
     anything:
     pages/001-page.cfg
     pages/001-page.html
     pages/002-page.cfg
     pages/002-page.html

     The directory and files structure for templates must be:
     templates/<templatename>/header.ext
     templates/<templatename>/item.ext
     templates/<templatename>/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/<templatename>, for example
     templates/atom.xml/* will become: output/atom.xml .  If a filename does
     not exist then the template block is not processed and will be the same
     result as if it was an empty file.

     Hidden template directories (starting with ".") are ignored.

     The templatename "page" is special and will be used per page.

CFG FILE
     A .cfg file has a simple key=value configuration syntax, for example:

     # an example page.
     filename=example.html
     title=Example page
     description=This is an example page
     created=2009-04-12
     updated=2009-04-14

     The following variables names are special with their respective default
     values:

     filename
	     The relative file path of the output HTML file for this page.
	     The path is relative to the outputdir.

     htmlfile
	     Path to the input HTML content filename, by default this is the
	     path of the .cfg file with .cfg replaced to .html.

     index   If set to 0 then this page is not processed for templates except
	     for the "page" template.  This can be used to hide pages from
	     templates such as index.html or from listing in an Atom feed.

     A line starting with # is ignored and can be used as a comment.

TEMPLATE SYNTAX
     The variables set in a .cfg file can be used inside templates, but not
     pages.

     The possible operators for variables are:

     $	     Escapes a XML string, for example: < to the entity &lt;.

     #	     Literal raw string value.

     %	     Insert contents of file of the value of the variable.

     For example in a HTML item template:

     <article>
	     <header>
		     <h1><a href="">${title}</a></h1>
		     <p>
			     <strong>Last modification on </strong>
			     <time datetime="${updated}">${updated}</time>
		     </p>
	     </header>
	     %{htmlfile}
     </article>

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 *.cfg file
	  there has to be a corresponding *.html file.	Optionally they can be
	  overridden with the special variable "htmlfile".  See the copied
	  example pages in this directory.

     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/

     Below is another example to use saait with Markdown:

     A possible method could be to just convert the Markdown to HTML and to
     run saait after that as usual.

     In this example it uses smu for the Markdown processor, available at:
     https://github.com/Gottox/smu :

     cd pages
     for f in *.md; do
	     smu -n < "$f" > "$(basename "$f" .md).html"
     done

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 <hiltjo@codemadness.org>
