foam-notes

# Foam Notes Work with Foam note-taking workspaces in VS Code. [Foam](https://foamnotes.com) 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: ```json { "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 | Key | Type | Default | Description | |-----|------|---------|-------------| | `foam_root` | string | `""` (auto-detect) | Path to your Foam workspace | | `default_template` | string | `"new-note"` | Template for new notes | | `default_notes_folder` | string | `"notes"` | Subfolder for new notes | | `daily_note_folder` | string | `"journals"` | Subfolder for daily notes | | `author` | string | `""` | Author name for note creation | | `wikilinks.title_stopwords` | list | `[]` | Note titles to never match as wikilinks (e.g. `"home"`, `"index"`, `"todo"`). Add any generic filenames from your workspace that produce false positives. | | `wikilinks.suffixes` | list | `[]` | Filename suffixes whose base stem should also register as a match key. For example, if you name your hub/MOC notes `docker-hub.md`, add `"-hub"` here so that "docker" in prose matches `docker-hub.md`. | | `wikilinks.min_length` | int | `3` | Minimum key length to consider for wikilink matching | | `tags.editorial_stopwords` | list | `[]` | Domain-specific words to exclude from tag suggestions (in addition to standard English stopwords). | ### Foam root priority order (highest to lowest) 1. `--foam-root` CLI argument 2. `FOAM_WORKSPACE` environment variable 3. `foam_root` in config.json 4. Auto-detect by finding `.foam` or `.vscode` directory 5. Current working directory See references/configuration.md for complete documentation. ## 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: ```bash 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: ```bash 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: ```bash python3 scripts/find_backlinks.py "Machine Learning" python3 scripts/find_backlinks.py "ml-basics" --format json ``` ### search_tags.py Find notes by tag: ```bash python3 scripts/search_tags.py "#research" python3 scripts/search_tags.py machine-learning --include-frontmatter ``` ### list_tags.py List all tags with usage counts: ```bash python3 scripts/list_tags.py python3 scripts/list_tags.py --hierarchy --min-count 3 ``` ### graph_summary.py Analyze the knowledge graph: ```bash python3 scripts/graph_summary.py python3 scripts/graph_summary.py --format json ``` ### daily_note.py Create daily notes: ```bash 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: ```bash 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 Respond with: - 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: ```bash 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: 1. Extracts keywords from note content 2. Finds matching existing tags (with usage counts) 3. Suggests new tags based on content analysis Presented as numbered list with two sections: - **Existing Tags** — Already used in your archive - **New Suggestions** — Extracted from current note content Respond with: - 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: ```bash 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: ```bash 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: ```markdown 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]]` See references/wikilinks.md for complete documentation. ### 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 Use backlinks for: - Finding unexpected connections between ideas - Identifying hub concepts (notes with many backlinks) - Building context around ideas across domains See references/backlinks.md for complete documentation. ### Tags Organize notes beyond wikilinks: ```markdown # 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" See references/tags.md for complete documentation. ### Daily Notes Quick daily journaling: - **Shortcut**: `Alt+D` - **Command**: "Foam: Open Daily Note" - **Snippets**: `/today`, `/yesterday`, `/tomorrow` Template: `.foam/templates/daily-note.md` See references/daily-notes.md for complete documentation. ### Templates Customize note creation. Foam looks for templates in `.foam/templates/`. **To initialize starter templates:** ```bash 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 **Markdown templates** (`.md`): ```markdown --- 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: 1. Use "Foam: Create New Note" for default template 2. Use "Foam: Create New Note From Template" to choose template 3. Or click a non-existent wikilink `[[new-note]]` ### Finding Note Relationships 1. **Backlinks**: Check Connections panel for linked notes 2. **Graph View**: Command "Foam: Show Graph" for visual network 3. **Tag Explorer**: Browse notes by tag ### Working with Embeds Include content from other notes: ```markdown ![[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.) See recipes in Foam documentation for publishing options. ## Foam vs Obsidian | Feature | Foam | Obsidian | |---------|------|----------| | Wikilinks | `[[note]]` | `[[note]]` | | Embeds | `![[note]]` | `![[note]]` | | Platform | VS Code | Dedicated app | | Plugin ecosystem | Minimal (VS Code extensions) | Extensive | | File format | Standard Markdown | Markdown with extensions | | Configuration | `.vscode/settings.json` | `.obsidian/` folder | | Price | Free | Freemium | Both use the same core linking syntax. Foam prioritizes simplicity and standard formats. ## Configuration Key `.vscode/settings.json` options: ```json { "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) Read these files for detailed information on specific features. ## External Resources - **Official site**: https://foamnotes.com - **GitHub**: https://github.com/foambubble/foam - **Discord**: https://foambubble.github.io/join-discord/w ## Tips 1. **Start small**: Foam works best with consistent note-taking habits 2. **Link liberally**: Create wikilinks even to non-existent notes (placeholders) 3. **Use the graph**: Visualize your knowledge network to find gaps 4. **Trust the process**: Backlinks reveal connections you didn't plan 5. **Keep it standard**: Foam uses standard Markdown — your notes remain portable