The CommonMark spec doesn’t “say something” about relative destination link semantics because Markdown never said anything about it, and CommonMark’s purpose is to provide a spec to lock down the syntax unambiguously, not to provide any new semantics. Doing the latter would be a “breaking change”.
Probably the reason Markdown (and thus CommonMark) doesn’t clarify this is because it was concerned with (1) the syntax for individual documents which (2) were rendered to HTML. It assumed the user of Markdown would use relative paths to images and other pages appropriate to their HTML publishing setup.
But you are right, many people are concerned with publishing entire assemblies of Markdown pages and resources. It’s not great that each publishing platform has its own rules. For example:
- GitHub supports relative paths to other pages or resources in the same repo and automatically transforms the paths as necessary for the HTML rendered versions.
- Pandoc by default expects paths relative to the project root, but can be configured to use page-relative paths with its
rebase_relative_paths option. It does not natively support automatic transformation of links to
.md files into links to corresponding published
.html files, but you can use a custom Lua filter to make that happen.
- Hugo until recently required the use of proprietary “shortcodes” to achieve what GitHub does automatically, but apparently has since mimicked GitHub’s behavior.
- some setups have no support for this at all, and one is forced to code into their Markdown sources links to the expected publish URLs of references pages and images. This coupling of source and specific publish path is just plain bad.
I’ve long wanted to address this issue. I’ve put considerable time in developing a proposal which I call TextAssembly . I haven’t pushed my draft spec to the repo yet… right now there’s just the README and the manifesto. I’ve temporarily back-burnered that proposal until I finish a different related project. Feel free to watch or star TextAssembly so you are alerted when I get back to it