These are the user docs on HaXtatic: another *ahem* static site generator.
So basically like good ole Macromedia Dreamweaver or Microsoft FrontPage just without the GUI. Kewl huh? We're all command-line jocks anyway now.
Programmed & maintained in Haskell, and documented in HaXtatic, by me.
To summarize, in one lean handy package we get: "controls" (aka. "components" aka. sub-templates aka. parametric-snippets aka. what-have-you-lets) — iterating renderers — HTML short-hand helper (haX)tags — navigation helpers — page context / page metadata haXtags — mix-and-match-and-combine-and-nest any haXtags — embed haXtags anywhere (source contents, templates/snippets(-aka.-controls), project/config file) — some almost-enough-for-a-coder's-minimalist-blog-or-three "section-of-related-pages" notion called "Bloks" — globally shared (even-simpler-than-controls) textual/markup snippets of course — custom per-page variables — commonly desirable XML outputs (sitemap.xml, *.atom) — mod-time-differential rebuilds — per-page caching across runs — of course per-file-type templating — composable "named setups" — extensive configurability — some notion of "postings"/"simpleton data records"/"static tweets" micro-content definitions (with fully custom rendering) — easily defined, easily applied custom date-time formats ...
[ That's without touching the code-base. There's an IMHO lean and insta-grok'able extensibility mechanism for coding up custom output rendering flows & logic in Haskell, too. Though HaXtatic's combination of built-in renderers combined with its nestable haXtags and custom-parametric-markup-snippets (aka. "controls"/"components") covers a profoundly wide spectrum of needs (incl. looping over various ranges) already, except branching — that one just hasn't come up yet, thankfully. ]
No "routes" or some such notion. That's just.. newfangled.
Of course, no "MarkDown" either. If the occasional angle bracket or named entity baffles you, enjoy the sensation, or set up a separate .md-to-.html process for that, or (most likely) just go with the countless other site-gens.
To top it off, no embedded-local-web-server either. For a static site?! Get outa'town. (Emitting correct relative URLs that also work locally without a server is easy enough if you must have content pages inside sub-directories — and haXtags can be placed and processed inside CSS/JS files too.)
Git(Hub) integration? Docker play&pluggery? Content-aware on-the-fly dependency tracking via embedded PhD-thesis with Van Schlauberg ad-hoc proofs and Nodejs hooks? Type-safe everything? Uh-huh. Ain't nobody got time for tomfoolery!
~/gitrepos/metaleap/haxtatic/$ stack install should suffice stack, this very first run will take a while and possibly output countless semi-obscure progress notices, as a fresh stack first fetches the appropriate Haskell compiler (several~100s MB) — a one-off expense)~/gitrepos/metaleap/haxtatic/$ stack exec haxtatic to hopefully see a little greeting with a notice such as No project-directory path supplied. Good! Now try just ~$ haxtatic, if this works the same, even better as it "installed" (copied the binary) to somewhere on your PATH.haxtatic ~/mydemosite.foo (or alternatively, as per above, stack exec haxtatic ~/mydemosite.foo), then explore the freshly generated and populated mydemosite.foo project-directory to grasp the bare essentials from the pre-created default single-page site in there.Hacked-together for hacking-together some fine sites the (frankly imaginary) "old-school way" — certainly a rather hacky way — and honestly among all the alternatives possibly only remotely, mildly "more compelling" in case you wish to (or have to) command some awfully-convoluted-templating powers and optionally —in a pinch, as a last resort— are content to code up at least simple short pieces of Haskell (starting from this or this) — I wrote it from the ground up with easy-speedy, "done-and-done" future (rendering) extensibility chiefly in mind.
— except perhaps for the most exotic of uses (or "abusing" it for other neatly-hacky text-to-text / bulk transformations).. this tool does actually accomplish quite a lot without really needing to touch its codebase — just have to turn config-file warrior and in places wrestle moderate amounts of trivial-yet-unforgiving syntax — alas you'll have to run-from-source (or compile from scratch) no less.. for no good reason other than plain inertia on my part. (Redistributing precompiled executable binaries of my open-source work for various platforms hasn't made it onto my exhaustive list of actual priorities. Though emitting overly wordy verbiage in software documentation has, apparently, unwittingly. Confound it!)
HaXtatic performs "incremental"/"differential" rebuilds by default, so just changing a single content-source file will only re-generate that (or with a Blok page, the entire Blok). Changing a template causes rebuilding of every file (by default from a cached pre-processed version) utilizing that template. Changing *.haxproj or *.haxsnip.html files causes a "full" rebuild (also invalidating/overwriting all cached files).
On my machine (mid-2014 Thinkpad, Windows 8.1 64bit), HaXtatic consistently reports for a full rebuild (assuming no static-files have changed, and with page-caching disabled — it's enabled by default) of this very documentation site:
Wrote 35 files in 0.42s: 0.03s pre-templating & planning 0.29s page templating & generation (30x ~0.009s) 0.09s XML file generation (5x ~0.018s) 0s misc. & file-copying
With page-caching enabled (the default), per-page cost is about halved (for "differential" rebuilds as per above). Another example, a full rebuild of the publicly visible parts of metaleap.net (no static-file changes) routinely gives:
Wrote 21 files in 0.46s: 0.05s pre-templating & planning 0.36s page templating & generation (19x ~0.019s) 0.04s XML file generation (2x ~0.022s) 0s misc. & file-copying
In this case, enabled page-caching only improves per-page cost to ~0.013s so the gain very much depends on the overall project, content characteristics, main-template complexity/functionality and such; of course there will always be in principle some slight gain for all subsequent differential rebuilds.
So from the above and some other experimental/test sites, on my machine/architecture/OS combination, I can consistently expect "about 40-50 files generated per second". Not "stellar" but certainly mighty fine for the intended uses. Differential rebuilds of course cut down the total number of files to re-generate.