oddmu-static(1)

Name

oddmu-static - create a static copy of the site

Synopsis

• *oddmu static** [***-jobs**** *n*] [****-glob**** *pattern*] [****-shrink***] *dir-name*

Description

The "static" subcommand generates a static copy of the pages in the current directory and saves them in the given destination directory. Existing files are only overwritten if they are older than the source file.

All pages (files with the ".md" extension) are turned into HTML files (with the ".html" extension) using the "static.html" template. Links pointing to existing pages get ".html" appended.

If a page has a name case-insensitively matching a hashtag, a feed file is generated (ending with ".rss") if any suitable links are found. A suitable link for a feed item must appear in a bullet list item using an asterisk ("*"). If no feed items are found, no feed is written. The feed is limited to the ten most recent items.

Hidden files and directories (starting with a ".") and backup files (ending with a "~") are skipped.

All other files are *hard linked*. This is done to save space: on a typical blog the images take a lot more space than the text. On my blog in 2023 I had 2.62 GiB of JPG files and 0.02 GiB of Markdown files. There is no point in copying all those images, most of the time.

As hard links cannot span filesystems, all other files are *copied* if the destination directory for the static site is not on same filesystem as the current directory.

Note that in-place editing changes the file for all names. Avoid editing the hard-linked files (anything that's not a HTML file) in the destination directory, just to be on the safe side. Usually you should be fine, as an editor moves the file that's being edited to a backup file and creates a new file. But then again, who knows. A SQLite file, for example, would change in-place, and therefore making changes to it in the destination directory would change the original, too.

Options

• **-jobs*** *n* By default, two jobs are used to process the files. If your machine has more cores, you can increase the number of jobs.

• **-glob*** *pattern* By default, all files are used for the static export. You can limit the files used by providing a shell file name pattern. A "*" matches any number of characters; a "?" matches exactly one character; "[a-z]" matches a character listed, including ranges; "[^a-z]" matches a character not listed, including ranges; "\" a backslash escapes the following character. You must use quotes around the pattern if you are using a shell as the shell would otherwise expand the pattern, resulting in the error "Exactly one target directory is required".

• **-shrink*** By default, images are linked or copied. With this option, JPEG, PNG and WebP files are scaled down if more than 800 pixels wide and the quality is set to 10% for JPEG and WebP files. This is *very bad quality* but the result is that these image files are very small.

Examples

Generate a static copy of the site, but only loading language detection for German and English, significantly reducing the time it takes to generate the static site:

env ODDMU_LANGUAGES=de,en oddmu static ../archive

Limitations

There can be nameclashes with generated HTML and RSS files and existing files ending in ".html" and ".rss". Instead of overwriting existing files in these cases, a warning is printed.

Links from files to pages do not get ".html" appended. This affects existing HTML or XML files including SVG files.

Links to absolute URLs (starting with "/") are not changed at all. It is up to you to migrate static folders and applications.

Environment

The ODDMU_WEBFINGER environment variable has no effect in this situation. Fediverse accounts are not linked to their profile pages. Since the data isn't cached, every run of this command would trigger a webfinger request for every fediverse account mentioned.

If the site is large, determining the language of a page slows things down. Set the ODDMU_LANGUAGES environment variable to a comma-separated list of ISO 639-1 codes, e.g. "en" or "en,de,fr,pt" to limit the languages loaded and thereby speed language determination up.

See also

See oddmu(1) and oddmu-templates(5) for general information.

See oddmu-html(1) for a subcommand that converts individual pages file to HTML and see oddmu-feed(1) for a subcommand that generates feeds for individual files.

Authors

Maintained by Alex Schroeder alex@gnu.org.