Skip to content

Keep your notes in a subfolder

Sometimes your notes live inside a bigger project rather than in a repository of their own — a knowledge-base folder next to your source code, say:

my-project/
├── knowledge-base/     ← your notes
├── src/
└── README.md

Foam works in this layout with three bits of configuration. There’s no single “Foam root” setting: instead you tell Foam which files to index, where your templates live, and where new notes should go.

1. Index only your notes

Section titled “1. Index only your notes”

In .vscode/settings.json:

{
  "foam.files.include": ["knowledge-base/**"]
}

Foam now builds the graph from your notes alone and ignores the rest of the project. Reload the window to apply it.

2. Point at your templates

Section titled “2. Point at your templates”
{
  "foam.files.include": ["knowledge-base/**"],
  "foam.templates.folder": "knowledge-base/.foam/templates"
}

Your Note Templates live at knowledge-base/.foam/templates/ rather than the project root.

3. Create new notes in the right place

Section titled “3. Create new notes in the right place”

By default, clicking a [[new-note]] placeholder creates the file at the top of the project. To send it to your notes folder instead, create knowledge-base/.foam/templates/new-note.md:

---
foam_template:
  filepath: 'knowledge-base/${FOAM_TITLE}.md'
---


# ${FOAM_TITLE}

Foam uses new-note.md whenever it creates a note without being told where to put it, so this covers Ctrl+clicking a placeholder as well as the Foam: Create New Note command.

For Daily Notes, do the same in knowledge-base/.foam/templates/daily-note.md:

---
foam_template:
  filepath: 'knowledge-base/journal/${FOAM_DATE_YEAR}-${FOAM_DATE_MONTH}-${FOAM_DATE_DATE}.md'
---


# ${FOAM_DATE_YEAR}-${FOAM_DATE_MONTH}-${FOAM_DATE_DATE}

Linking

Section titled “Linking”

[[wikilinks]] work exactly as they do anywhere else — [[my-note]] finds knowledge-base/my-note.md, because Foam only indexes your notes folder.

The one thing to know is that a leading slash means “the folder you opened in VS Code”, not “my notes folder”. So [[/my-note]] and [my note](/my-note.md) point at my-project/my-note.md, which isn’t where your notes are. Write [[/knowledge-base/my-note]] if you want the full path — or just use [[my-note]], which is shorter and unambiguous.

This also means you can link out to the rest of the project: [the build script](/scripts/build.sh) does what you’d expect, and works on GitHub too.

What stays at the project root

Section titled “What stays at the project root”

When you delete a note, Foam moves it to .foam/trash/ at the top of the project, and Smart Folders are saved under .foam/queries/. If you’d rather keep everything together, move those folders into your notes directory by hand — Foam will recreate them at the project root next time, so it’s a matter of taste rather than correctness.

Section titled “Related”

LINKS TO THIS PAGE

Recipes
Published with Foam