Workspace Root URL References

Author: Michael Vorburger.ch
Status: Idea

Abstract

This Spec introduces a convention for resolving special URLs to the “root of a project’s directory” instead of the “physical” file system root.

Description

A URL resolver supporting this spec will interpret a URL such as ¬/dir/file.txt to mean “relative” to the closest parent directory containing an (empty) .ROOT tag file.

Given a project directory tree looking e.g. like this:

• /home/user/projects/cool/
• .ROOT tag file #1
• README.md
• docs/
  • .ROOT tag file #2
  • README.md
  • folder/
  • index.md
• other/
  • whatever.xyz

The following will be the Result of resolve the Reference given the Base:

Base	Reference	Result
README.md	README.md	README.md
README.md	¬/README.md	README.md
docs/README.md	¬/README.md	docs/README.md
docs/folder/index.md	¬/README.md	docs/README.md
other/whatever.xyz	¬/README.md	README.md

If there is no tag file in any ancestor directory, then an error is raised (instead of it being ignored; as the user likely meant to put one).

Note that the slash after the special character is mandatory; ¬test.txt is ignored and kept as-is (and thus very likely won’t work).

This was, of course, inspired by the ~ convention for $HOME which has been prevalent in UNIX shells for many tens of years.

There is, obviously, a small risk that this makes “real” files inside a (relative) directory actually named ¬ in-accessible, but we consider the impact of this drawback as negligible. (The ~ on UNIX could cause similar confusion, but details depend on your shell’s escaping rules; here, it’s just impossible to use a so named directory from a system with a resolver implementing this Spec.)

This is primarily intended to work on file: scheme URIs; but not entirely exclusively, as it could also be made to work to resolve e.g. inside jar: (zip:?) sort of virtual file systems. It perhaps makes less sense on http: just because e.g. web browsers’ HTTP clients will not support this spec.

Alternatives

We initially thought of using // instead of ¬, inspired by Bazel WORKSPACE relative syntax. However, we suggest that is not such a great idea, because // does have a well-defined other meaning; as it’s already the protocol-relative URL (PRURL) prefix.

One could also consider “just” interpreting absolute / references in this way. But that’s again not a great idea - because that really does have a very well defined meaning already; for a generic solution, you must still be able to reference e.g. /tmp/file (or whatever).

Other characters than ¬ which we did consider were § and ° or |, but they seemed less clear. The use of | (or |) specifically, but other than making one think of the (totally unrelated) UNIX pipe concept, was considered to have potential for confusion specifically in the context of Markdown Magic Links which already use it to separate URI-Reference and Text in their new link syntax.

Fallback

Without this, one can just write out the full relative path in links.

This essentially just saves having to figure out and type ../../../abc, and having to maintain that when moving files around.

Implementations

Enola.dev’s I/O sub-system may implement this idea in the future.

References

• Gollum permits absolute paths like [[/Foo]]

• MkDocs kind of supports absolute [text](/another.md), and then interprets it as “root of docs/ directory” (instead of “real root of filesystem”). But it recommends against using this feature, and has validation to detect it. (And mkdocs-abs-rel-plugin did it before it was standard.)