Support wiki-style internal page links

[heitorPB]

It would be great for Zola to support wiki-style page links (a.k.a. wikilinks).

Wiki-links are in the format [[Foo Bar]] that translates to [Foo Bar](path/foo-bar) and [[Foo Bar|Custom Title]] that translates to [Custom Title](path/foo-bar). Those links are for internal pages only.

This format is used in:

• GitHub wikis (https://help.github.com/articles/adding-links-to-wikis/).
• Obsidian.
• vim-wiki.
• supported by Pandoc (Markdown, CommonMark: add support for wiki links. [API change] jgm/pandoc#7705).

I know Zola has its own format for that (which is much more comfortable to use than what I saw on other systems), but Wiki links are gaining a lot of popularity. Supporting that would make the transition from other systems to Zola easier (my particular use case) and would add good tooling support to editing Zola-powered websites (in Vim/Neovim, hitting on a markdown/wiki link opens that document).

This was requested on the Forums but it was dismissed without discussion. There was another forum post that mentions the lack of support for wikilinks.

[c-git]

The maintainer did respond and say it wouldn't be supported on the first request that you mentioned. But if I may add my 2 cents. There are already 2 ways to add links in Common Mark which is what Zola uses. I am all for options but too many options can lead to confusion, make the project more difficult to maintain and actually lead to a "less good" product in the end.

I'm of the opinion that you can add a "preprocessor" before you call zola that would convert the "wiki links" to one of the options supported in common mark. I'm happy to give a try at helping with the preprocessor if that is an option you think would meet your needs.

A general sketch of what I'm thinking is you have this program that will run through the content folder and look for a regex that matches the format and the use a capture group to get the info and the replace it in place by editing the file. (Maybe backing it up first?)

[Keats]

Yeah as mentioned by @c-git we already added a way to add link that is not in CommonMark. Adding another way to do the same thing but less powerful/obvious is not going to happen.

How would you link to the following files with Wiki links for example:

• content/blog/2022-01-01_index.md
• content/wiki/_index.md
• content/wiki/colocated/index.md

[heitorPB]

I agree with you to avoid feature creep. That can easily add a huge burden on the dev team. Adding features that are not exactly new should be decided with care. That's why I started this issue: to have this discussion :)

I'm of the opinion that you can add a "preprocessor" before you call zola that would convert the "wiki links" to one of the options supported in common mark

I'm currently using this strategy. I have a Perl script that "translates" wiki links. But as my internal wiki grew, this script is now taking ~10s to parse all my ~2k pages. This is getting too annoying for me.

As for pages with same title, but in different places, I have something like this in my Ultimate Index page:

• [[diary/index|Diary entries]] -> [Diary Entries](diary/index.html)
• [[wiki/index]] -> [Index](wiki/index.html)
• [[wiki/work/index]] -> [Index](wiki/work/index.html)

In the wikilink format you can specify a path to the file to solve any ambiguity.

[c-git]

I'd add a small db to check last modified time to avoid processing files that have already been processed and that should cut down the runtime substantially.

[lebarde]

Hello,
It is my very first incursion into zola (I used Hugo long... a-go).
Actually I love writing inside Obsidian, and I also love the way Obsidian manages links in the wikilink’s style. But I acknowledge it is a major breach into the Markdown uses.
@heitorPB I would be immensely pleased if you shared your Perl script. Maybe, as c-git says, a preprocessor would be of great use. I would be very pleased to dive into this.
Thanks by advance! Cheers!

[heitorPB]

@lebarde here's the script I used in the past, this is from my Hugo times, should still work but requires tweaks for your use:

#!/usr/bin/env bash

for f in content/posts/*md;
do
	# change [[file|title]] -> [title]({{< relref file.md >}})
	perl -pi -e  's!\[\[(.*?)\|(.*?)]]!\[\2\]\({{< relref "\1.md" >}}\)!g' "$f"

	# change [[file]] -> [file]({{< relref file.md >}})
	perl -pi -e  's!\[\[(.*?)]]!\[\1\]\({{< relref "\1.md" >}}\)!g' "$f"
done

[Keats]

I had a look at that again since pulldown-cmark has an option for that. I'm not using any software using those links so looking for some more input on top of https://help.obsidian.md/links.

If I understand correctly, [[Some name]] would implicitely look for a Some name.md file somewhere in the content. Since we can't disambiguate during a build that would be an error if you have 2 files with that name. Looking at https://blot.im/how/formatting/wikilinks#examples it seems the path is relative to the current local path of the file so moving it might break the links inside. It could also refer to the title/slug so to properly render you would need to get the title + path + slug from content/ for all content before rendering the markdown.

Now a edge case: we can render markdown in a template via the markdown filter, which might be done in pages that don't have an associated content document. I guess we would error on those?
Edit: I guess they could refer to the slug or full path?

[c-git]

Do you have an idea if there is a performance penalty for getting the title, path and slug before rendering?

[Keats]

Not much, except the one-time hashmaps allocation but it will contain only references. The only perf issue is having to search all of those for every link but that should not be a big deal compared to the syntax highlighting overhead for example.

[c-git]

Well given the performance cost isn't substantial maybe it's actually not a bad idea as it would make life easier for some users. In cases like templates where it's not possible to disambiguate then as long as the error message is clear I think it seems like a good idea.

[Keats]

I've rewritten the markdown renderer entirely in a branch so that should not be too hard to add once i've done all the other bits I want to first.

[c-git]

Would be nice if we could line up volunteers for once you're done to test who have experience using wikilinks. @heitorPB @lebarde are you all able to test once it's "ready for testing"?