arachnopress

DESCRIPTION

arachnopress builds a single-page or multi-page static site from articles/slug/article.html files. Run make build to generate site/, then serve it as static files or open site/index.html through file://.

The build runs in POSIX-like BSD, Linux, and macOS environments. The generated interface uses HTML and CSS only; it requires no client-side scripting or server-side processing.

FEATURES

• File-backed code blocks with syntax highlighting, collapsible headers, optional footers, raw links, sizes, and header/footer navigation.
• Download blocks with file sizes and checksums.
• Image blocks and directory galleries with responsive sizing, framing, alignment, text flow, and enlarged-image popovers.
• Small, editable HTML article fragments with optional arbitrary HTML.
• Single-page or per-article output; optional unlisted articles and extensionless page links.
• Responsive article, section, and subsection indexes; title/date sorting, summary tooltips, and creation/modification metadata.
• Opt-in Atom entries for whole articles or sections, with subsection links.
• Upstream colour palettes, Exact/Auto/Light/Dark modes, independent corner styles, and background-opacity controls.
• SVG logos, favicons, and optional fixed or randomised themed backdrops; a single Unicode symbol provides the logo/favicon fallback.
• Theme, contact, and license popovers; contact messages sent as marked GET requests for server-log collection.
• No cookies or browser storage; optional release-archive packaging.

DOWNLOADS

REQUIREMENTS

• Build: POSIX-style sh, BSD or GNU make, standard Unix utilities, and mktemp.
• Utilities: awk, sed, grep, sort, tr, date, dirname, pwd, printf, mkdir, rm, wc, cat, cksum, chmod, mv, cp, and find.
• Release targets: cmp and tar with gzip support.
• mktemp is widely available but is not specified by POSIX.
• Optional highlighting: pygmentize (Pygments, default) or GNU source-highlight.
• Optional download checksums: sha256, sha256sum, shasum, or openssl; the first successful one is used.
• Browser: CSS :has(), :target, prefers-color-scheme, native details/summary, and HTML popovers. CSS random() is optional.

BUILD

1. Work from the project root, which contains Makefile.
2. Edit PUBLIC_SITE_ENV in the Makefile for the site's identity, appearance, and feed settings. Set its own SITE_URL and SITE_AUTHOR, or disable SITE_FEED. If removing the bundled article, replace its SVG paths or disable the SVG icon and backdrop.
3. Add or edit articles below articles/.
4. Run make build. Deploy or inspect site/index.html.

• Environment and command-line make variables override profile defaults.
• build copies all article directories and renders the site in staging before replacing site/.
• Keep maintained files outside site/. Run builds from the source root, never from the generated tree.
• Rerun after changing articles, assets, CSS, or settings. Stylesheet and favicon URLs carry content-based cache tokens.
• All targets share site/; run only one build at a time.

For generator release packaging, see MAINTENANCE.

ARTICLE FORMAT

Article structure

Create articles/slug/article.html with this structure:

• Keep the opening article tag on one line. Its class list must include article; id must match the directory name; data-title supplies the index title.
• Use double-quoted attributes read by the generator.
• The header contains h1, an optional kicker, and p class="summary". The summary may span lines and contain inline HTML.
• Use normal HTML for article content. Author HTML and inline SVG are trusted input; they are not sanitised. Author-supplied scripts or external resources remain part of the output.
• data-listed: true (default) or false; see Unlisted articles under CONFIGURATION.
• data-feed-sections: none (default), h1, h2, or h3; see ATOM FEED.

Headings and links

• Use h2 sections and h3 subsections. Every source h2/h3 is indexed; each must contain plain text and close on the same line. An h3 follows an h2.
• Explicit heading IDs are optional. Otherwise, IDs derive from the article and heading text; repeated names receive unique suffixes.
• Slugs and explicit IDs use ASCII letters, digits, dots, underscores, and hyphens. Article, heading, control, and generated-block IDs must not collide. Keep IDs on other author elements unique.
• Single-page links use #article-id or #heading-id. Multi-page links use slug.html#heading-id, or slug#heading-id with extensionless URLs.
• Copy section links from the generated index, or assign explicit IDs for links that must survive heading renames. Author-written links are not rewritten when the output mode changes.

Dates

Article, h2, and h3 attributes accept auto or a value beginning with a valid YYYY-MM-DD date. Metadata, date sorting, and feed timestamps use the date portion.

Article data-created

Missing, empty, or auto: current UTC build date.

Article data-modified

Missing or empty: resolved creation date. auto: UTC build date.

Heading dates

