GopherProxy

	saait.1 - saait - the most boring static page generator
	git clone git://git.codemadness.org/saait
	Log
	Files
	Refs
	README
	LICENSE
	---
	saait.1 (5001B)
	---
	1 .Dd February 16, 2020
	2 .Dt SAAIT 1
	3 .Os
	4 .Sh NAME
	5 .Nm saait
	6 .Nd the most boring static page generator
	7 .Sh SYNOPSIS
	8 .Nm
	9 .Op Fl c Ar configfile
	10 .Op Fl o Ar outputdir
	11 .Op Fl t Ar templatesdir
	12 .Ar pages...
	13 .Sh DESCRIPTION
	14 .Nm
	15 writes HTML pages to the output directory.
	16 .Pp
	17 The arguments
	18 .Ar pages
	19 are page config files, which are processed in the given order.
	20 .Pp
	21 The options are as follows:
	22 .Bl -tag -width Ds
	23 .It Fl c Ar configfile
	24 The global configuration file, the default is "config.cfg".
	25 Each page configuration file inherits variables from this file.
	26 These variables can be overwritten per page.
	27 .It Fl o Ar outputdir
	28 The output directory, the default is "output".
	29 .It Fl t Ar templatesdir
	30 The templates directory, the default is "templates".
	31 .El
	32 .Sh DIRECTORY AND FILE STRUCTURE
	33 A recommended directory structure for pages, although the names can be
	34 anything:
	35 .Bl -tag -width Ds -compact
	36 .It pages/001-page.cfg
	37 .It pages/001-page.html
	38 .It pages/002-page.cfg
	39 .It pages/002-page.html
	40 .El
	41 .Pp
	42 The directory and file structure for templates must be:
	43 .Bl -tag -width Ds -compact
	44 .It templates/<templatename>/header.ext
	45 .It templates/<templatename>/item.ext
	46 .It templates/<templatename>/footer.ext
	47 .El
	48 .Pp
	49 The following filename prefixes are detected for template blocks and pro…
	50 in this order:
	51 .Bl -tag -width Ds
	52 .It Qo "header." Qc
	53 Header block.
	54 .It Qo "item." Qc
	55 Item block.
	56 .It Qo "footer." Qc
	57 Footer block.
	58 .El
	59 .Pp
	60 The files are saved as output/<templatename>, for example
	61 templates/atom.xml/* will become: output/atom.xml.
	62 If a template block file does not exist then it is treated as if it was
	63 empty.
	64 .Pp
	65 Template directories starting with a dot (".") are ignored.
	66 .Pp
	67 The "page" templatename is special and will be used per page.
	68 .Sh CONFIG FILE
	69 A config file has a simple key=value configuration syntax, for example:
	70 .Bd -literal
	71 # this is a comment line.
	72 filename = example.html
	73 title = Example page
	74 description = This is an example page
	75 created = 2009-04-12
	76 updated = 2009-04-14
	77 .Ed
	78 .Pp
	79 The following variable names are special with their respective defaults:
	80 .Bl -tag -width Ds
	81 .It contentfile
	82 Path to the input content filename, by default this is the path of
	83 the config file with the last extension replaced to ".html".
	84 .It filename
	85 The filename or relative file path for the output file for this page.
	86 By default the value is the basename of the
	87 .Va contentfile .
	88 The path of the written output file is the value of
	89 .Va filename
	90 appended to the
	91 .Ar outputdir
	92 path.
	93 .El
	94 .Pp
	95 A line starting with # is a comment and is ignored.
	96 .Pp
	97 TABs and spaces before and after a variable name are ignored.
	98 TABs and spaces before a value are ignored.
	99 .Sh TEMPLATES
	100 A template (block) is text.
	101 Variables are replaced with the values set in the config files.
	102 .Pp
	103 The possible operators for variables are:
	104 .Bl -tag -width Ds
	105 .It $
	106 Escapes a XML string, for example: < to the entity <.
	107 .It #
	108 Literal raw string value.
	109 .It %
	110 Insert contents of file of the value of the variable.
	111 .El
	112 .Pp
	113 For example in a HTML item template:
	114 .Bd -literal
	115 <article>
	116 <header>
	117 <h1><a href="">${title}</a></h1>
	118 <p>
	119 <strong>Last modification on </strong>
	120 <time datetime="${updated}">${updated}</time>
	121 </p>
	122 </header>
	123 %{contentfile}
	124 </article>
	125 .Ed
	126 .Sh EXIT STATUS
	127 .Ex -std
	128 .Sh EXAMPLES
	129 A basic usage example:
	130 .Bl -enum
	131 .It
	132 Create a directory for a new site:
	133 .Bd -literal
	134 mkdir newsite
	135 .Ed
	136 .It
	137 Copy the example pages, templates, global config file and example
	138 stylesheets to a directory:
	139 .Bd -literal
	140 cp -r pages templates config.cfg style.css print.css newsite/
	141 .Ed
	142 .It
	143 Change the current directory to the created directory.
	144 .Bd -literal
	145 cd newsite/
	146 .Ed
	147 .It
	148 Change the values in the global config.cfg file.
	149 .It
	150 If you want to modify parts of the header, like the navigation menu item…
	151 you can change the following two template files:
	152 .Bl -item -compact
	153 .It
	154 templates/page/header.html
	155 .It
	156 templates/index.html/header.html
	157 .El
	158 .It
	159 Create any new pages in the pages directory.
	160 For each config file there has to be a corresponding HTML file.
	161 By default this HTML file has the path of the config file, but with the …
	162 extension (".cfg" in this case) replaced to ".html".
	163 .It
	164 Create an output directory:
	165 .Bd -literal
	166 mkdir -p output
	167 .Ed
	168 .It
	169 After any modifications the following commands can be used to generate t…
	170 output and process the pages in descending order:
	171 .Bd -literal
	172 find pages -type f -name '*.cfg' -print0 \| sort -zr \| xargs -0 saait
	173 .Ed
	174 .It
	175 Copy the modified stylesheets to the output directory also:
	176 .Bd -literal
	177 cp style.css print.css output/
	178 .Ed
	179 .It
	180 Open output/index.html locally in your webbrowser to review the changes.
	181 .It
	182 To synchronize files, you can securely transfer them via SSH using rsync:
	183 .Bd -literal
	184 rsync -av output/ user@somehost:/var/www/htdocs/
	185 .Ed
	186 .El
	187 .Sh TRIVIA
	188 The most boring static page generator.
	189 .Pp
	190 Meaning of saai (dutch): boring, pronunciation of saait: site
	191 .Sh SEE ALSO
	192 .Xr find 1 ,
	193 .Xr sort 1 ,
	194 .Xr xargs 1
	195 .Sh AUTHORS
	196 .An Hiltjo Posthuma Aq Mt [email protected]