Mercury🔗

1.1 The build process🔗

Mercury follows these steps when it builds your site:

1. Mercury uses the name of your site’s module path to find its root folder on your filesystem, and, separately, to dynamically require its site-info value.

2. Mercury locates every source file in the root folder and any subfolders, and uses the site-info to construct a mapping of source files to output file paths.

3. To this source→output map, Mercury adds all files/folders in the "static" subfolder.

4. Mercury assumes that any ".rkt" file that is not also a source file affects the entire site; Thus if any such file, or any other file in your site’s cache watchlist, has a modification timestamp later than any single existing output file in the "publish" subfolder, the "publish" subfolder is wiped for a clean build, and Mercury runs raco make -j n -l sitemodpath, where n is two less than the number of CPU cores on your computer.

5. Any entry in the source→output map whose source is newer than its output file (or whose output file does not exist) is rebuilt, using a simple file copy if the source is in "static", or using the site’s source-render-proc otherwise.

6. Mercury regenerates your site’s RSS/Atom feed. All web pages whose source files include a date meta value, and whose draft? meta value, if present, is not #f, are included in the feed.

1.2 Source/output path mapping🔗

Every source file in your site produces an HTML file, and this file needs to be placed somewhere in your website’s public folder structure. Source/output path maps allow you to decide what that public folder structure will look like, and which output files will get placed in which folders.

Here’s an example of a source/output path mapping:

'("blog/*" . "blog/YYYY/MM/DD/*/")

Under this mapping, a source file saved as "blog/first-post.md.rkt", and whose date meta is set to 19 January 2025, will be output as "blog/2025/01/19/first-post/index.html".

The mapping consists of a pair of values: a source-path pattern and an output-path pattern.

A source-path pattern is a relative path ending with a single *. The pattern matches all source files contained in the path, including in any unnamed subfolders of the given path.

An output-path pattern is a relative path which must contain a * as at least one of its elements. The pattern describes the folder structure that will be created to house the output file. Any folder name in the pattern which is valid CIDR syntax will be replaced with a new name, generated by formatting the source file’s date information with that pattern using ~t. Any folder given as * will be replaced with the source file’s slug. If the output-path pattern ends in a slash, the output file will be named "index.html"; otherwise, the output file will be the name of the pattern’s final path element with the ".html" extension added.

Here are some more examples:

; Given a 'blog/first-post.md.rkt' source dated 2025-01-19:

'("blog/*" . "blog/YYYY/MM/DD/*/") ; → blog/2025/01/19/first-post/index.html

'("blog/*" . "quarterly/YYYY/MM/*") ; → quarterly/2025/01/first-post.html

'("blog/*" . "blog/*") ; → blog/first-post.html

'("blog/*" . "annual-events/*/YYYY") ; → annual-events/first-post/2025.html

'("blog/*" . "blog/YYYY/qqq/*/") ; → blog/2025/Q2/first-post/index.html

Shorthand path maps: You’ll notice there is a lot of repetition. If the folder holding your source folders is the same as the first folder in your output path, you can supply just the output path pattern instead, and the source path pattern will be inferred.

Thus, "blog/YYYY/*/" is equivalent to '("blog/*" . "blog/YYYY/*/"), and "blog/posts/*" is equivalent to '("blog/*" . "blog/posts/*").

(source/output-pattern? "blog/YYYY/MM/*/") ; #t

(source/output-pattern? '("foo/*" . "pages/*")) ; #t

(source-path-pattern? "blog/*") ; #t

(source-path-pattern? "blog/subfolder/*") ; #t

(source-path-pattern? "blog/*/") ; #f (must end with *)

(source-path-pattern? "blog/../../*") ; #f (. and .. not allowed)

(output-path-pattern? "blog/*") ; #t

(output-path-pattern? "blog/*/foo") ; #t

(output-path-pattern? "blog/**/foo") ; #f (must contain * as one of the elements)

(output-path-pattern? "blog/../../*") ; #f (. and .. not allowed)

2.1 Site Definitions🔗

• The root field is the path to the site’s root folder; this is set by define-mercury-site to the folder containing the module where the define-mercury-site expression appears.

• The title, authors, founded, and url fields are used to build the site’s feed.

• The render-proc takes a path to a source file (which is relative to root), the file’s Punct document, and the file’s slug, and must return either an HTML X-expression or bytes?.

• The pathmap-proc takes a relative path to a source file, a slug and a post date and returns a path to an output filename (relative to root). This procedure is automatically constructed by define-mercury-site from its #:output-paths argument.

When either author-name-or-names or author-email-or-emails is a list, they must both be lists of the same length. These arguments are combined into the equivalent number of person structs in the resulting site.

See the site struct definition for more info on this macro’s non-optional arguments.

The optional arguments are stored in the site-options field of the resulting struct, and are described below:

2.2 Using Sites🔗

This module exposes the structs and classes used by the Mercury Terminal app to interact with sites that provide info via define-mercury-site.

This section is not essential reading for using Mercury. It’s here for my own reference, and you will find it useful if you want to build your own tools for working with Mercury sites instead of using the Mercury Terminal app.