Foam Knowledge Base Tools

The @foam/core library provides several key functional areas:

• Workspace & graph: Managed via FoamWorkspace and FoamGraph to handle resources and their connections.
• Markdown parsing: Tools to parse notes and extract links, tags, frontmatter, and blocks.
• Resource providers: Pluggable support for file types via MarkdownResourceProvider and AttachmentResourceProvider.
• Note creation: Includes a template engine, variable resolution, and support for daily notes.
• Query engine: Supports DQL and JS-based queries for embedding dynamic content.
• Link integrity: Computes rename edits for wikilinks and markdown links.
• Utilities: Includes logging, slugs, hashtags, and path helpers.

The publishing layer is responsible for turning a workspace into artifacts without depending on VS Code APIs. It should be implemented as a framework-agnostic module.

Core Responsibilities:

• Discover and load publishable notes.
• Resolve wikilinks, aliases, and anchors using Foam's workspace/graph logic.
• Evaluate publish visibility rules.
• Rewrite links and expand/rewrite embeds for the target site.
• Compute backlinks and graph/search metadata.
• Render or precompute foam-query output.

Required Inputs:

• Workspace root
• Publish target configuration
• Output mode and path

Required Outputs:

• Transformed Markdown files.
• JSON indexes (for search, backlinks, graph, and route metadata).
• Copied static assets and attachments.

Foam facilitates knowledge management through several key abstractions and syntax patterns:

• Atomic notes: Writing focused Markdown documents centered on single topics.
• Wikilinks: Connecting ideas using [[double bracket]] syntax. This supports autocomplete and navigation within VS Code.
• Embeds: Including content from other notes using ![[note]] syntax.
• Backlinks: Automatically discovering connections between notes via a dedicated Backlinks panel.
• Graph visualization: A visual representation of your knowledge network.
• Daily notes: Capturing timestamped thoughts, often using templates and snippets.
• Tags: Organizing and filtering content using a tag system.

The CLI needs to know the root directory of your Foam workspace to resolve notes and tags. It determines the workspace root using the following priority order:

1. The --workspace <dir> global flag.
2. The FOAM_WORKSPACE environment variable.
3. The current working directory (cwd).

You can set FOAM_WORKSPACE in your shell profile to avoid passing the flag or changing directories constantly.

Foam collects anonymous usage data (e.g., which commands are used, feature configurations) to prioritize development. It never collects note content, file names, or personal information.

Respecting VS Code Settings

Foam respects the global VS Code telemetry setting: telemetry.telemetryLevel. If you have disabled telemetry in VS Code, Foam will not send any data.

Inspecting Telemetry

To see what data is being sent, you can inspect the Foam output channel:

1. Open the Command Palette.
2. Run Foam: Set log level and select Debug.
3. Check the Foam output channel for telemetry events.

For a full list of collected data and opt-out instructions, see the [[telemetry]] documentation.

Foam integrates with VS Code panels to provide different perspectives on your knowledge base:

• Foam: links: Displays incoming and outgoing links for the active note.
• Foam: Orphaned Notes: Lists notes with no incoming or outgoing links.
• Tag Explorer: Provides a hierarchical view of all tags in the workspace.
• Foam: Graph: A visual representation of note connections.
• Outline View: Shows the heading hierarchy of the current Markdown note for quick navigation.
• Timeline View: Located in the Explorer panel, it shows the history of file changes (Git commits and file saves).

Because foam-vscode and @foam/cli bundle @foam/core at build time (using esbuild) and declare it as a devDependency, Changesets' automatic internal-dependency bumping (updateInternalDependencies) will not automatically cascade a @foam/core version bump to them.

Crucial Rule: If a change affects packages/foam-core, your changeset fragment must explicitly include foam-vscode and @foam/cli (typically as patch bumps). If you only bump @foam/core, the extension and CLI will publish updated code under stale version numbers.

In Foam, links to non-existent notes are treated as placeholders.

• Visual Cues: Placeholders are highlighted with a different color in the editor and styled specially in preview mode.
• Creation: Clicking a placeholder in the editor automatically creates the corresponding note.
• Discovery: You can find all existing placeholders by looking at the Placeholders treeview in the sidebar.

Commands that operate on specific notes (like show, move, or delete) accept a positional <identifier>. This identifier is resolved using the same logic as wikilinks (supporting short names or aliases).

Alternatively, you can use the --path <path> flag to target a note by its exact file path.

Note: If an identifier matches more than one note, the command will exit with code 1 and list the matching candidates.

You can embed dynamic, auto-updating lists, tables, and counts of notes directly in your Markdown preview. This is achieved using foam-query and foam-query-js code blocks. For a full reference of query capabilities, consult the official Foam Queries documentation.

# Example placeholder for a foam-query block