ADR 4: URLs mirroring paths in source directory

Context

Generated HTML pages cannot use absolute URLs because they can be used both on the production web server and also on local file system. Therefore all links in generated pages must be relative.

The problem arises when pages in different folders or at the top level should link to the same page or resource. Either the links must be different respecting different locations of pages in a directory structure, or the structure would be flattened during generation, so all pages would be placed in the top-level directory. The first option requires some logic for transforming URLs, while the second one breaks correspondence between source and destination file hierarchies.

Decision

We decided against structure flattening as it leads to possible name collisions and also the mentioned loss of source-to-destination structure correspondence.

We decided that URLs must mirror paths in the source directory. This allows authors to easily reason about URLs in cases where they need to link to other page.

URLs used in templates would be relativized using special Jinja template filter that would convert URLs relative to the top-level to URLs relative to the currently generated page.

This decision also influences URLs used in page elements, especially image paths. In the official version, directory name resources was automatically appended to the image path. To make the path explicit and allow different names of directories with images (for example simply images), no relative path given by author would be modified. “Absolute” paths (that start with a single / character and are in fact relative to the course’s top-level directory) would be just relativized to URLs relative to the currently generated page, similarly to those used in Jinja templates.

Status

Accepted.

Consequences

File paths in the output would match paths in the input, with the exception of file extensions (.xml vs .html). All relative paths entered by authors would be kept without change. Absolute paths and paths that are part of the template would be automatically modified to be relative to the current page path.