genhtml — Static HTML Inserts for Website Files
This is the home of genhtml, a Python script used to construct most of the web pages published at this site. With genhtml, site-wide updates are easy, because common page components are split off to automatic inserts and referenced by name. Moreover, genhtml's page inserts do not require a web server, which makes them useful in off-line roles such as documentation.
This page describes genhtml's use cases and mechanics, and provides download links. If you're looking for a quick example of genhtml in action, check out the
of the page you are viewing; one of the
it references; and its genhtml
. To dive right in, read the docstring of the
, and find genhtml's usage in this site's master publishing
. And for the full story, read on here.
Overview
This Python 3.X program provides basic HTML macro functionality, which you invoke as part of your page-building workflow. It replaces keys in a folder's HTML-template files with the content of correspondingly named insert files. The net effect automatically updates static web pages when any common content they share is changed. Among its features, this program has:
Automatic dependency tracking HTML files are regenerated whenever—and only when—their templates or any inserts they use have changed Configurable Unicode support Encodings in a sequence are tried in turn for each HTML template file One-level nested inserts Insert files can insert other insert files for added flexibility Automatic generation-date insertion Built-in date keys support multiple formats This script addresses only static content: common text that can change over time, but need not be generated on each new page request from a server. For such content, though, this program is a simple alternative to:
Mass cut-and-paste edits, which are prohibitively tedious
JavaScript hacks on the client, which users may disable
PHP or Apache inserts on the server, which make your pages unviewable offline
Unix cpp + make, which may not be present on every platform, and requires manual makefiles
HTML preprocessors, which have many of cpp's tradeoffs, and are overkill for the use case
By comparison, Server Side
provides a standard and reasonable inserts tool for pages which will only ever be viewed online. genhtml can do similar work by building pages on your development machine prior to uploads, but its server-less model also allows its results to be viewed in full offline, and applies to non-web tasks such as program documentation.
Besides its utility, this program uses and requires only Python 3.X, runs on any platform that Python 3.X supports (including most PCs and smartphones), and illustrates a typical role for Python code in content-creation pipelines.
Resources
See the main script's docstring and other items below for usage details.
Code and docs:
— the main script's source (634 lines, 1/2 docstring)
Example:
— with insert targets
— filename gives template key
— referenced in prior item
— with inserts applied
— as rendered by your browser
Usage:
— runs genhtml automatically
— basic script interaction
— session console capture
— assorted documentation augmenting the script's docstring
Download
Use the following to fetch genhtml, or view its unzipped content.
— with all tests, docs, and examples
— script, docs, more examples and test pages
This program was last changed: March 2022.
Recent upgrades: genhtml's latest version retries page saves with UTF-8, if their saves fail with the encoding used to load their templates. This allows insert files to use broader Unicode character sets than their page-template clients.
genhtml's prior version explicitly handles .* Mac/Unix cruft files in inserts and templates folders, including both .DS_Store Finder files and any ._* AppleDouble resource-fork files on non-Mac drives. Both are skipped in inserts to avoid errors, but are simply copied like other non-HTML in templates because more may crop up before site publication; filter later with your zip or upload tools (e.g., -skipcruft in
).
For more code examples, see the
page.
