Introduction
Introduction Statistics Contact Development Disclaimer Help
README - saait - the most boring static page generator
git clone git://git.codemadness.org/saait
Log
Files
Refs
README
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 director…
40 regenerates static files if this happens. If successful then refreshes t…
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")…
50 fi
51
52
53 Using Markdown
54 --------------
55
56 A possible method could be to just convert the Markdown to HTML and to r…
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 …
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 t…
89 given order.
90
91 The options are as follows:
92
93 -c configfile
94 The global configuration file, the default is "config.cfg".…
95 page configuration file inherits variables from this file. …
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…
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 tem…
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 exam…
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 defa…
148
149 contentfile
150 Path to the input content filename, by default this is the …
151 of the config file with the last extension replaced to ".ht…
152
153 filename
154 The filename or relative file path for the output file for …
155 page. By default the value is the basename of the contentf…
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…
162 spaces before a value are ignored.
163
164 TEMPLATES
165 A template (block) is text. Variables are replaced with the values…
166 in the config files.
167
168 The possible operators for variables are:
169
170 $ Escapes a XML string, for example: < to the entity &l…
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}</tim…
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 exam…
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…
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 c…
216 there has to be a corresponding HTML file. By default this HT…
217 file has the path of the config file, but with the last extens…
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…
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 u…
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 <[email protected]>
You are viewing proxied material from codemadness.org. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.