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 15writes HTML pages to the output directory. 16.Pp 17The arguments 18.Ar pages 19are page config files, which are processed in the given order. 20.Pp 21The options are as follows: 22.Bl -tag -width Ds 23.It Fl c Ar configfile 24The global configuration file, the default is "config.cfg". 25Each page configuration file inherits variables from this file. 26These variables can be overwritten per page. 27.It Fl o Ar outputdir 28The output directory, the default is "output". 29.It Fl t Ar templatesdir 30The templates directory, the default is "templates". 31.El 32.Sh DIRECTORY AND FILE STRUCTURE 33A recommended directory structure for pages, although the names can be 34anything: 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 42The 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 49The following filename prefixes are detected for template blocks and processed 50in this order: 51.Bl -tag -width Ds 52.It Qo "header." Qc 53Header block. 54.It Qo "item." Qc 55Item block. 56.It Qo "footer." Qc 57Footer block. 58.El 59.Pp 60The files are saved as output/<templatename>, for example 61templates/atom.xml/* will become: output/atom.xml. 62If a template block file does not exist then it is treated as if it was 63empty. 64.Pp 65Template directories starting with a dot (".") are ignored. 66.Pp 67The "page" templatename is special and will be used per page. 68.Sh CONFIG FILE 69A config file has a simple key=value configuration syntax, for example: 70.Bd -literal 71# this is a comment line. 72filename = example.html 73title = Example page 74description = This is an example page 75created = 2009-04-12 76updated = 2009-04-14 77.Ed 78.Pp 79The following variable names are special with their respective defaults: 80.Bl -tag -width Ds 81.It contentfile 82Path to the input content filename, by default this is the path of 83the config file with the last extension replaced to ".html". 84.It filename 85The filename or relative file path for the output file for this page. 86By default the value is the basename of the 87.Va contentfile . 88The path of the written output file is the value of 89.Va filename 90appended to the 91.Ar outputdir 92path. 93.El 94.Pp 95A line starting with # is a comment and is ignored. 96.Pp 97TABs and spaces before and after a variable name are ignored. 98TABs and spaces before a value are ignored. 99.Sh TEMPLATES 100A template (block) is text. 101Variables are replaced with the values set in the config files. 102.Pp 103The possible operators for variables are: 104.Bl -tag -width Ds 105.It $ 106Escapes a XML string, for example: < to the entity <. 107.It # 108Literal raw string value. 109.It % 110Insert contents of file of the value of the variable. 111.El 112.Pp 113For 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 129A basic usage example: 130.Bl -enum 131.It 132Create a directory for a new site: 133.Bd -literal 134mkdir newsite 135.Ed 136.It 137Copy the example pages, templates, global config file and example 138stylesheets to a directory: 139.Bd -literal 140cp -r pages templates config.cfg style.css print.css newsite/ 141.Ed 142.It 143Change the current directory to the created directory. 144.Bd -literal 145cd newsite/ 146.Ed 147.It 148Change the values in the global config.cfg file. 149.It 150If you want to modify parts of the header, like the navigation menu items, 151you can change the following two template files: 152.Bl -item -compact 153.It 154templates/page/header.html 155.It 156templates/index.html/header.html 157.El 158.It 159Create any new pages in the pages directory. 160For each config file there has to be a corresponding HTML file. 161By default this HTML file has the path of the config file, but with the last 162extension (".cfg" in this case) replaced to ".html". 163.It 164Create an output directory: 165.Bd -literal 166mkdir -p output 167.Ed 168.It 169After any modifications the following commands can be used to generate the 170output and process the pages in descending order: 171.Bd -literal 172find pages -type f -name '*.cfg' -print0 | sort -zr | xargs -0 saait 173.Ed 174.It 175Copy the modified stylesheets to the output directory also: 176.Bd -literal 177cp style.css print.css output/ 178.Ed 179.It 180Open output/index.html locally in your webbrowser to review the changes. 181.It 182To synchronize files, you can securely transfer them via SSH using rsync: 183.Bd -literal 184rsync -av output/ user@somehost:/var/www/htdocs/ 185.Ed 186.El 187.Sh TRIVIA 188The most boring static page generator. 189.Pp 190Meaning 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 hiltjo@codemadness.org