Link Formatting and Autocompletion

When coming from Roam, Obsidian and such tools, you may be used to writing [wiki-links] in [[Title Case Format]]. Foam will eventually support this syntax (see: foambubble/rfcs#3), but for the time being, we do not.

Foam relies heavily on our [recommended-extensions], and each extension has slightly different semantics and edge cases. This is a short guide on how to name your files, format your links, and configure your editor so that you can enjoy Foam until our implementation catches up with our aspirations.

Short version

How to name your files

As described in [foam-file-format], Foam file names should not contain spaces. Because of the Markdown Notes extension’s default behaviour, we recommend naming your files in lower-dash-case:

ℹ️ This means:

✅ Valid lower-dash-case file names include:

❌ Some invalid names include:

Some of these file names may work for a subset of use cases (for example, if you don’t publish your Foam site), but we’d still recommend following these rules.

As per [foam-file-format], we eventually want to make Foam a lot more lenient. As per our [principles], you should be able to focus on your work and not fight against Foam. We’re not there yet, but we’ll get there.

Use [wiki-links] to link between files. Each link:

Foam autocompletion is provided by Markdown Notes. The default behaviour of Markdown Notes Autocomplete is to suffix .md to the end of suggestion, such as in the below screenshot:

Autocomplete from Markdown Notes with file extension

To change this behaviour, add the below to your .vscode/settings.json file:

"vscodeMarkdownNotes.noteCompletionConvention": "noExtension"

Now your autocomplete will look like the below screenshot:

Autocomplete from Markdown Notes without file extension

If you created your Foam from the official foam-template project after 27th July 2020, this setting should be already correctly set.