README - saait - the most boring static page generator
(HTM) git clone git://git.codemadness.org/saait
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
README (6445B)
---
1 saait
2 -----
3
4 The most boring static page generator.
5
6 Meaning of saai (dutch): boring
7 Pronounciation: site
8
9 Some parts are intentionally hardcoded in C for simplicity.
10
11
12 Build and install
13 -----------------
14
15 $ make
16 # make install
17
18
19 Dependencies
20 ------------
21
22 - C compiler (C99), tested on gcc and clang.
23 - libc
24 - POSIX make (optional).
25 - mandoc for documentation: https://mdocml.bsd.lv/ (optional).
26
27
28 Tested and works on
29 -------------------
30
31 - OpenBSD
32 - Linux (glibc).
33 - Windows (mingw and cygwin).
34
35
36 Example of a workflow
37 ---------------------
38
39 This script monitors pages for changes and for new files in the directory then
40 regenerates static files if this happens. If successful then refreshes the
41 current window/tab in Firefox.
42
43 Dependencies: make, xdotool, entr (https://eradman.com/entrproject/).
44
45 #!/bin/sh
46 if test x"$1" = x"rebuild"; then
47 make && xdotool search --class firefox key F5
48 else
49 while :; do find pages | entr -d -p "$(readlink -f "$0")" rebuild; done
50 fi
51
52
53 Using Markdown
54 --------------
55
56 A possible method could be to just convert the Markdown to HTML and to run
57 saait after that as usual.
58
59 In this example it uses smu for the Markdown processor, available at:
60 https://github.com/Gottox/smu:
61
62 cd pages
63 for f in *.md; do
64 smu -n < "$f" > "$(basename "$f" .md).html"
65 done
66
67
68 Documentation
69 -------------
70
71 See the man page of saait(1).
72
73
74 Man page
75 --------
76
77 SAAIT(1) General Commands Manual SAAIT(1)
78
79 NAME
80 saait the most boring static page generator
81
82 SYNOPSIS
83 saait [-c configfile] [-o outputdir] [-t templatesdir] pages...
84
85 DESCRIPTION
86 saait writes HTML pages to the output directory.
87
88 The arguments pages are page config files, which are processed in the
89 given order.
90
91 The options are as follows:
92
93 -c configfile
94 The global configuration file, the default is "config.cfg". Each
95 page configuration file inherits variables from this file. These
96 variables can be overwritten per page.
97
98 -o outputdir
99 The output directory, the default is "output".
100
101 -t templatesdir
102 The templates directory, the default is "templates".
103
104 DIRECTORY AND FILE STRUCTURE
105 A recommended directory structure for pages, although the names can be
106 anything:
107 pages/001-page.cfg
108 pages/001-page.html
109 pages/002-page.cfg
110 pages/002-page.html
111
112 The directory and file structure for templates must be:
113 templates/<templatename>/header.ext
114 templates/<templatename>/item.ext
115 templates/<templatename>/footer.ext
116
117 The following filename prefixes are detected for template blocks and
118 processed in this order:
119
120 "header."
121 Header block.
122
123 "item."
124 Item block.
125
126 "footer."
127 Footer block.
128
129 The files are saved as output/<templatename>, for example
130 templates/atom.xml/* will become: output/atom.xml. If a template block
131 file does not exist then it is treated as if it was empty.
132
133 Template directories starting with a dot (".") are ignored.
134
135 The "page" templatename is special and will be used per page.
136
137 CONFIG FILE
138 A config file has a simple key=value configuration syntax, for example:
139
140 # this is a comment line.
141 filename = example.html
142 title = Example page
143 description = This is an example page
144 created = 2009-04-12
145 updated = 2009-04-14
146
147 The following variable names are special with their respective defaults:
148
149 contentfile
150 Path to the input content filename, by default this is the path
151 of the config file with the last extension replaced to ".html".
152
153 filename
154 The filename or relative file path for the output file for this
155 page. By default the value is the basename of the contentfile.
156 The path of the written output file is the value of filename
157 appended to the outputdir path.
158
159 A line starting with # is a comment and is ignored.
160
161 TABs and spaces before and after a variable name are ignored. TABs and
162 spaces before a value are ignored.
163
164 TEMPLATES
165 A template (block) is text. Variables are replaced with the values set
166 in the config files.
167
168 The possible operators for variables are:
169
170 $ Escapes a XML string, for example: < to the entity <.
171
172 # Literal raw string value.
173
174 % Insert contents of file of the value of the variable.
175
176 For example in a HTML item template:
177
178 <article>
179 <header>
180 <h1><a href="">${title}</a></h1>
181 <p>
182 <strong>Last modification on </strong>
183 <time datetime="${updated}">${updated}</time>
184 </p>
185 </header>
186 %{contentfile}
187 </article>
188
189 EXIT STATUS
190 The saait utility exits 0 on success, and >0 if an error occurs.
191
192 EXAMPLES
193 A basic usage example:
194
195 1. Create a directory for a new site:
196
197 mkdir newsite
198
199 2. Copy the example pages, templates, global config file and example
200 stylesheets to a directory:
201
202 cp -r pages templates config.cfg style.css print.css newsite/
203
204 3. Change the current directory to the created directory.
205
206 cd newsite/
207
208 4. Change the values in the global config.cfg file.
209
210 5. If you want to modify parts of the header, like the navigation menu
211 items, you can change the following two template files:
212 templates/page/header.html
213 templates/index.html/header.html
214
215 6. Create any new pages in the pages directory. For each config file
216 there has to be a corresponding HTML file. By default this HTML
217 file has the path of the config file, but with the last extension
218 (".cfg" in this case) replaced to ".html".
219
220 7. Create an output directory:
221
222 mkdir -p output
223
224 8. After any modifications the following commands can be used to
225 generate the output and process the pages in descending order:
226
227 find pages -type f -name '*.cfg' -print0 | sort -zr | xargs -0 saait
228
229 9. Copy the modified stylesheets to the output directory also:
230
231 cp style.css print.css output/
232
233 10. Open output/index.html locally in your webbrowser to review the
234 changes.
235
236 11. To synchronize files, you can securely transfer them via SSH using
237 rsync:
238
239 rsync -av output/ user@somehost:/var/www/htdocs/
240
241 TRIVIA
242 The most boring static page generator.
243
244 Meaning of saai (dutch): boring, pronunciation of saait: site
245
246 SEE ALSO
247 find(1), sort(1), xargs(1)
248
249 AUTHORS
250 Hiltjo Posthuma <hiltjo@codemadness.org>