saait.md - www.codemadness.org - www.codemadness.org saait content files
(HTM) git clone git://git.codemadness.org/www.codemadness.org
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
saait.md (7262B)
---
1 Saait is the most boring static HTML page generator.
2
3 Meaning of saai (dutch): boring. Pronunciation: site
4
5 [Read the README for more information about it.](/git/saait/file/README.html)
6
7 I used to use [shellscripts](/git/static-site-scripts/files.html) to generate the static pages, but realised I
8 wanted a small program that works on each platform consistently. There are
9 many incompatibilities or unimplemented features in base tools across different
10 platforms: Linux, UNIX, Windows.
11
12
13 This site is created using saait.
14
15
16 ## Features
17
18 * Single small binary that handles all the things. At run-time no dependency on
19 other tools.
20 * Few lines of code (about 575 lines of C) and no dependencies except: a C
21 compiler and libc.
22 * Works on most platforms: tested on Linux, *BSD, Windows.
23 * Simple template syntax.
24 * Uses HTML output by default, but can easily be modified to generate any
25 textual content, like gopher pages, wiki pages or other kinds of documents.
26 * Out-of-the-box supports: creating an index page of all pages, Atom feed,
27 twtxt.txt feed, sitemap.xml and urllist.txt.
28
29
30 ## Cons
31
32 * Simple template syntax, but very basic. Requires C knowledge to extend it if
33 needed.
34 * Only basic (no nested) template blocks supported.
35
36
37 ## Clone
38
39 git clone git://git.codemadness.org/saait
40
41
42 ## Browse
43
44 You can browse the source-code at:
45
46 * <https://git.codemadness.org/saait/>
47 * <gopher://codemadness.org/1/git/saait>
48
49
50 ## Download releases
51
52 Releases are available at:
53
54 * <https://codemadness.org/releases/saait/>
55 * <gopher://codemadness.org/1/releases/saait>
56
57
58 ## Documentation / man page
59
60 Below is the saait(1) man page, which includes usage examples.
61
62
63 SAAIT(1) General Commands Manual SAAIT(1)
64
65 NAME
66 saait the most boring static page generator
67
68 SYNOPSIS
69 saait [-c configfile] [-o outputdir] [-t templatesdir] pages...
70
71 DESCRIPTION
72 saait writes HTML pages to the output directory.
73
74 The arguments pages are page config files, which are processed in the
75 given order.
76
77 The options are as follows:
78
79 -c configfile
80 The global configuration file, the default is "config.cfg". Each
81 page configuration file inherits variables from this file. These
82 variables can be overwritten per page.
83
84 -o outputdir
85 The output directory, the default is "output".
86
87 -t templatesdir
88 The templates directory, the default is "templates".
89
90 DIRECTORY AND FILE STRUCTURE
91 A recommended directory structure for pages, although the names can be
92 anything:
93 pages/001-page.cfg
94 pages/001-page.html
95 pages/002-page.cfg
96 pages/002-page.html
97
98 The directory and file structure for templates must be:
99 templates/<templatename>/header.ext
100 templates/<templatename>/item.ext
101 templates/<templatename>/footer.ext
102
103 The following filename prefixes are detected for template blocks and
104 processed in this order:
105
106 "header."
107 Header block.
108
109 "item."
110 Item block.
111
112 "footer."
113 Footer block.
114
115 The files are saved as output/<templatename>, for example
116 templates/atom.xml/* will become: output/atom.xml. If a template block
117 file does not exist then it is treated as if it was empty.
118
119 Template directories starting with a dot (".") are ignored.
120
121 The "page" templatename is special and will be used per page.
122
123 CONFIG FILE
124 A config file has a simple key=value configuration syntax, for example:
125
126 # this is a comment line.
127 filename = example.html
128 title = Example page
129 description = This is an example page
130 created = 2009-04-12
131 updated = 2009-04-14
132
133 The following variable names are special with their respective defaults:
134
135 contentfile
136 Path to the input content filename, by default this is the path
137 of the config file with the last extension replaced to ".html".
138
139 filename
140 The filename or relative file path for the output file for this
141 page. By default the value is the basename of the contentfile.
142 The path of the written output file is the value of filename
143 appended to the outputdir path.
144
145 A line starting with # is a comment and is ignored.
146
147 TABs and spaces before and after a variable name are ignored. TABs and
148 spaces before a value are ignored.
149
150 TEMPLATES
151 A template (block) is text. Variables are replaced with the values set
152 in the config files.
153
154 The possible operators for variables are:
155
156 $ Escapes a XML string, for example: < to the entity <.
157
158 # Literal raw string value.
159
160 % Insert contents of file of the value of the variable.
161
162 For example in a HTML item template:
163
164 <article>
165 <header>
166 <h1><a href="">${title}</a></h1>
167 <p>
168 <strong>Last modification on </strong>
169 <time datetime="${updated}">${updated}</time>
170 </p>
171 </header>
172 %{contentfile}
173 </article>
174
175 EXIT STATUS
176 The saait utility exits 0 on success, and >0 if an error occurs.
177
178 EXAMPLES
179 A basic usage example:
180
181 1. Create a directory for a new site:
182
183 mkdir newsite
184
185 2. Copy the example pages, templates, global config file and example
186 stylesheets to a directory:
187
188 cp -r pages templates config.cfg style.css print.css newsite/
189
190 3. Change the current directory to the created directory.
191
192 cd newsite/
193
194 4. Change the values in the global config.cfg file.
195
196 5. If you want to modify parts of the header, like the navigation menu
197 items, you can change the following two template files:
198 templates/page/header.html
199 templates/index.html/header.html
200
201 6. Create any new pages in the pages directory. For each config file
202 there has to be a corresponding HTML file. By default this HTML
203 file has the path of the config file, but with the last extension
204 (".cfg" in this case) replaced to ".html".
205
206 7. Create an output directory:
207
208 mkdir -p output
209
210 8. After any modifications the following commands can be used to
211 generate the output and process the pages in descending order:
212
213 find pages -type f -name '*.cfg' -print0 | sort -zr | xargs -0 saait
214
215 9. Copy the modified stylesheets to the output directory also:
216
217 cp style.css print.css output/
218
219 10. Open output/index.html locally in your webbrowser to review the
220 changes.
221
222 11. To synchronize files, you can securely transfer them via SSH using
223 rsync:
224
225 rsync -av output/ user@somehost:/var/www/htdocs/
226
227 TRIVIA
228 The most boring static page generator.
229
230 Meaning of saai (dutch): boring, pronunciation of saait: site
231
232 SEE ALSO
233 find(1), sort(1), xargs(1)
234
235 AUTHORS
236 Hiltjo Posthuma <hiltjo@codemadness.org>