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]> |