Support wiki-style internal page links

[rcoreilly]

It would be great if hugo could support wiki-style page links, as in the git-hub wiki syntax:
https://help.github.com/articles/adding-links-to-wikis/

This has been suggested a few times it seems:

• https://discourse.gohugo.io/t/internal-links-hugo-as-wiki-backend/3518/3
• https://discourse.gohugo.io/t/automated-linking-wiki-like-behaviour/4244
• https://discourse.gohugo.io/t/support-wiki-internal-link-converson-to-relref-shortcode/6074

But I didn't see an open bug ticket on it, so.. here goes -- please mark as a duplicate if I somehow missed it.

Proposal:

• This would make a link to another wiki page with given title: [[Page Title]] -- it would find page based on the title property of the pages, and render the link (via the pathed file name) for you.

• You can optionally include alternative link text: [[Alternative Text|Page Title]] and also use the file name, but it would still use the title for the link if avail for that page: [[docs/my_file_name]] renders link with text as title of that page

Motivation:

• Current link syntax requires significant duplicate typing -- one of the main design criteria for the Go language was to remove all that "stuttering" kind of thing -- very annoying to constantly be typing something like [My Page Here](docs/my_page_here).

• The [[ ]] link syntax is standard on the git hub wiki, and on the widely-used mediawiki, so it will be familiar to many users.

• Using the page title instead of the path is more robust if you decide to reorganize your file structure.

• We are just experimenting with porting our wiki from mediawiki to hugo and this link issue is the main remaining barrier to having the new platform be a clear win! Hugo can be a great wiki platform, but the high density of internal links in a wiki requires this simpler kind of link syntax.

Thanks for making such an awesome tool!

[maiki]

I've dealt with internal linking for a while, so I am gonna throw out the low-hanging fruit, planning-wise:

• How does the internal linking work for capitalization? Does it standardize the title using the same rules as slugs?
• How does it handle namespaces/sections? When I type [[About]], does it go to /about/ or /other-project/about/? We want to make sure folks don't need to change their site structure in order to use the link brackets effectively.
• Will it throw errors if links are non-existent? For instance, I change a page title, on the next build will there be errors about the links that were pointing at that page title?

[bep]

@maiki about the middle one, and I guess the challenging part of this, is about the handling of ambiguous links, i.e. which one to pick. I'm not sure how MediaWiki handles this, but I'm pretty sure they "pick one".

To me, it would be natural to pick the one closest in "file system distance", so given this tree:

about/blog
about/blog/subsection

A link to about in blog/subsection would be ambiguous, but pick the one with the longest prefix match, i.e. about/blog/subsection. This is also extremely fast.

[maiki]

I'm not sure how MediaWiki handles this, but I'm pretty sure they "pick one".

@bep in MediaWiki they have the concept of namespaces, and the default namespace is without prefix. Taking Wikipedia for example (assume editing on a page there), here are some internal link examples:

• [[Tron]] > https://en.wikipedia.org/wiki/Tron
• [[Talk:Tron]] > https://en.wikipedia.org/wiki/Talk:Tron
• [[User:マイキ]] > https://en.wikipedia.org/wiki/User:マイキ

Namespaces are nearly identical to "sections" in Hugo as they are used by site editors; there are some special namespaces, but they are primarily used to "differentiate between the purpose of the pages at a high level".

But note that following the method prescribed by MediaWiki may not make sense elsewhere. URLs and linking is kinda wonky, and presents a lot of caveats. For instance, wiki articles are named intentionally as fact, whereas the title of my site's about page can change over time.

I like the idea of making the rel/relref shortcode work with double brackets. It doesn't help convert a MediaWiki instance to Hugo as @rcoreilly is doing, but that process is going to be finicky anyhow, since Hugo doesn't produce default MediaWiki URL structures out of the box. If some massaging is going to be done anyhow, I'd opt to build a system that make refs easy, and tweak content being processed by Hugo.

BTW, the wiki included in GitHub projects is called Gollum, and it has a way to do internal linking. I've used Gollum (here and in GitLab), and the linking works really nice. It isn't the "link by title" that @rcoreilly requested, but it does "[s]upport wiki-style internal page links". ^_^

[bep]

Namespaces are nearly identical to "sections" in Hugo as they are used by site editors

I would not say that.

• The only reason linking kind of works on Wikipedia is that it is, in practice, one big namespace. There are the "talk" namespace etc., but that is not part of the "daily article editing".
• Since MediaWiki is a server software, they can also suggest/autocomplete links.
• In Hugo, namespaces (i.e. sections) are very common, and the only way this is going to work is if the user does not have to think about these sections.
• This should also follow "regular Github wiki syntax" to be of real value.

