2.3 HTML Resources

For example, a typical use of resource is to register the generation of a CSS file, where the value produced by resource itself renders as the URL for the generated CSS file. Another possible use of resource is to generate an HTML file, where the resource result renders as the URL of the generated HTML page.

The path argument specifies the path of the output file, relative to the working directory, indicating where the resource file should be placed. Though url-roots, path also determines the ultimate URL. The path string must be a /-separated relative path with no .., ., or //. The path string can end in /, in which case "index.html" is effectively added to the string. Using resource with #f as renderer is useful for converting a path to a URL according to url-roots.

The renderer argument (when non-#f) renders the resource, receiving the path for the file to be created. The path provided to renderer will be different from path, because the function is invoked in the target directory.

The resulting resource value is a function that returns the URL for the resource. The function accepts an optional boolean; if a true value is provided, the result is an absolute URL, instead of relative. Note that the function can be used as a value for output, which uses the resource value as a thunk (that renders as the relative URL for the resource). The default relative resulting URL is, of course, a value that depends on the currently rendered resource that uses this value.

When renderer is called by render-all, more resources can be created while rendering; the newly created resources will also be rendered, in turn, until no more new resources are created.

If exists is 'delete-file and the target file exists when renderer is to be called, then the file is deleted before renderer is called.

The parameter value is a mapping from path prefixes to URLs (actually, any string). When two paths have the same prefix, links from one to the other are relative (unless absolute links are requested); if they have different prefixes, the full URL is used. The paths enclosed by two root paths must be disjoint (e.g., the list must not include both "/colors" and "/colors/red", but it can include both "/colors/red" and "/colors/blue").

If an item in the parameter’s list includes 'abs, then a site-local, absolute URL (i.e., a URL that starts with /) is produced for references among files within the corresponding prefix.

If an item in the parameter’s list includes 'index, then a reference to a directory path is converted to a reference to "index.html", otherwise a reference to "index.html" is converted to a directory path.