In #19, internal links were added, but in a syntactically abnormal way: a leading ./ means an absolute URL, relative to the content directory rather than the current file.

This is a really bad idea, and a serious design bug: it wreaks havoc with the expected semantics of URLs and relative paths, leading to substantial surprise among users, and breaking tooling that people use. In Vim, for example, gf goes to the file under the cursor, and it treats ./foo.md as a relative path, but if the current file is content/bar/baz.md, it looks for content/bar/foo.md rather than content/foo.md.

This design decision was briefly questioned in #19 (comment), and the response was this:

That's intended, I think it makes more sense that way: you can move the file around but the links will stay valid.

Well, you can move the source file around, but not the destination file. If you rename a file, any files that link to it will still need to be updated.

My real counterpoint to this argument is that one of the most common forms of content moving is directory renaming; and going for absolute URLs instead of relative makes that harder, because now all pages inside the section need to have all their links updated, rather than them just working.

Really, it should be parsing the whole thing as a URL, with the content directory being the site root. Thus, things like https://… and //… will be untouched, /foo will be understood to be relative to the content directory, ../foo to the parent directory (whatever that may be, up to but not exceeding the content directory), and ./foo and foo relative to the current directory.

Then, let people decide for themselves whether they want to use relative or absolute URL styles—there are advantages and disadvantages to both approaches. In some moods I prefer absolute, because you can search for it in the source more easily; in others I prefer relative, because it’s shorter!

There is always the hazard with this that not all links that start with /, ./ or other such things are internal links—I might write /foo/, for example, rather than /foo.md. If you really want a special prefix, go for a URI scheme, e.g. site:foo.md; just don’t use ./foo.md, because it’s very confusing.

This will be a breaking change. It should be made sooner rather than later, because it will cause pain for users whenever it’s done.

(I’m questioning this now because we’re in the process of moving fastmail.com from a long-in-the-tooth homegrown Markdown.pl system to Zola, and use relative links, with ./ and ../, extensively in our help pages. We’re going to update the links in various ways anyway, but it brought my attention to this design bug.)