data-modified takes precedence over data-created. auto uses the UTC build date. An undated h2 inherits the article's resolved modification date; an undated h3 contributes no date. A newer child h3 date updates its parent section's effective date.

• The effective article modification date is the newest resolved article or heading date. It drives Updated metadata, modification sorting, and whole-article feed entries.
• Missing and empty heading attributes have the same fallback behaviour.
• The header displays Created, plus Updated when different, with middle-dot separators. Unlisted articles also display Unlisted.
• Heading dates never reorder sections or subsections. Creation sorting continues to use the article's creation date.
• Use explicit dates for stable publication metadata. The build does not write resolved dates or generated heading IDs into source files.

GENERATED BLOCKS

• Each marker is an empty element on one source line.
• data-src is relative to the article directory. Path components use ASCII letters, digits, dots, underscores, and hyphens; empty components, ., .., and symlinks are rejected.
• Missing or invalid sources render visible missing blocks. Non-empty or multiline markers stop the build.
• data-title overrides the displayed source path; data-note adds a header qualifier.

Code blocks

• data-lang: explicit lexer, or omit for filename inference. Pygments auto also permits content guessing.
• data-open="false": initially collapsed; default is open.
• data-header="false": always visible, without a header.
• data-footer="true" or "false": override automatic footer selection. Normally shown above CODE_FOOTER_LINES; headerless blocks require explicit true.
• Header/footer arrows navigate between the bars. Raw links and sizes refer to the original file.

HIGHLIGHTER selects pygments (default), source-highlight, or none:

• Missing tools, unknown lexers, failed highlighting, or unusable output fall back to escaped source. none always uses escaped source.
• Source-highlight uses tools/html-fragment.outlang; an omitted or auto language enables its language inference.
• Highlighted output follows the selected theme. Whitespace-only Pygments span.w and Source-highlight span.sh-normal wrappers are removed without removing whitespace.

Download blocks

• One data-src file per marker.
• Displays the file size and, when available, its SHA256 checksum.
• data-title changes the label, not the download path.

Image blocks

A file creates a single image; a directory creates a gallery. Both use the same size, alignment, frame, header, and footer options.

data-alt / data-caption

Alternative text / visible caption. A gallery caption covers the whole block; its alternative text prefixes each readable filename.

data-open / data-header

As for code blocks: open and headed by default; false collapses the block or removes its header.

data-footer

Shown with a header unless false. Headerless images require explicit true.

data-scale

small (20rem), medium (32rem), large (48rem), or full (default). Caps image/gallery width within available space; frame padding is additional.

data-border

full (default): full-width frame. fit: frame fitted to the image or gallery, with equal-width header and footer. none: no frame, padding, header, or footer; the block retains an opaque article-background surface.

data-align

start, center (default), or end. Aligns the image inside a full frame, or the entire fit/borderless block.

• Single images preserve aspect ratio, scale down to fit, and do not upscale.
• Images load lazily and decode asynchronously.
• Unknown scale, border, or alignment values stop the build.

Galleries and viewers

• Galleries read immediate AVIF, GIF, JPEG, PNG, SVG, and WebP files in filename order. They do not recurse; hidden, unsupported, or invalid filenames are ignored. An empty gallery renders a missing block.
• Previews occupy equal square cells and may crop. Small galleries use one to three columns; larger galleries fit columns to the block width.
• Thumbnail tooltips show filenames. The footer shows the image count; each enlarged gallery image has its own raw link.
• Click an image to open its themed viewer over the article pane. The complete image retains its aspect ratio and scales down without upscaling.
• Click the enlarged image or X, press Escape, or click outside to close. Image cursors indicate zoom in/out. Missing blocks have no viewer.

Text beside images

1. Place the image marker directly inside an article section, before the text that should flow beside it.
2. Use data-border="fit" or "none" with data-align="start" or "end".

• Above 760px, the block occupies at most 55% of the section width, subject to its size limit. Following paragraphs and text lists flow beside it.
• Headings, generated blocks, preformatted blocks, tables, horizontal rules, consecutive images, and the section end clear the flow.
• Centered/full-frame blocks stay on their own row. At narrower widths, blocks return to normal flow and start/end-aligned images are centred.

CONFIGURATION

Edit Makefile defaults or override individual values with make build NAME=value.

• PUBLIC_SITE_ENV: site defaults for build and full.
• RELEASE_SITE_ENV: site defaults for release.
• BUILD_ENV: shared defaults.
• Below, public means build/full; release means the release profile. Boolean settings accept true or false.

Site and navigation

SITE_TITLE

Header brand, site page title, and contact-marker prefix. Default: public arachnogoat; release arachnopress.

