Skip to content

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: foam-file-format.md.

ℹī¸ This means:
- All lowercase
- No spaces, punctuation or special characters
- Using dashes as word separators
- Ending with a .md extension

✅ Valid lower-dash-case file names include:
- roadmap.md
- foam-file-format.md
- f-f-f-f-falling.md

❌ Some invalid names include:

  • Roadmap.md (Name should not be capitalised)
  • foam file format.md (Name should not have spaces)
  • f-f-f-f-falling!.md (Name should not have special characters)

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:
- Should match file name exactly: [foam-file-format](../reference/foam-file-format.md), not [Foam File Format](../reference/foam-file-format.md)
- If you're reading this document on the Foam website, you might think: "That's not right!" What about links like foam-file-format! That uses spaces, capitalised letters, and everything!
- But if you look at the raw version of this document, you'll see that the link is actually written as [foam-file-format](../reference/foam-file-format.md): we make it look nicer with a bit of web magic and a sprinkle of JavaScript.
- Not include a file extension: [foam-file-format](../reference/foam-file-format.md), not [foam-file-format.md](../reference/foam-file-format.md).
- You might ask: If I can't use the .md extension, why does Foam autocomplete it for me?
- The answer is: It's a setting. See How to autocomplete your links correctly below.

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.