Link Reference Definitions

Introduction

When you use [[wiki-links]], the foam-vscode extension will automatically generate Markdown Link Reference Definitions at the bottom of the file. This is done to make the content of the file compatible with various Markdown tools (e.g. parsers, static site generators, VS code plugins etc), which don't support [[wiki-links]].

Example

The following example:

- [[wiki-links]]
- [[github-pages]]

...generates the following link reference definitions to the bottom of the file:

[wiki-links]: wiki-links "Wiki Links"
[github-pages]: github-pages "Github Pages"

You can open the raw markdown to see them at the bottom of this file

Specification

The three components of a link reference definition are [link-label]: link-target "Link Title"

• 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
  • By default we generate links without extension. This can be overridden, see Configuration below
• "Link Title" Optional title for link (The Foam template has a snippet of JavaScript to replace this on the website at runtime)

Configuration

You can choose to generate link reference definitions with or without file extensions, depending on the target, or to disable the generation altogether. As a rule of thumb:

• Links with file extensions work better with standard markdown-based tools, such as GitHub web UI.
• Links without file extensions work better with certain web publishing tools that treat links as literal urls and don't transform them automatically, such as the standard GitHub pages installation.

By default, Foam generates links without file extensions for legacy reasons, but this may change in future versions.

You can override this setting in your Foam workspace's settings.json:

• "foam.edit.linkReferenceDefinitions": "withoutExtensions" (default)
• "foam.edit.linkReferenceDefinitions": "withExtensions"
• "foam.edit.linkReferenceDefinitions": "off"

Ignoring files

Sometimes, you may want to ignore certain files or folders, so that Foam doesn't generate link reference definitions to them.

For instance, if you're using a local instance of Jekyll, you may find that it writes copies of each .md file into a _site directory, which may lead to Foam generating references to them instead of the original source notes.

You can ignore the _site directory by adding the following to your .vscode/settings.json:

  "files.exclude": {
    "**/_site": true
  },
  "files.watcherExclude": {
    "**/_site": true
  },

After changing the setting in your workspace, you can run the [[workspace-janitor]] command to convert all existing definitions.

[[todo]] _Implement a `foam.eclude

Future improvements

See [[link-reference-definition-improvements]] for further discussion on current problems and potential solutions.