SITE_MODE

single-page (default): all generated articles in index.html. multi-page: one article per slug.html, plus index.html containing the first listed article. Each page embeds its navigation rules and shares the CSS.

SITE_URL_STYLE

html: page links retain .html. extensionless: multi-page navigation and contact actions use slug and ./; files retain .html. Requires a server rewrite. Single-page output is unaffected. Default: public extensionless; release html.

ARTICLE_ORDER

Initial index order: title (default), created, or modified. Title sorting is case-insensitive; date sorting is newest first. Ties use the slug. Visitors can switch order with the index controls; sections and subsections retain source order.

• The first listed article in the configured order is the initial article.
• Multi-page slug.html titles use article title followed by SITE_TITLE; the index page uses SITE_TITLE.
• Multi-page slugs cannot be index. Extensionless slugs also cannot contain dots or collide with a path at the site root.
• Landscape navigation uses a left pane; narrow/portrait navigation uses horizontal article, section, and conditional subsection rows.
• Article-title tooltips show a plain-text summary and a final line of Created/Updated dates. Unsupported summary markup falls back to dates only. Native tooltip appearance is browser-controlled.
• Single-page HTML includes all generated article bodies and highlighted spans. Use multi-page output, excerpts, or HIGHLIGHTER=none for large code-heavy collections.

Unlisted articles

Mark an article data-listed="false". SITE_MODE_UNLISTED=true generates it; false excludes it from generated pages and navigation. Default: public true; release false.

• Single-page: accessible by article/heading fragment, with section navigation, but absent from every article-title index.
• Multi-page: its page indexes all listed articles plus itself, never another unlisted article. Listed pages omit it. Its robots directive is noindex, nofollow.
• Unlisted content is public. Single-page output has no per-article robots directive. All included source directories are still copied to site/articles/, even when unlisted generation is disabled.
• At least one listed article is required. Unlisted articles never appear in the Atom feed.

Themes and controls

DEFAULT_THEME

Theme input ID from tools/theme-menu.html, with or without theme-. Default: public everforest-hard-dark; release solarized-dark.

DEFAULT_THEME_MODE

off: no mode control; use the selected theme unchanged. exact, auto, light, or dark: show all four controls and select that initial mode. Default: public exact; release off.

DEFAULT_THEME_SELECTOR

true (default): show the Theme popover in either page mode. false: fix the theme, corners, and opacity to build values. The separate mode control remains governed by DEFAULT_THEME_MODE.

DEFAULT_ROUNDING

square, soft, rounded, or round. Applies across controls, highlights, blocks, images, and popovers. Default: public soft; release square.

DEFAULT_BACKGROUND_OPACITY

Initial SVG backdrop opacity: 0 to 100 percent in steps of 10. Default: 30. Its selector appears above Corners when SITE_BACKGROUND=true.

• Exact uses the selected palette unchanged. Auto follows the browser's light/dark preference; Light and Dark force the mapped variant.
• Corner style and background opacity are independent of theme/mode changes.
• Selections persist within a single-page document. Reloading or opening another multi-page article restores build settings.
• Set light/dark pairs with data-auto-light and data-auto-dark on theme inputs in tools/theme-menu.html. Supply both IDs, refer to existing themes, and include the source theme in its pair. Unmapped themes remain unchanged in every mode.
• Palettes retain upstream RGB values. styles.css maps them to interface and syntax roles, without colour mixing or contrast adjustment.

Logo and favicon

SITE_ICON_PATH

Custom SVG path relative to the build tree. Used as the header logo and copied unchanged to favicon.svg. Default: public articles/arachnopress/arachnogoatsundual.svg; release empty.

SITE_ICON_PATH_THEME

true: embed and theme the header SVG; requires SITE_ICON_PATH. false: display it as an external image. The favicon always keeps its original colours. Default: public true; release false.

SITE_ICON

Single Unicode symbol for the header and generated favicon when SITE_ICON_PATH is empty. Default: public U+4DEA; release U+4DD6.

SITE_ICON_COLOUR

Optional #rgb or #rrggbb override for the Unicode icon. Empty (default): header uses the article-title colour; generated favicon uses SVG's default text fill. Unused with a custom SVG.

• Store SVGs below an included article, using the same path-component rules as generated blocks. Files must be readable, non-empty .svg files; do not use the generated favicon.svg.
• For a themed logo, assign double-quoted class="colour-out" and class="colour-in" attributes to drawable elements or groups. Edit the SVG directly or use Inkscape's XML Editor.
• CSS fills colour-out with the article background and colour-in with its title colour. The mapping follows the active theme and mode. Avoid inline style declarations that override those fills.
• Restore the Unicode icon with SITE_ICON_PATH= and SITE_ICON_PATH_THEME=false.

