Option to support unix-style path semantics

[vassudanagunta]

Unix-style path semantics, in particular support for both absolute and relative paths, are well understood and have become the path "lingua franca", from file systems to HTML links. Hugo's .Site.GetPage method and ref/relref shortcodes go against these conventions:

• relative paths are not supported. (though there are unused artifacts in the code indicating that it was once the intent).
• leading "/"s are ignored. What looks like a relative path is actually absolute.

The latter adds unnecessary confusion for new users. The former is a significant functional disadvantage. Relative paths allow sections (directory branches) in the content tree to be self-contained, and facilitate moving or renaming them without breaking internal links. It is one of the main reasons HTML follows unix-style path semantics (and given that HTML is Hugo's most common target, it would be nice to have the same semantics).

relative path vs shorthand references

Hugo supports what I'm calling "shorthand" refs for the .Site.GetPage method and the ref/relref shortcodes. I'm not sure it was a good idea.

Looking at the discussion, shorthand refs came about to alleviate a pain point: One had to type the fully-qualified, absolute (from the content root) path to the target, no matter how deep, and even if one page was referring to another page in the same directory.

Supporting relative paths would have alleviated that pain without introducing ambiguity, and in a way that is arguably more powerful.

To re-use the example from #4727:

content/
├── _index.md
├── help.md
├── blog
│   └── lessons.md
│   ├── lessons.nn.md
└── lessons
    ├── _index.md
    ├── links
    │   ├── _index.md
    │   └── help.md
    └── tags
        ├── _index.md
        └── help.md

• The most common cases of reference are very short:
  • sibling items: The Links lesson references its help page as help.md
  • subsection: The Lessons home refers to its various lessons simply: links and tags.
• The next most common cases are only slightly longer. But that extra length is meaningful:
  • items in the root: the Links lesson references the site-wide help as /help.md and the homepage as /. The "/" prefix says with a single char: I am referring to a root item!
  • parent items: The Links lesson refers to the Lessons home page with a simple ../. That three character prefix says I'm pointing back out to my containing section, and it will work even if Lessons is renamed to Tutorials.
  • subsection items: If for any reason the Lessons home page want to refer the help pages for each of the lessons, the added prefix makes this appropriatel explicit: links/help.md and tags/help.md.
• The long ones are links beyond "close family". And they very rightly are a bit longer. If the Lessons home wanted to refer to the blog post about lessons, /blog/lessons.md is not only reasonable but perfect. If you think about it, such cross-branch links are the kind of links you really want to be explicit about and fully-qualify.
• When you have a choice, the choice is semantically useful. You can point to the Lessons home from the Tags Lesson one of two ways: .. or /lessons, depending on whether you are saying I'm pointing to my parent section or I'm pointing to the lessons section.

if you really want wiki links...

The reason wiki links can be so simple is because wikis have a single, flat namespace (see discussion here). It's really dangerous to collapse the hierarchical namespace of a filesystem into a flat namespace. You can achieve wiki-like simplicity with Hugo: Just put all your content in the root folder, in which case you only ever have to type the filename. If Hugo supported relative paths, you could do this in a section or subsection as well.

Pull request forthcoming pending a discussion on the forum...

[github-actions]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.