Foam Notes

Work with Foam note-taking workspaces in VS Code. Foam is a free, open-source personal knowledge management system using standard Markdown files with wikilinks.

Quick Reference

• Wikilinks: [[note-name]] — connect notes bidirectionally
• Embeds: ![[note-name]] — include content from other notes
• Backlinks: Automatically discovered connections to current note
• Tags: #tag or frontmatter tags: [tag1, tag2]
• Daily Notes: Alt+D or command "Foam: Open Daily Note"

Configuration

Copy config.json.template to config.json and edit to taste:

{
  "foam_root": "/path/to/your/foam-workspace",
  "default_template": "new-note",
  "default_notes_folder": "notes",
  "daily_note_folder": "journals",
  "author": "Your Name",
  "wikilinks": {
    "title_stopwords": ["home", "index", "readme", "draft", "template"],
    "suffixes": ["-hub"],
    "min_length": 3
  },
  "tags": {
    "editorial_stopwords": ["notes", "note", "foam", "markdown", "file", "page", "section"]
  }
}

Location: config.json in the skill directory (next to SKILL.md).

Config keys

Foam root priority order (highest to lowest)

• --foam-root CLI argument
• FOAM_WORKSPACE environment variable
• foam_root in config.json
• Auto-detect by finding .foam or .vscode directory
• Current working directory

Scripts

All scripts support --foam-root to override the workspace path.

init_templates.py

Initialize .foam/templates/ with starter templates from the official Foam template:

python3 scripts/init_templates.py              # Copy to current workspace
python3 scripts/init_templates.py --foam-root ~/notes
python3 scripts/init_templates.py --list      # Show available templates
python3 scripts/init_templates.py --force     # Overwrite existing
python3 scripts/init_templates.py --dry-run   # Preview what would be copied

Templates included:

• new-note.md — Default template for new notes
• daily-note.md — Template for daily notes
• your-first-template.md — Example template demonstrating VS Code snippets

create_note.py

Create a new note from template:

python3 scripts/create_note.py "My New Idea"
python3 scripts/create_note.py "Meeting Notes" --template meeting
python3 scripts/create_note.py "Research Topic" --dir research/

find_backlinks.py

Find all notes that link to a given note:

python3 scripts/find_backlinks.py "Machine Learning"
python3 scripts/find_backlinks.py "ml-basics" --format json

search_tags.py

Find notes by tag:

python3 scripts/search_tags.py "#research"
python3 scripts/search_tags.py machine-learning --include-frontmatter

list_tags.py

List all tags with usage counts:

python3 scripts/list_tags.py
python3 scripts/list_tags.py --hierarchy --min-count 3

graph_summary.py

Analyze the knowledge graph:

python3 scripts/graph_summary.py
python3 scripts/graph_summary.py --format json

daily_note.py

Create daily notes:

python3 scripts/daily_note.py
python3 scripts/daily_note.py --yesterday
python3 scripts/daily_note.py --template custom-daily
python3 scripts/daily_note.py --print-path   # Just output the path

suggest_wikilinks.py

Suggest wikilinks by finding text in a note that matches existing note titles:

python3 scripts/suggest_wikilinks.py my-note.md              # Interactive mode
python3 scripts/suggest_wikilinks.py my-note.md --apply 1,3,5  # Auto-apply
python3 scripts/suggest_wikilinks.py my-note.md --auto-apply   # Apply all
python3 scripts/suggest_wikilinks.py my-note.md --dry-run      # Preview only
python3 scripts/suggest_wikilinks.py my-note.md --with-aliases # Create [[target|text]] format

The script scans the note content and identifies words/phrases that match existing note titles in the archive. It presents them as a numbered list:

1. Line 12, col 8
   Text: "machine learning"
   Link to: [[machine-learning]]
   Context: ...working on machine learning projects...

Wikilink formats:

• Default: [[target]] — clean, simple links
• With --with-aliases: [[target|display text]] — preserves original text as alias

• Numbers to implement (e.g., 1 3 5)
• all to apply all suggestions
• none to cancel

suggest_tags.py

Suggest tags for a note based on content and existing tags in the archive:

python3 scripts/suggest_tags.py my-note.md              # Interactive mode
python3 scripts/suggest_tags.py my-note.md --apply all  # Add all suggested
python3 scripts/suggest_tags.py my-note.md --apply existing  # Only existing tags
python3 scripts/suggest_tags.py my-note.md --frontmatter     # Add to frontmatter

The script:

• Extracts keywords from note content
• Finds matching existing tags (with usage counts)
• Suggests new tags based on content analysis

• Existing Tags — Already used in your archive
• New Suggestions — Extracted from current note content

• Numbers (e.g., 1 3 5)
• all — all suggestions
• existing — only existing tags
• new — only new suggestions
• none — cancel
• Or type custom tags: #mytag #project

delete_note.py

Delete notes with optional backup and automatic backlink handling:

python3 scripts/delete_note.py "Old Note"                    # Interactive deletion
python3 scripts/delete_note.py "Old Note" --force          # Skip confirmation
python3 scripts/delete_note.py "Old Note" --backup         # Move to .foam/trash/
python3 scripts/delete_note.py "Old Note" --fix-links      # Remove wikilinks from other notes

Features:

• Backup mode: Moves note to .foam/trash/ instead of permanent deletion
• Backlink detection: Shows which notes link to the one being deleted
• Link fixing: Automatically removes wikilinks from other notes
• Confirmation: Prompts before deletion (skip with --force)

rename_note.py

Rename notes and automatically update all wikilinks:

python3 scripts/rename_note.py "Old Name" "New Name"       # Interactive rename
python3 scripts/rename_note.py "Old Name" "New Name" --force  # Skip confirmation

Features:

• Automatic wikilink updates: Finds and updates all [[old-name]] references
• File rename: Changes filename from old-name.md to new-name.md
• Title preservation: Keeps note content intact, only updates links
• Confirmation: Shows affected notes before proceeding

When to Use This Skill

Use this skill when:

• Creating or editing notes in a Foam workspace
• Working with wikilinks, backlinks, or the knowledge graph
• Analyzing note relationships and connections
• Setting up or configuring Foam templates
• Working with daily notes or tags
• Publishing Foam workspaces to static sites

Foam Workspace Structure

foam-workspace/
├── .vscode/
│   ├── extensions.json      # Recommended extensions
│   └── settings.json        # VS Code settings
├── .foam/
│   └── templates/           # Note templates (.md and .js)
├── journals/                # Daily notes (default location)
├── attachments/             # Images and files
├── *.md                     # Your notes
└── foam.json (optional)     # Foam configuration

Core Concepts

Wikilinks

Create connections between notes using double brackets:

See also [[related-concept]] for more information.

• Autocomplete with [[ + type note name
• Navigate with Ctrl+Click (or Cmd+Click on Mac)
• Create new notes by clicking non-existent links
• Link to sections: [[note-name#Section Title]]

Backlinks

Backlinks show which notes reference the current note — discovered automatically by Foam.

Access via:

• Command palette: "Explorer: Focus on Connections"
• Shows forward links, backlinks, or both

• Finding unexpected connections between ideas
• Identifying hub concepts (notes with many backlinks)
• Building context around ideas across domains

Tags

Organize notes beyond wikilinks:

# Inline tags
#machine-learning #research #in-progress

# Frontmatter tags
---
tags: [machine-learning, research, in-progress]
---

• Hierarchical: #programming/python
• Browse in Tag Explorer panel
• Search: "Foam: Search Tag"

Daily Notes

Quick daily journaling:

• Shortcut: Alt+D
• Command: "Foam: Open Daily Note"
• Snippets: /today, /yesterday, /tomorrow

See references/daily-notes.md for complete documentation.

Templates

Customize note creation. Foam looks for templates in .foam/templates/.

To initialize starter templates:

python3 scripts/init_templates.py

This copies official Foam templates to your workspace:

• new-note.md — Default template
• daily-note.md — Daily notes template
• your-first-template.md — Example with VS Code snippets

---
foam_template:
  filepath: '$FOAM_CURRENT_DIR/$FOAM_SLUG.md'
---

# $FOAM_TITLE

Created: $FOAM_DATE_YEAR-$FOAM_DATE_MONTH-$FOAM_DATE_DATE

$FOAM_SELECTED_TEXT

JavaScript templates (.js) — for smart, context-aware templates.

See references/templates.md for complete documentation.

Common Tasks

Creating a New Note

When creating notes programmatically (not via VS Code), always read the workspace template in .foam/templates/new-note.md first and follow its structure exactly.

In VS Code:

• Use "Foam: Create New Note" for default template
• Use "Foam: Create New Note From Template" to choose template
• Or click a non-existent wikilink [[new-note]]

Finding Note Relationships

• Backlinks: Check Connections panel for linked notes
• Graph View: Command "Foam: Show Graph" for visual network
• Tag Explorer: Browse notes by tag

Working with Embeds

Include content from other notes:

![[glossary]]

See the full definition above.

Publishing

Foam can publish to static sites:

• GitHub Pages (built-in template)
• Netlify
• Vercel
• GitLab Pages
• Custom static site generators (Gatsby, MkDocs, etc.)

Foam vs Obsidian

Configuration

Key .vscode/settings.json options:

{
  "foam.openDailyNote.onStartup": true,
  "foam.dateSnippets.format": "yyyy-mm-dd",
  "markdown.styles": [".foam/css/custom.css"]
}

Foam CLI Commands

Key VS Code commands:

• Foam: Open Daily Note — Create/open today's note
• Foam: Create New Note — Create from default template
• Foam: Create New Note From Template — Choose template
• Foam: Create New Template — Create new template
• Foam: Show Graph — Visualize knowledge graph
• Foam: Search Tag — Search for tagged notes
• Explorer: Focus on Connections — Show backlinks panel

Reference Documentation

• foam-overview.md — General Foam introduction and philosophy
• wikilinks.md — Complete wikilinks guide
• backlinks.md — Backlinks and knowledge discovery
• tags.md — Tag organization and filtering
• daily-notes.md — Daily note workflows
• templates.md — Template creation (Markdown and JavaScript)

External Resources

• Official site: https://foamnotes.com
• GitHub: https://github.com/foambubble/foam
• Discord: https://foambubble.github.io/join-discord/w

Tips

• Start small: Foam works best with consistent note-taking habits
• Link liberally: Create wikilinks even to non-existent notes (placeholders)
• Use the graph: Visualize your knowledge network to find gaps
• Trust the process: Backlinks reveal connections you didn't plan
• Keep it standard: Foam uses standard Markdown — your notes remain portable