Article backdrop

SITE_BACKGROUND

Enable the fixed article-pane SVG background. Default: public true; release false.

SITE_BACKGROUND_PATH

SVG path relative to the build tree, with the same file and class requirements as a themed logo. Default: articles/arachnopress/arachnogoatsundual.svg.

SITE_BACKGROUND_RANDOM

true (default): browsers supporting CSS random() choose a scale and crop on document load. Unsupported browsers, or false, retain the SVG's base fit.

• The backdrop paints colour-in with the theme's background artwork colour; colour-out is unpainted. DEFAULT_BACKGROUND_OPACITY controls opacity.
• Use preserveAspectRatio="xMidYMid slice" for a centred cover crop, as in the bundled SVG.
• Single-page navigation retains one backdrop; each multi-page document can receive a new random crop. Code, download, and image surfaces stay opaque.

Highlighting and local CSS

HIGHLIGHTER

pygments (default), source-highlight, or none. See Code blocks under GENERATED BLOCKS.

CODE_FOOTER_LINES

Non-negative source-line threshold for automatic code footers. Default: 23; blocks at or below it omit the footer.

Create custom-styles.css in the project root for site-local styling:

• build and full copy it unchanged when present; release excludes it. It must be a readable regular file, not a symlink.
• Pages load it after standard CSS and embedded navigation rules. Normal specificity applies; existing CSS variables follow the active theme.
• Without the file, no custom stylesheet link is generated.

Feed identity

SITE_FEED

Generate feed.atom, discovery metadata, and the header's Atom link. Default: public true; release false.

SITE_URL

Canonical site root, including any deployment subdirectory. Required when the feed is enabled: absolute HTTP(S), with no whitespace, query, or fragment. Trailing slashes are removed. Default: public https://arachnogoat.com; release empty.

SITE_AUTHOR

Atom author name. Default: public musol@arachnogoat.com; release SITE_TITLE.

ATOM FEED

Enable SITE_FEED, set the feed identity, and opt listed articles in with data-feed-sections:

none

No entries; also used when the attribute is missing or empty.

h1

One entry with the article title, link, and available plain-text summary.

h2

One entry per section, titled "Article title - Section heading", with its section link as content.

h3

As h2, adding a linked list of that section's h3 headings.

• h2/h3 fall back to h1 when the article has no sections. An h3 entry without child headings contains only its section link. Section entries do not include article prose.
• Entry dates follow ARTICLE FORMAT: h1 uses the effective article modification date; section entries use their effective h2 date, including newer child dates.
• An article-level auto date participates in whole-article entries. For section entries, it is only the fallback for an undated h2.
• Dates use midnight UTC. Article groups sort by their newest entry; sections and linked subsections retain source order. The feed date is the newest entry date, or the UTC build date when empty.
• Links follow SITE_MODE and SITE_URL_STYLE. IDs remain SITE_URL/#article-id or SITE_URL/#section-id, independent of dates and output mode.
• Explicit heading IDs preserve feed identity across renames and reordering of duplicate headings. Changing SITE_URL changes IDs.
• New sections create entries; edits and new h3 links retain the parent entry ID. Switching to section mode introduces existing sections as entries. Read/unread status is controlled by the reader.
• The Atom 1.0 feed includes author, generator/version, HTML links, and the versioned site favicon. It may contain zero entries.

SERVING

• Deploy the contents of site/ without changing relative paths.
• For local file:// access, open site/index.html; multi-page navigation requires SITE_URL_STYLE=html.
• Serve .atom as application/atom+xml.
• Extensionless multi-page URLs require an internal rewrite from missing extensionless paths to their .html files.

The OpenBSD httpd(8) example supplies the Atom MIME type and rewrite. Replace its host, certificate, and document-root paths; validate before reloading. Keep specific location rules before the final rewrite.

Contact messages

• The Contact popover submits a GET to the current page and displays a confirmation. It requires HTTP(S); use HTTPS for transport encryption.
• reply: optional address, maximum 254 characters. message: required, maximum 500 characters.
• The first query item is sanitised-site-title_contact=1. The title is lowercased; runs outside ASCII letters, digits, dots, underscores, and hyphens become an underscore; edge underscores are removed. A result without letters or digits becomes arachnopress.
• The default markers are arachnogoat_contact=1 for public builds and arachnopress_contact=1 for releases.
• Configure access logging to retain query strings. Extract and process marked requests from the log; the site has no separate delivery or storage service.
• Messages remain in URLs, browser history, and server logs. Do not include confidential information.

