Discussion: Fixing [[wiki-links]] in GitHub Web UI

[jevakallio]

At the time of writing, links created with the [[wiki-link]] syntax work in VS Code and in rendered GitHub pages, but lead to non-existent pages on the GitHub Web UI. This is a meta-issue to track solutions and document the approach, once selected.

See context in foambubble/foam/wiki-links. TL;TR; There's a workaround at the end of the document, but it has some nasty trade-offs.

Ideas welcome!

[grst]

Could this jekyll plugin solve the problem?

[jevakallio]

@grst I'm not sure it would. The mission of that plugin is to generate relative HTML links, whereas our problem is that our MD link targets are to extensionless urls rather than file names. It could solve it, but not based on the documentation. If you'd like to try, I'd love to hear how it goes!

Bigger problem for that approach is that in order to integrate a new Jekyll plugin, AFAIK we need to build the entire Jekyll build toolset into our repo. For people's own workspaces that's fine and I'd definitely put it to our Recipes section as a solution, but I'd like to keep the initial template as low-code as possible.

[technoweenie]

The mediawiki style [[links]] are supported by the github wiki. I've barely started playing around with Foam, but basic things look good.

(picture replaced after manually deleting the autogenerated link references, I deleted foam-tips.md before pushing.)

[jevakallio]

@technoweenie wait, that's cool? How did you get the workspace into the wiki?

[technoweenie]

Every repo has a wiki repo at https://github.com/{user}/{repo}.wiki.git. Make sure the Wiki feature is enabled under repo settings, and you should be good to go! Creating the first wiki page shows you the wiki's repo url. Though, you might be able to push directly to it before creating the first page.

[pkoch]

One could even have a GH action that syncs those on push to master. Not sure if/how we could get syncing going the other way (wiki -> master).

[jevakallio]

@technoweenie I did not know that! It's an interesting piece of information, but like @pkoch said, we'd need to have a two-way sync.

Philosophically, I don't want to rely on anything GitHub specific, since Foam wants you to own your own thoughts and should avoid lock-in.

It's a nice option to have.

[stevemoser]

I was about to create an issue for this. Why not support GH's/Markdown's relative style links which work natively in VSCode and Jekyll as well which is why I prefer them over mediawiki style links:
https://github.blog/2013-01-31-relative-links-in-markup-files/
https://github.blog/2016-12-05-relative-links-for-github-pages/

[jevakallio]

As an update, after seeing @mathieudutour's gatsby-digital-garden project and how easily it works with Foam via foam-gatsby-template, I'm starting to think relying on the default "hidden" Jekyll build for GitHub pages is going to be too limiting in the long run, and we should start looking into a bespoke SSG stack for Foam.

[jevakallio]

Why not support GH's/Markdown's relative style links which work natively in VSCode and Jekyll as well which is why I prefer them over mediawiki style links

Thanks for the suggestion @stevemoser! Here's my thoughts on the matter.

Why [[mediawiki]]

Relative .md links is how I built the first personal version of Foam, but over time I began to feel that the writing ergonomics of auto-completed [[mediawiki]] links is important enough to go the extra effort to tool around them. Writing notes is fickle process, and creating densely networked notes, it's an activity we're doing a lot.

Though, as I write that, it occurs to me that the first-write experience could be implemented with snippets that expand from just the note name to full markdown links 🤔 🤔 🤔 🤔 🤔

On the other hand, the [[mediawiki]] links are a de-facto "standard" among the linked note taking apps, such as Bear, Obsidian, Roam, etc. and will provide familiarity and portability to those users.

In addition, because the link references in the current approach are listed at the end of the file, it should make automatically renaming and refactoring notes easier (only need to regenerate auto-generated sections, not rewrite your own content).

Your question has certainly made me think, but for the time being I'm still motivated to support [[mediawiki]] links, in addition to Markdown relative links.

Supporting markdown links

In your own notes, you are welcome to use relative .md links. They should already (mostly) work, and I intend to continue to support them, in addition to [[mediawiki]] links.

The only extension in the current recommended extensions stack that doesn't yet support relative Markdown links is the Markdown Notes plugin, and adding that feature should not be too complicated! Feel free to open an issue there.

To fix the GitHub Web UI issue latest comment there, we'll moving from the default built-in Jekyll config to a more bespoke static site generation approach, which will allow us to generate the link references in the standard, .md format, and unlock many other possible features as well.

[jevakallio]

@stevemoser thinking about it some more, and maybe you're right about this. As soon as we remove the mediawiki constraint, a lot of things become a lot easier.

Maybe I need to look at this from write-time tooling rather than storage/read time tooling perspective.

[RowanMcDonald]

👋 First off foam is awesome!

Wanted to mention a workaround that I've been using that isn't mentioned here. Similar to the suggestion that this could be synced by a github action, I've been using foam with both the "root" and the wiki repo as remotes.

git remote add wiki [email protected]:{username}/{repo}.wiki.git
git remote set-url --add --push origin [email protected]:{username}/{repo}.git
git remote set-url --add --push origin [email protected]:{username}/{repo}.wiki.git

This allows me to browse the pages in the wiki. However, it doesn't sync edits from the wiki... I /think/ that could be scripted up? Haven't had the need b/c I prefer local editing.

[inf-rno]

my 2 cents, I wouldn't remove mediawiki just because GitHub web UI doesn't support it. Given that Foam doesn't want vendor lock in, it seems contrary to restrict compatibility for a lack in one vendor.

[jevakallio]

@inf-rno Thanks for your feedback! I'm most likely going to continue supporting them, but the tradeoff is not just that GitHub pages doesn't support it.

Problem is that really Markdown doesn't support it at all, and so the subset of tools that support both markdown and media-wiki is much smaller than the superset that supports markdown. This means that we are fighting an uphill battle on integrations.

OTOH there is an entirely separate set of tools (and people) who like mediawiki links, and we want to support them too.

I keep flip flopping between convenience and completeness on this, haven't made final decisions yet, but like I said, most likely both will continue to be supported.

[alexandru]

@jevakallio

The mediawiki style [[links]] are supported by the github wiki

Unfortunately no, they aren't supported, GitHub's Wiki links are different because they are automatically flattened. So for example you can't organize your notes in sub-directories:

If the solution is to be compatible with GitHub's preview, those auto-generated links have to include the .md extension.

Also as a personal preference, note that I prefer GitHub's preview instead of GitHub Pages, because my repository is going to be private. I will not be able to publish my notes unless I protect that website with an HTTP password.

[jojanaho]

a proposal drafted in #82

[riccardoferretti]

This has been solved, see https://github.com/foambubble/foam/blob/master/docs/features/link-reference-definitions.md