Skip to content

Latest commit

 

History

History
73 lines (46 loc) · 4.29 KB

wiki-links.md

File metadata and controls

73 lines (46 loc) · 4.29 KB
Raw

Wiki Links

Foam enables you to Link pages together using [[file-name]] annotations with the help of VS Code Markdown Notes extension.

  • Both [[file-name]] and [[file-name.md]] work
  • Type [[ and start typing a file name for autocompletion.
  • Cmd + Click on file name to navigate to file (F12 also works while your cursor is on the file name)
  • Cmd + Click on non-existent file to create that file in the workspace.

If the F12 shortcut feels unnatural you can rebind it at File > Preferences > Keyboard Shortcuts by searching for editor.action.revealDefinition.

The Foam for VSCode extension automatically generates markdown link reference definitions at the bottom of the file to make wiki-links compatible with Markdown tools and parsers

Why don't [[wiki-links]] work on GitHub

TL;DR; workaround in the end.

If you click any of the wiki-links on GitHub web UI (such as the README.md of a project), you'll notice that the links break with a 404 error.

At the time of writing (June 28 2020) this is a known, but unsolved error. To understand why this is the case, we need to understand what we are trading off.

If you look at link references the bottom of any Foam workspace file that uses wiki-links, you should see an automatically generated list of references that look as follows:

[wiki-links]: wiki-links "Wiki Links"
[other-page]: other-page "Other Page"

These exist to make [[wiki-links]] compatible with Markdown-consuming tools such as static site generators, VS Code plugins etc. So, why don't they work on GitHub?

The three components of a link reference definitions are:

  • link label: The link text to match in the surrounding markdown document. This matches the inner bracket of the double-bracketed [[wiki-link]] notation
  • link destination The target of the matched link
  • "Link Title" Optional title for link (The Foam template has a snippet of JavaScript to replace this on the website at runtime)

The issue is the middle link destination component. It's configured to point to the file name without file extension, i.e. "file-name" instead of "file-name.md". This is to make the GitHub Pages rendering work, because if we generated the links to file-name.md, the links would point to the raw markdown files instead of their generated HTML versions.

Environment file-name file-name.md
VS Code Works Works
GitHub pages Works Breaks
GitHub UI Breaks Works

So as you can see, we've prioritised GitHub Pages over GitHub Web U for the time being.

Ideally, we'd like a solution that works with both, but I haven't thought of it yet. Ideas include:

  • Writing a better static side generator that works with file-name.md link targets. This is on the [roadmap], but for the time being GitHub Pages support is as must-have.
  • Adding a configuration setting to generate file-name.md link targets. This is fine and I would accept this contribution to foam-vscode, but it doesn't solve the core problem.

An acceptable solution may include one where we don't generate link reference definitions at all, but if we do, ideally, we'd like to generate file-name.md links since those are more standards compatible for different markdown tools.

I'm sure there's an elegant-ish solution out there. Ideas and suggestions welcome that the tracking issue on GitHub

Workaround

For the time being, you can use regular [markdown links](markdown-link.md) syntax.

Pros:

  • This will work on all platforms.

Cons:

  • It will break the Markdown Notes [backlinking] support
  • Less convenient to write