MAINTENANCE

Generator releases

These targets package the generator; routine site updates use make build.

GENERATOR_LABEL

Generator name displayed in site and Atom metadata. Default: arachnopress; archive names remain arachnopress.

GENERATOR_VERSION

Dot-separated digits used in metadata and archive names. Default: 1.0.70.

make release

Builds only articles/arachnopress with RELEASE_FILES, leaving a working release tree in site/. Creates arachnopress_VERSION.tar.gz at the project root, under a matching top-level directory. Its own download is absent inside that tree/archive.

make full

Requires the matching root release archive. Builds all articles with RELEASE_FILES and installs the archive into the staged generator article. Leaves that complete tree in site/.

• The generator article must contain exactly one data-release="generator" download marker.
• Both targets update that complete marker line to the current archive name and remove arachnopress_*.tar.gz from the source generator article directory after publication. Other root archives remain.
• build uses RUNTIME_FILES and all articles; it leaves source download markers and archives unchanged.

1. Update GENERATOR_VERSION and run make release.
2. Copy the root archive into articles/arachnopress/, then run make build to publish it with other articles. Alternatively, make full integrates it into staged output.

Failures and cleanup

• A validation, staging, or rendering failure preserves the previous site/. Publication replaces the old output directory.
• Targets exit zero on success and non-zero on invalid input or an unhandled command/filesystem failure. Correct the diagnostic and rerun.
• Missing block sources, optional highlighting, and unavailable checksums are non-fatal: blocks show missing-source notices, escaped code, or no checksum.
• Normal exits/signals clean temporary files. After an untrappable termination, stop all builds and inspect .site-build.* under the project root and static-site-build.* under TMPDIR before removing leftovers.
• There is no clean target. Remove site/ to discard generated output; remove obsolete root archives by exact filename.
• Inclusion lists reject symlinks, including those within article directories.

Missing release archive

Run make release with the same version before make full, from the same source root.

No listed articles found

Provide at least one article with data-listed="true" or no data-listed attribute.

Invalid theme, SVG, heading, marker, or path

Check the named input against CONFIGURATION, ARTICLE FORMAT, or GENERATED BLOCKS. Diagnostics identify the rejected value or source.

Build environment

PATH

Locates build utilities, highlighters, and checksum programs.

TMPDIR

Parent of private static-site-build.* rendering directories; default /tmp. Target staging uses .site-build.* beneath the source root.

LC_ALL / SOURCE_HIGHLIGHT_DATADIR

The scripts set LC_ALL=C; the generator unsets SOURCE_HIGHLIGHT_DATADIR.

• tools/build-profile.sh invokes tools/build.sh with internal BUILD_ROOT and ARTICLE_SELECTION settings.
• Direct generator execution writes into its build root, defaults to the source root, and does not stage or package site/.
• Direct execution uses release-style site defaults and the script version above; it reads custom-styles.css from its build root.

FILES

Maintained inputs

Makefile

Targets, profile defaults, and inclusion lists.

articles/slug/article.html / articles/slug/*

Article fragments and their code, image, gallery, and download assets.

styles.css / custom-styles.css

Shared layout, palettes, and syntax roles / optional site-local overrides.

tools/build.sh / tools/build-profile.sh

Article renderer / target staging and packaging.

tools/theme-menu.html

Theme controls and light/dark pair mappings.

tools/html-fragment.outlang

Source-highlight HTML-fragment output definition.

tools/license.txt / THIRD_PARTY_NOTICES.txt / licenses/

Static project license / palette sources and retained third-party notices.

README.arachnopress

Plain-text edition of this reference.

Generated output

site/index.html / site/slug.html

Entry page / additional multi-page articles, with embedded navigation rules.

site/articles/

Copied article directories, including source HTML and published assets.

site/styles.css / site/custom-styles.css

Copied shared stylesheet / optional custom stylesheet.

site/theme-auto.css

Derived theme-mode rules; present when the mode control is enabled and a selectable theme has a light/dark mapping.

site/favicon.svg / site/feed.atom

Generated or copied favicon / optional Atom feed.

site/THIRD_PARTY_NOTICES.txt / site/licenses/

Copied notices required by the published site.

LICENSE

• arachnopress: BSD 3-Clause; see tools/license.txt.
• The license popover embeds that file as escaped text. Its first non-blank line supplies the title; the text is otherwise static.
• Bundled palettes retain their upstream licences; see THIRD_PARTY_NOTICES.txt and licenses/. The license and Theme popovers link to those notices.