[maiki]

The only reason linking kind of works on Wikipedia is that it is, in practice, one big namespace. There are the "talk" namespace etc., but that is not part of the "daily article editing".

Namespaces don't change often on Wikipedia, but they are something that folks change in general MediaWiki usage, and for the same reasons as with Hugo: as a way to structure content.

[rcoreilly]

The transition from a single big namespace has been a major issue in migrating from mediawiki to Hugo -- the ability to edit files locally using e.g., emacs (and see changes immediately on the local hugo server) is a major plus, but then it becomes more important to organize the files in subdirectories to avoid a single massive directory that is hard to manage. Nevertheless, having the convenience of a single effective namespace based on titles seems like the "best of both worlds". And if you want to be unambiguous, you can always have the option of using the file path as in the ref/relref.

Here's a possible spec for how it could work to address above questions:

• If the link has a / in it, then look for a filename, otherwise look for a page title
  • could have a param option to exclude title search if that seems important for some users -- in which case it works like ref/relref (except for the title text part)
  • if not found, render "link not found: <the link>" right on the page -- in general it seems like providing error feedback right on the page is better than in the server output -- that is where you're looking when you're editing.
  • if multiple matches, count the number of characters in common at start of file path for each found page vs. the current page path -- higher number wins (this will favor items in the same path -- similar to @bep's suggestion) -- if still a tie then pick the one with the shortest path, because you have now determined that the file is not within the same section, and thus the most general version should be chosen.
• Unless an explicit alternative text has been provided, use the page title for the link text. I'm not sure what the @maki's question is about capitalizing? The title is what the user has specified, and typically it seems like this will be a nice human-readable capitalized or whatever according to user's preference. Note that even if you use the page path in the link, it will replace that with the page title, which seems like a big win over using ref/relref.
  • btw, I tried implementing some of this functionality myself using ref/relref in a shortcode, to massage the page path to discard the path and upper-case it, but I couldn't find any string functions exposed in the template language -- might be good to expose some of those so people can do some basic string manipulations within templates.
  • can expose this [[ ]] functionality as a template function too, e.g., titleref or something like that, and then if people want to manipulate the results they can.

[rcoreilly]

BTW, I did manage to use the new .Site.GetPage functionality to write a shortcode "page.html" that takes the path as input and automatically uses the page title in the link, saving the double-typing but still requiring a lot more keystrokes than [[ ]] -- including this here in case anyone else looking for this functionality is interested in a stop-gap measure until the real thing is implemented :)

usage:

{{< page "path/page" >}}

code for page.html -- put in layouts/shortcodes

{{ $inlnk := .Get 0 }}{{ $pgfl := printf "%s.md" $inlnk }}{{ $pgtt := .Site.GetPage "page" $pgfl }}{{ if $pgtt }} <a href="{{ $pgtt.URL }}"> {{ $pgtt.Title }} </a>{{ else }}<a href="{{ .Site.BaseURL }}{{ $inlnk }}"> {{ $pgfl }} Not Found! </a>{{ end }}

Interestingly, it even works with just entering the page name without the full path -- I guess the getpage is robust that way, but probably doesn't have the advanced logic mentioned above.

Also please ignore comment about template functions for strings -- somehow I missed the key page in the docs about that!

[bep]

I guess the getpage is robust that way, but probably doesn't have the advanced logic mentioned above.

No, it is a "light version" of the "tree logic" I was talking about; the search order is

1. Exact match (i.e. path + filename)
2. Filename

[stale]

This issue has been automatically marked as stale because it has not had recent activity. The resources of the Hugo team are limited, and so we are asking for your help.
If this is a bug and you can still reproduce this error on the master branch, please reply with all of the information you have about it in order to keep the issue open.
If this is a feature request, and you feel that it is still relevant and valuable, please tell us why.
This issue will automatically be closed in the near future if no further activity occurs. Thank you for all your contributions.

[rcoreilly]

I still think this would be a great and widely used feature, and should be relatively easy to implement, so please do keep the ticket open!

[stale]

This issue has been automatically marked as stale because it has not had recent activity. The resources of the Hugo team are limited, and so we are asking for your help.
If this is a bug and you can still reproduce this error on the master branch, please reply with all of the information you have about it in order to keep the issue open.
If this is a feature request, and you feel that it is still relevant and valuable, please tell us why.
This issue will automatically be closed in the near future if no further activity occurs. Thank you for all your contributions.