Use the userRequire function from @antora/user-require-helper to require user code
Anywhere Antora requires code provided by the user, it should use the userRequire
function exported by @antora/user-require-helper to resolve and require it.
There's one potential side effect of this change. Antora will no longer locate a dot relative path inside a folder if a file extension is not specified (e.g., ./lib/my-extension
). That's because userRequire
will interpret this as a module name and end up skipping the path lib/my-extension.js
relative to the playbook directory when looking for it. Unfortunately, this was documented as supported. Therefore, we'll need to detect this special case an add a workaround to maintain backwards-compatibility. The documentation should be updated to indicate that doing so is deprecated and recommend using the file extension whenever referring to a path.
An open question is, when requiring a bare module name (a module name without an anchor like .:my-extension
), should we look for the module relative to the playbook directory or the current working directory prior to looking where Antora is installed? Currently, Antora looks relative to the playbook directory. However, this differs from how a bare relative path (like my-extension.js
) is resolved, which looks relative to the current directory.