saait.1 - saait - the most boring static page generator
HTML git clone git://git.codemadness.org/saait
DIR Log
DIR Files
DIR Refs
DIR README
DIR 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 processed
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 items,
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 last
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 the
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 hiltjo@codemadness.org