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>