Wiki-Style Links Followup

There is an open issue to add wiki-style link support here: Support wiki-style internal page links · Issue #3606 · gohugoio/hugo · GitHub
and an open PR for the same here: Internal links (Wikilink) issue #3606 by dgasparri · Pull Request #10019 · gohugoio/hugo · GitHub

The PR has been open for about a year now. I request that an initial code review be performed to let the community know if this feature will be considered for addition. If we see a response from the maintainers on the PR hopefully we can get the issues mentioned below addressed and then a merge could happen.

I have checked out the PR and confirmed that it works as expected for the base case, but not the piped case (spot check only, with extended enabled). There are also no unit tests added for the new syntax. So certainly additional work is needed.

I did see one unit test error: doTestGetDottedRelativePath is failing in both helpers\path_test.go and common\paths\path_test.go specifically for the "////post/////" input. I don’t understand the purpose of this check well enough to investigate a fix as that input does not seem valid at first glance. Several other modules failed to run for me but I suspect that my dev environment setup is not complete as this happens in master as well.

Merging in origin/master resulted in additional unit test failures but I ran out of time to investigate. I suspect that some changes have been made which render this change incompatible. If I find time to look at this later I will post to the PR with my findings.

I have made a note in the PR comments with all issues found.

For me personally, this is a feature I really want. It should make moving pages around on my site much easier as well as lower my cognitive load when cross linking (needing only to know a given page title and not it’s path). In addition this would help me preserve editing habits across applications as I’m using Obsidian for most other writing activities outside my website, and I grew up on MediaWiki.

1 Like

A code review might make sense if there were consensus on what the code should actually do, and an indication from the project maintainer that such an addition to the code base would be welcome.

The only consensus that I have seen is that the format should be:


where the pipe + label is optional.

But I haven’t seen any consensus on what “something” should be.

  1. Some want “something” be the page .Title.
  2. Others want it to be the file path or file name.
  3. Others want it to be a site-relative or page-relative URL.
  4. What should it do if it can’t find the page?
  5. What if it finds duplicates (two pages with the same title)? Which one should it pick?
  6. Should the match be case sensitive?
  7. Should it also handle absolute URLs (e.g.,
  8. Should there be an enable/disable flag in site configuration?
  9. Should it handle images?

Should we follow this standard:

Or something else?

For those willing to use this notation…


… a link render hook can handle items 1 through 8 above.

The problem of consensus is entirely fair, but it is not clear from either the issue or the PR that this is the hangup, given the lack of response over the past year. I’m going to cross-post a note about the problem of consensus to the issue thread.

As for the maintainer’s openness to a PR: I also don’t think we have an indication that a PR would not be welcome. @bep could you weigh in on that, either here or in the GitHub issue thread? My apologies for bothering you. I know you are busy. Even if a PR is not welcome, it would be good to know so that others can avoid putting more effort into this. Thanks for all you do!

In an effort to reach consensus:

1,2: I think a significant percentage of people looking for this feature don’t think of this as a problem because, in the system they’re coming from, page name / file name (without extension), and Title are all always equal (this is at least [naively] true on MediaWiki and Obsidian, but possibly not GitHub - I’m not familiar). So it will be important for them to understand what they’re getting via documentation, but I think it may not be useful to ask the question up front. Rather have hugo dictate a default. I don’t hold a strong opinion on which one, but I think file name might be simplest since we already have a standing implementation. Hugo could then offer a configuration option to switch to the other style (perhaps as a followup feature).

3: I think it would make sense for the file name version to also accept full file paths, but this could be a followup feature if it does not happen naturally.

4: When no matching page is found, the PR implementation throws an error, and that seems fine to me for a first pass. To be honest, I don’t really have a good answer for this one, because I don’t have a strong opinion. For my particular use cases, pretty much anything will do here. I do think throwing an error as the existing PR does might make the most sense because Hugo is not a live editing environment like many of the other systems this is modeled after.

5: I believe @bep’s proposed tree-shaking solution is the best option here, both for file name and Title options. For Title, since it is possible to have two items at the same level with the same title, I think any well-documented tie breaker will work for the vast majority of users. I propose sorting by file name alphabetically and picking the first one. It may be easier to throw an error or pick the first found match in the initial implementation, and then make this more robust as a followup feature.

6: Yes the match should be case sensitive. Although it would be cool if it did a fall-back case insensitive lookup if no matching pages are found. I think whichever one is not done could be a followup feature. So “both”.

7: This feels like a separate feature that could be proposed rather than a blocker to implementing the initial request.

8: Maybe there should be a flag for this feature, but I think it should be enabled by default if so. This is because many new users will expect this to work right away. If anyone has a good reason to make it default to off, then assume I agreed with them.

9: Handling images feels like a separate feature that could be proposed rather than a blocker to implementing the initial request. But I would say no for now to avoid scope creep, and to avoid additional items to need to reach consensus on.

Please do not consider my proposals above highly opinionated. If someone enters the discussion later with a strong opinion that differs from my own, let’s assume I agree with them unless I return and respond in a timely fashion.

I’ve attempted to make my proposals to the above solutions meet a minimally viable approach with iteration options for improvement. My spot check of the PR found that it meets or exceeds this minimally viable version (if it is fixed). Anything I’ve listed as a followup or separate feature would be something I would expect to not necessarily ever happen. Those would be features that would each require their own discussion and need not be implemented if there is not significant need within the userbase.

I think what we do have consensus on is that not having this feature at all is confusing for new users, since so many are coming from extended versions of markdown that allow for this. So I think it is important for Hugo to offer something in this space that attempts to meet the principle of least surprise. I believe the implementation in the PR (even in its somewhat broken state) does that.

A post was split to a new topic: Using Hugo with Foambubble