github/foam
1
1
Fork 0
mirror of https://github.com/foambubble/foam.git synced 2026-01-08 21:48:15 -05:00
Code Issues Packages Projects Releases Wiki Activity

Updated documentation

Browse Source
This commit is contained in:
Riccardo Ferretti
2025-09-06 11:54:15 +02:00
parent 0c7b1458f5
commit f57b8ec9b6
31 changed files with 1390 additions and 604 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
docs/Achieving Greater Privacy and Security.md
View File

@@ -1,29 +0,0 @@
# Achieving Greater Privacy and Security
Foam, at its heart and committed to in its [Principles](https://foambubble.github.io/foam/principles), allows the user to control their content in a flexible and non-prescriptive manner. This extends to user preferences, or requirements depending on application and context, around both privacy and security. One way that these use cases can be met is through the use of open-source and not-for-profit mechanisms in the user's workflow to provide a functional equivalence.
Here are a few suggestions on increasing privacy and security when using Foam.
## VS Codium: The Open Source build of VS Code
Foam is built upon VS Code, itself a Microsoft product built on top of an open source project.
As can be found [here](https://github.com/Microsoft/vscode/issues/60#issuecomment-161792005) the **VS Code product itself is not fully open source**. This means that its inner workings are not fully transparent, facilitating the collection and distribution of your data, as specified in its [Privacy Statement](https://devblogs.microsoft.com/visualstudio/privacy/).
If you prefer a fully open source editor based on the same core of VS Code (and for most intents and purposes equivalent to it), you can try [VSCodium](https://github.com/VSCodium).
In its own introduction it is described as, "Binary releases of VS Code without MS branding/telemetry/licensing". Installation packages are easily available across Windows, Unix and Linux (or you can build it from source!).
Access to the VS Code marketplace of add-ons remains in place, including the Foam extension.
The change you will notice in using VS Code versus VS Codium - simply speaking, none. It is, in just about every way you will think of, the same IDE, just without the Microsoft proprietary licence and telemetry. Your Foam experience will remain as smooth and productive as before the change.
## Version Control and Replication
In Foam's [Getting Started](https://foambubble.github.io/foam/#getting-started) section, the set up describes how to set up your notes with a GitHub repository in using the template provided. Doing so provides the user with the ability to see commits made and therefore versions of their notes, allows the user to work across devices or collaborate effectively with other users, and makes publishing to GitHub pages easy.
It's important at the same time to point out the closed-source nature of GitHub, being owned by Microsoft.
One alternative approach could be to use [GitLab](https://gitlab.com/), an open source alternative to GitHub. Whilst it improves on the aspect of transparency, it does also collect usage details and sends your content across the internet.
And of course data is still stored in clear in the cloud, making it susceptible to hacks of the service.
A more private approach would manage replication between devices and users with a serverless mechanism like [Syncthing](https://syncthing.net). Its continuous synchronisation means that changes in files are seen almost instantly and offers the choice of using only local network connections or securely using public relays when a local network connection is unavailable. This means that having two connected devices online will have them synchronised, but it is worth noting that the continuous synchronisation could result in corruption if two users worked on the same file simultaneously and it doesn't offer the same kind of version control that git does (though versioning support can be found and is described [here](https://docs.syncthing.net/users/versioning.html)). It is also not advisable to attempt to use a continuous synchronisation tool to sync local git repositories as the risk of corruption on the git files is high (see [here](https://forum.syncthing.net/t/can-syncthing-reliably-sync-local-git-repos-not-github/8404/18)).
If you need the version control and collaboration, but do not want to compromise on your privacy, the best course of action is to host the open source GitLab server software yourself. The steps (well described [here](https://www.techrepublic.com/article/how-to-set-up-a-gitlab-server-and-host-your-own-git-repositories/)) are not especially complex by any means and can be used exclusively on the local network, if required, offering a rich experience of "built-in version control, issue tracking, code review, CI/CD, and more", according to its website, [GitLab / GitLab Community Edition · GitLab](https://gitlab.com/rluna-gitlab/gitlab-ce).

17
docs/big-vision.md
View File

@@ -1,17 +0,0 @@
# Big Vision
[[todo]]
- What methodologies do we want to support?
- Zettelkasten?
- GTD? (Get Things Done)
- Digital gardening?
- Blogging/publishing
- Others?
- Be an educational tool as much as a tool to implement these methodologies
- What use cases are we working towards?
-[[todo]] User round table
[//begin]: # "Autogenerated link references for markdown compatibility"
[todo]: dev/todo.md "Todo"
[//end]: # "Autogenerated link references"

9
docs/dev/foam-file-format.md
View File

@@ -1,6 +1,6 @@
# Foam File Format
This file is an example of a valid Foam file. Essentially it's just a markdown file with a bit of additional support for MediaWiki-style `[[wikilinks]]`.
This file is an example of a valid Foam file. Essentially it's just a markdown file with a bit of additional support for MediaWiki-style `[[wikilinks]]` and note embeds.
Here are a few specific constraints, mainly because our tooling is a bit fragmented. Most of these should be eventually lifted, and our requirement should just be "Markdown with `[[wikilinks]]`:
@@ -10,7 +10,8 @@ Here are a few specific constraints, mainly because our tooling is a bit fragmen
- This is a temporary limitation and will be lifted in future versions.
- At least `.mdx` will be supported, but ideally we'll support any file that you can map to `Markdown` language mode in VS Code
- **In addition to normal Markdown Links syntax you can use `[[MediaWiki]]` links.** See [[wikilinks]] for more details.
- **You can embed other notes using `![[note]]` syntax.** This supports various modifiers like `content![[note]]` or `full-card![[note]]` to control how content is displayed.
[//begin]: # "Autogenerated link references for markdown compatibility"
[wikilinks]: ../user/features/wikilinks.md "Wikilinks"
[//end]: # "Autogenerated link references"
[//begin]: # 'Autogenerated link references for markdown compatibility'
[wikilinks]: ../user/features/wikilinks.md 'Wikilinks'
[//end]: # 'Autogenerated link references'

128
docs/index.md
View File

@@ -1,10 +1,25 @@
# Foam
# What is Foam?
**Foam** is a personal knowledge management and sharing system inspired by [Roam Research](https://roamresearch.com/), built on [Visual Studio Code](https://code.visualstudio.com/) and [GitHub](https://github.com/).
Foam is a personal knowledge management system built on [Visual Studio Code](https://code.visualstudio.com/) and [GitHub](https://github.com/). It helps you organize research, create discoverable notes, and publish your knowledge.
You can use **Foam** for organising your research, keeping re-discoverable notes, writing long-form content and, optionally, publishing it to the web.
## Key Features
**Foam** is free, open source, and extremely extensible to suit your personal workflow. You own the information you create with Foam, and you're free to share it, and collaborate on it with anyone you want.
- **Wikilinks** - Connect thoughts with `[[double bracket]]` syntax
- **Embeds** - Include content from other notes with `![[note]]` syntax
- **Backlinks** - Automatically discover connections between notes
- **Graph visualization** - See your knowledge network visually
- **Daily notes** - Capture timestamped thoughts
- **Templates** - Standardize note creation
- **Tags** - Organize and filter content
## Why Choose Foam?
- **Free and open source** - No subscriptions or vendor lock-in
- **Own your data** - Notes stored as standard Markdown files
- **VS Code integration** - Leverage powerful editing and extensions
- **Git-based** - Version control and collaboration built-in
Foam is like a bathtub: _What you get out of it depends on what you put into it._
<p class="announcement">
<b>New!</b> Join <a href="https://foambubble.github.io/join-discord/w" target="_blank">Foam community Discord</a> for users and contributors!
@@ -17,88 +32,79 @@ You can use **Foam** for organising your research, keeping re-discoverable notes
## Table of Contents
- [Foam](#foam)
- [What is Foam?](#what-is-foam)
- [Key Features](#key-features)
- [Why Choose Foam?](#why-choose-foam)
- [Table of Contents](#table-of-contents)
- [How do I use Foam?](#how-do-i-use-foam)
- [What's in a Foam?](#whats-in-a-foam)
- [Getting started](#getting-started)
- [Features](#features)
- [Call To Adventure](#call-to-adventure)
- [Contributing](#contributing)
- [Thanks and attribution](#thanks-and-attribution)
- [License](#license)
## How do I use Foam?
**Foam** is a tool that supports creating relationships between thoughts and information to help you think better.
Foam helps you create relationships between thoughts and information through:
Whether you want to build a [Second Brain](https://www.buildingasecondbrain.com/) or a [Zettelkasten](https://zettelkasten.de/posts/overview/), write a book, or just get better at long-term learning, **Foam** can help you organise your thoughts if you follow these simple rules:
1. **Atomic notes** - Write focused markdown documents on single topics
2. **Wikilinks** - Connect ideas with `[[double bracket]]` syntax
3. **Backlinks** - Discover unexpected connections between notes
4. **Graph visualization** - See your knowledge network visually
1. Create a single **Foam** workspace for all your knowledge and research following the [Getting started](#getting-started) guide.
2. Write your thoughts in markdown documents (I like to call them **Bubbles**, but that might be more than a little twee). These documents should be atomic: Put things that belong together into a single document, and limit its content to that single topic. ([source](https://zettelkasten.de/posts/overview/#principles))
3. Use Foam's shortcuts and autocompletions to link your thoughts together with `[[wikilinks]]`, and navigate between them to explore your knowledge graph.
4. Get an overview of your **Foam** workspace using a [[graph-visualization]] (⚠️ WIP), and discover relationships between your thoughts with the use of [[backlinking]].
Foam is a like a bathtub: _What you get out of it depends on what you put into it._
Success with Foam depends on consistent note-taking and linking habits.
## What's in a Foam?
Like the soapy suds it's named after, **Foam** is mostly air.
Foam combines existing tools:
1. The editing experience of **Foam** is powered by VS Code, enhanced by workspace settings that glue together [[recommended-extensions]] and preferences optimised for writing and navigating information.
2. To back up, collaborate on and share your content between devices, Foam pairs well with [GitHub](http://github.com/).
3. To publish your content, you can set it up to publish to [GitHub Pages](https://pages.github.com/), or to any website hosting platform like [Netlify](http://netlify.com/) or [Vercel](https://vercel.com).
1. **VS Code** - Enhanced with [[recommended-extensions]] optimized for knowledge management
2. **GitHub** - Version control, backup, and collaboration
3. **Static site generators** - Publish to GitHub Pages, Netlify, or Vercel
> **Fun fact**: This documentation was researched, written and published using **Foam**.
> This documentation was created using Foam.
## Getting started
> ⚠️ Foam is still in preview. Expect the experience to be a little rough.
**Requirements:** GitHub account and Visual Studio Code
These instructions assume you have a GitHub account, and you have Visual Studio Code installed.
1. Use the [foam-template project](https://github.com/foambubble/foam-template) to generate a new repository. If you're logged into GitHub, you can just hit this button:
1. **Create repository** - Use the [foam-template](https://github.com/foambubble/foam-template) to generate a new repository
<a class="github-button" href="https://github.com/foambubble/foam-template/generate" data-icon="octicon-repo-template" data-size="large" aria-label="Use this template foambubble/foam-template on GitHub">Use this template</a>
_If you want to keep your thoughts to yourself, remember to set the repository private, or if you don't want to use GitHub to host your workspace at all, choose [**Download as ZIP**](https://github.com/foambubble/foam-template/archive/main.zip) instead of **Use this template**._
2. **Clone and open** - Clone locally and open the folder in VS Code
3. **Install extensions** - Click "Install all" when prompted for recommended extensions
4. **Configure** - Edit `.vscode/settings.json` for your preferences
2. [Clone the repository locally](https://help.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository) and open it in VS Code.
**Next steps:**
_Open the repository as a folder using the `File > Open...` menu item. In VS Code, "open workspace" refers to [multi-root workspaces](https://code.visualstudio.com/docs/editor/multi-root-workspaces)._
3. When prompted to install recommended extensions, click **Install all** (or **Show Recommendations** if you want to review and install them one by one)
After setting up the repository, open `.vscode/settings.json` and edit, add or remove any settings you'd like for your Foam workspace.
- _If using a [multi-root workspace](https://code.visualstudio.com/docs/editor/multi-root-workspaces) as noted above, make sure that your **Foam** directory is first in the list. There are some settings that will need to be migrated from `.vscode/settings.json` to your `.code-workspace` file._
To learn more about how to use **Foam**, read the [[recipes]].
Getting stuck in the setup? Read the [[frequently-asked-questions]].
Check our [issues on GitHub](http://github.com/foambubble/foam/issues) if you get stuck on something, and create a new one if something doesn't seem right!
- Explore the [[recipes]] for usage patterns
- Check [[frequently-asked-questions]] if you need help
- Report issues on [GitHub](http://github.com/foambubble/foam/issues)
## Features
**Foam** doesn't have features in the traditional sense. Out of the box, you have access to all features of VS Code and all the [[recommended-extensions]] you choose to install, but it's up to you to discover what you can do with it!
Foam leverages VS Code and [[recommended-extensions]] to provide:
- **Wikilinks** with autocomplete and navigation
- **Backlinks** panel showing connections
- **Graph visualization** of your knowledge network
- **Daily notes** with templates and snippets
- **Tag system** for organization
- **Publishing** to static sites
![Short video of Foam in use](assets/images/foam-navigation-demo.gif)
Head over to [[recipes]] for some useful patterns and ideas!
Explore [[recipes]] for usage patterns and workflows.
## Call To Adventure
## Contributing
The goal of **Foam** is to be your personal companion on your quest for knowledge.
Foam is an evolving project and we welcome contributions:
It's currently about "10% ready" relative to all the features I've thought of, but I've only thought of ~1% of the features it could have, and I'm excited to learn from others.
I am using it as my personal thinking tool. By making it public, I hope to learn from others not only how to improve Foam, but also to improve how I learn and manage information.
If that sounds like something you're interested in, I'd love to have you along on the journey.
- Read about our [[principles]] to understand Foam's philosophy and direction
- Read the [[contribution-guide]] guide to learn how to participate.
- Feel free to open [GitHub issues](https://github.com/foambubble/foam/issues) to give me feedback and ideas for new features.
- Read our [[principles]] to understand Foam's philosophy
- Follow the [[contribution-guide]] to get involved
- Share feedback via [GitHub issues](https://github.com/foambubble/foam/issues)
## Thanks and attribution
@@ -281,20 +287,18 @@ If that sounds like something you're interested in, I'd love to have you along o
<!-- ALL-CONTRIBUTORS-LIST:END -->
**Foam** was inspired by [Roam Research](https://roamresearch.com/) and the [Zettelkasten methodology](https://zettelkasten.de/posts/overview)
Foam was inspired by [Roam Research](https://roamresearch.com/) and [Zettelkasten methodology](https://zettelkasten.de/posts/overview).
**Foam** wouldn't be possible without [Visual Studio Code](https://code.visualstudio.com/) and [GitHub](https://github.com/), and relies heavily on our fantastic open source [[recommended-extensions]] and all their contributors!
Foam builds on [Visual Studio Code](https://code.visualstudio.com/), [GitHub](https://github.com/), and our [[recommended-extensions]].
## License
Foam is licensed under the [MIT license](LICENSE.txt).
[//begin]: # "Autogenerated link references for markdown compatibility"
[graph-visualization]: user/features/graph-visualization.md "Graph Visualization"
[backlinking]: user/features/backlinking.md "Backlinking"
[recommended-extensions]: user/getting-started/recommended-extensions.md "Recommended Extensions"
[recipes]: user/recipes/recipes.md "Recipes"
[frequently-asked-questions]: user/frequently-asked-questions.md "Frequently Asked Questions"
[principles]: principles.md "Principles"
[contribution-guide]: dev/contribution-guide.md "Contribution Guide"
[//end]: # "Autogenerated link references"
[//begin]: # 'Autogenerated link references for markdown compatibility'
[recommended-extensions]: user/getting-started/recommended-extensions.md 'Recommended Extensions'
[recipes]: user/recipes/recipes.md 'Recipes'
[frequently-asked-questions]: user/frequently-asked-questions.md 'Frequently Asked Questions'
[principles]: principles.md 'Principles'
[contribution-guide]: dev/contribution-guide.md 'Contribution Guide'
[//end]: # 'Autogenerated link references'

10
docs/reading-list.md
View File

@@ -1,10 +0,0 @@
# Reading list
- [Zettelkasten article, recommended by tchayen](https://github.com/alefore/weblog/blob/master/zettelkasten.md)
- [Suping up VS Code as a Markdown editor](https://kortina.nyc/essays/suping-up-vs-code-as-a-markdown-notebook/)
- [VSCode Extensions Packs](https://code.visualstudio.com/blogs/2017/03/07/extension-pack-roundup) [[todo]] Evaluate for deployment
- [Dark mode](https://css-tricks.com/dark-modes-with-css/)
[//begin]: # "Autogenerated link references for markdown compatibility"
[todo]: dev/todo.md "Todo"
[//end]: # "Autogenerated link references"

19
docs/terminology.md
View File

@@ -1,19 +0,0 @@
# Terminology
It would be good to have some shared terminology to talk about Foam concepts. Some in-group terminology is acceptable, but we shouldn't be obtuse just to be exclusive.
Here's some ideas, these are open for discussion.
## Foam, the software project
The set of tools and ideas collected in this organisation.
## (Your) Foam
The directory/repository where you keep all your notes.
Also happens to sound quite a lot like Home. Funny, that.
## Bubble
Individual Foam note, written in Markdown.

6
docs/user/__foam todo.md Normal file
View File

@@ -0,0 +1,6 @@
- command to bootstrap workspace
- make all extensions ON for attachments by default
- improve settings description
- add deprecation to daily note settings in package.json
- JS filteres and hooks
- plugins (compatibility with Obsidian?)

76
docs/user/features/backlinking.md
View File

@@ -1,16 +1,66 @@
# Backlinking
# Backlinks
When using [[wikilinks]], you can find all notes that link to a specific note in the **Connections Explorer**
Backlinks are one of Foam's most powerful features for knowledge discovery. They automatically show you which notes reference your current note, creating a web of interconnected knowledge that reveals surprising relationships between your ideas.
- Run `Cmd` + `Shift` + `P` (`Ctrl` + `Shift` + `P` for Windows), type "connections" and run the **Explorer: Focus on Connections** view.
- Keep this pane always visible to discover relationships between your thoughts
- You can drag the connections panel to a different section in VS Code if you prefer. See: [[make-backlinks-more-prominent]]
- You can filter the connections to see just backlinks, forward links, or all connections
- Finding backlinks in published Foam workspaces via [[materialized-backlinks]] is on the [[roadmap]] but not yet implemented.
_[📹 Watch: Understanding and using backlinks in Foam]_
[//begin]: # "Autogenerated link references for markdown compatibility"
[wikilinks]: wikilinks.md "Wikilinks"
[make-backlinks-more-prominent]: ../recipes/make-backlinks-more-prominent.md "Make Backlinks More Prominent"
[materialized-backlinks]: ../../dev/proposals/materialized-backlinks.md "Materialized Backlinks (stub)"
[roadmap]: ../../dev/proposals/roadmap.md "Roadmap"
[//end]: # "Autogenerated link references"
## What Are Backlinks?
A backlink is a connection from another note that points to the note you're currently viewing. While you create forward links intentionally with `[[wikilinks]]`, backlinks are discovered automatically by Foam.
### Forward Links vs. Backlinks
**Forward Links** (what you create):
```markdown
# Machine Learning Note
I'm studying [[Neural Networks]] and [[Deep Learning]] concepts.
```
**Backlinks** (what Foam discovers):
If you're viewing the "Neural Networks" note, Foam shows you that "Machine Learning Note" links to it, even though you didn't explicitly create that reverse connection.
This bidirectional linking creates a richer knowledge network than traditional hierarchical folders.
## Accessing Backlinks - Connections Panel
The Connections panel shows both forward links and backlinks:
1. **Open Command Palette** (`Ctrl+Shift+P` / `Cmd+Shift+P`)
2. **Type "connections"** and select "Explorer: Focus on Connections"
3. **Use the filter buttons** to show only backlinks, forward links, or all connections
_[📹 Watch: Finding and opening the backlinks panel]_
## Using Backlinks for Knowledge Discovery
### 1. Finding Unexpected Connections
Backlinks often reveal relationships you didn't consciously create:
**Example:** While reviewing a "Productivity" note, backlinks might show connections from:
- A cooking recipe (time management for meal prep)
- A fitness routine (efficient workout planning)
- A work project (team productivity strategies)
These diverse connections can spark new insights and cross-domain learning.
### 2. Identifying Important Concepts
Notes with many backlinks are often central to your thinking:
- **Hub concepts** that connect many ideas
- **Frequently referenced** resources or definitions
- **Bridge topics** that span multiple domains
### 3. Building Context Around Ideas
Backlinks provide context for how you use concepts across different areas:
- How you apply the same principle in various projects
- Evolution of your thinking about a topic over time
- Different perspectives you've encountered on the same idea
_[📹 Watch: Using backlinks for knowledge discovery and research]_

29
docs/user/features/built-in-note-embedding-types.md
View File

@@ -1,29 +0,0 @@
# Built-In Note Embedding Types
When embedding a note, there are a few ways to modify the scope of the content as well as its display style. The following are Foam keywords that are used to describe note embedding.
Note, this only applies to note embedding, not embedding of attachments or images.
![Note Embed Types GIF](../../assets/images/note-embed-type-demo.gif)
## Scope
- `full` - the entire note in the case of `![[note]]` or the entire section in the case of `![[note#section1]]`
- `content` - everything excluding the title of the section. So the entire note minus the title for `![[note]]`, or the entire section minus the section header for `![[note#section1]]`
## Style
- `card` - outlines the embedded note with a border
- `inline` - adds the note continuously as if the text were part of the calling note
## Default Setting
Foam expresses note display type as `<scope>-<style>`.
By default, Foam configures note embedding to be `full-card`. That is, whenever the standard embedding syntax is used, `![[note]]`, the note will have `full` scope and `card` style display. This setting is stored under `foam.preview.embedNoteStyle` and can be modified.
## Explicit Modifiers
Prepend the wikilink with one of the scope or style keywords, or a combination of the two to explicitly modify a note embedding if you would like to override the default setting.
For example, given your `foam.embedNoteStyle` is set to `content-card`, embedding a note with standard syntax `![[note-a]]` would show a bordered note without its title. Say, for a specific `note-b` you would like to display the title. You can simply use one of the above keywords to override your default setting like so: `full![[note-b]]`. In this case, `full` overrides the default `content` scope and because a style is not specified, it falls back to the default style setting, `card`. If you would like it to be inline, override that as well: `full-inline![[note-b]]`.

65
docs/user/features/daily-notes.md
View File

@@ -1,23 +1,48 @@
# Daily Notes
Daily notes allow you to quickly create and access a new notes file for each day. This is a surprisingly effective and increasingly common strategy to organize notes and manage events.
Daily notes allow you to quickly create and access a note file for each day.
View today's note file by running the `Foam: Open Daily Note` command, by using the shortcut `alt+d` (note: shortcuts can be [overridden](https://code.visualstudio.com/docs/getstarted/keybindings)), or by using [#snippets](#Snippets). The name, location, and title of daily notes files are [#configurable](#Configuration).
## Creating Daily Notes
## Roam-style Automatic Daily Notes
- **Command:** `Ctrl+Shift+P` → "Foam: Open Daily Note"
- **Shortcut:** `Alt+D`
- **Snippets:** Type `/today`, `/yesterday`, `/tomorrow` in any note
You can automatically open today's note on startup by setting the `Foam › Open Daily Note: On Startup` setting to `true`.
## Automatic Daily Notes
Open daily note automatically on VS Code startup:
```json
{
"foam.openDailyNote.onStartup": true
}
```
## Daily Note Templates
Daily notes can also make use of [[Note Templates]], by defining a special `.foam/templates/daily-note.md` template.
Create `.foam/templates/daily-note.md` to customize the structure:
## Snippets
```markdown
---
type: daily-note
---
Create a link to a recent daily note using [snippets](https://code.visualstudio.com/docs/editor/userdefinedsnippets). Type `/today` and press `enter` to link to today's note. You can also write:
# Daily Note - $FOAM_DATE_YEAR-$FOAM_DATE_MONTH-$FOAM_DATE_DATE
## Tasks
- [ ]
## Notes
```
## Date Snippets
Create links to recent daily notes using snippets:
| Snippet | Date |
| ------------ | ------------- |
| `/today` | today |
| `/tomorrow` | tomorrow |
| `/yesterday` | yesterday |
| `/monday` | next Monday |
@@ -29,31 +54,13 @@ Create a link to a recent daily note using [snippets](https://code.visualstudio.
## Configuration
By default, Daily Notes will be created in a file called `yyyy-mm-dd.md` in the workspace's `journals` folder, with the heading `yyyy-mm-dd`.
By default, daily notes are created as `yyyy-mm-dd.md` in the workspace's `journals` folder.
These settings can be overridden in your workspace or global `.vscode/settings.json` file, using the [**dateformat** date masking syntax](https://github.com/felixge/node-dateformat#mask-options):
To customize your daily note location and format you can create a `.foam/templates/daily-note.md` template. See [[templates]] for more information.
It's possible to customize the path and heading of your daily notes, by following the [dateformat masking syntax](https://github.com/felixge/node-dateformat#mask-options).
The following properties can be used:
There are also some settings to customize the behavior of daily notes, but they are deprecated and will be removed. Please use the `daily-note.md` template.
```json
"foam.openDailyNote.directory": "journal",
"foam.openDailyNote.filenameFormat": "'daily-note'-yyyy-mm-dd",
"foam.openDailyNote.fileExtension": "mdx",
"foam.openDailyNote.titleFormat": "'Journal Entry, ' dddd, mmmm d",
```
The above configuration would create a file `journal/daily-note-2020-07-25.mdx`, with the heading `Journal Entry, Sunday, July 25`.
> NOTE: It is possible to set the filepath of a daily note according to the date using the special [[note-properties]] configurable for [[Note Templates]]. Specifically, see [[note-templates#Example of date-based|Example of date-based filepath]]. Using the template property will override any setting configured through `.vscode/settings.json`.
## Extend Functionality (Weekly, Monthly, Quarterly Notes)
Please see [[note-macros]]
[//begin]: # "Autogenerated link references for markdown compatibility"
[Note Templates]: note-templates.md "Note Templates"
[note-properties]: note-properties.md "Note Properties"
[note-templates#Example of date-based|Example of date-based filepath]: note-templates.md "Note Templates"
[note-macros]: ../recipes/note-macros.md "Custom Note Macros"
[note-templates]: note-templates.md "Note Templates"
[//end]: # "Autogenerated link references"

77
docs/user/features/embeds.md Normal file
View File

@@ -0,0 +1,77 @@
# Note Embeds
Embeds allow you to include content from other notes directly into your current note. This is powerful for creating dynamic content that updates automatically when the source note changes.
## Basic Syntax
Use the embed syntax with an exclamation mark before the wikilink:
```markdown
![[note-name]]
```
This will embed the entire content of `note-name` into your current note.
## Embedding Sections
You can embed specific sections of a note by referencing the heading:
```markdown
![[note-name#Section Title]]
```
## Embed Types
Foam supports different embedding scopes and styles that can be configured globally or overridden per embed.
### Scope Modifiers
- **`full`** - Include the entire note or section, including the title/heading
- **`content`** - Include everything except the title/heading
Examples:
```markdown
full![[my-note]] # Include title + content
content![[my-note]] # Content only, no title
```
### Style Modifiers
- **`card`** - Display the embedded content in a bordered container
- **`inline`** - Display the content seamlessly as part of the current note
Examples:
```markdown
card![[my-note]] # Bordered container
inline![[my-note]] # Seamless integration
```
### Combined Modifiers
You can combine scope and style modifiers:
```markdown
full-card![[my-note]] # Title + content in bordered container
content-inline![[my-note]] # Content only, seamlessly integrated
full-inline![[my-note]] # Title + content, seamlessly integrated
content-card![[my-note]] # Content only in bordered container
```
## Configuration
Set your default embed behavior in VS Code settings:
```json
{
"foam.preview.embedNoteType": "full-card"
}
```
Available options:
- `full-card` (default)
- `full-inline`
- `content-card`
- `content-inline`

26
docs/user/features/graph-visualization.md → docs/user/features/graph-view.md
View File

@@ -1,10 +1,23 @@
# Graph Visualization
Foam comes with a graph visualization of your notes.
The graph view is one of Foam's most powerful features. It transforms your collection of notes into a visual network, revealing connections between ideas that might not be obvious when reading individual notes. This guide will teach you how to use the graph view to explore, understand, and expand your knowledge base.
To see the graph execute the `Foam: Show Graph` command.
Your files, such as notes and documents, are shown as the nodes of the graph along with the tags defined in your notes. The edges of the graph represent either a link between two files or a file that contains a certain tag. A node in the graph will grow in size with the number of connections it has, representing stronger or more defined concepts and topics.
### The `Show Graph` command
1. **Press `Ctrl+Shift+P` / `Cmd+Shift+P`**
2. **Type "Foam: Show Graph"**
3. **Press Enter**
You can set up a custom keyboard shortcut:
1. **Go to File > Preferences > Keyboard Shortcuts**
2. **Search for "Foam: Show Graph"**
3. **Assign your preferred shortcut**
## Graph Navigation
With the Foam graph visualization you can:
@@ -101,8 +114,19 @@ Will result in the following graph:
![Style node by type](../../assets/images/style-node-by-type.png)
## What's Next?
With graph view mastery, you're ready to explore advanced Foam features:
1. **[[wikilinks]]** - Understand bidirectional connections
2. **[[templates]]** - Use templates effectively to standardize your note creation
3. **[[tags]]** - Organize your notes with tags
4. **[[daily-notes]]** - Set up daily notes to establish capture routines
[//begin]: # "Autogenerated link references for markdown compatibility"
[note-properties]: note-properties.md "Note Properties"
[wikilinks]: wikilinks.md "Wikilinks"
[tags]: tags.md "Tags"
[templates]: templates.md "Note Templates"
[daily-notes]: daily-notes.md "Daily Notes"
[//end]: # "Autogenerated link references"

23
docs/user/features/including-notes.md
View File

@@ -1,23 +0,0 @@
# Including notes in a note
In some situations it might be useful to include the content of another note in your current note. Foam supports this displaying within the vscode environment. Note, this does not work out-of-the-box for your publishing solutions.
## Including a note
Including a note can be done by adding an `!` before a wikilink definition. For example `![[wikilink]]`.
## Custom styling
To modify how an embedded note looks and the scope of its content, see [[built-in-note-embedding-types]]
For more fine-grained custom styling, see [[custom-markdown-preview-styles]]
## Future possibilities
Work on this feature is evolving and progressing. See the [[inclusion-of-notes]] proposal for the current discussion.
[//begin]: # 'Autogenerated link references for markdown compatibility'
[built-in-note-embedding-types]: built-in-note-embedding-types.md 'Built-In Note Embedding Types'
[custom-markdown-preview-styles]: custom-markdown-preview-styles.md 'Custom Markdown Preview Styles'
[inclusion-of-notes]: ../../dev/proposals/inclusion-of-notes.md 'Inclusion of notes Proposal '
[//end]: # 'Autogenerated link references'

119
docs/user/features/link-reference-definitions.md
View File

@@ -1,88 +1,65 @@
# Link Reference Definitions
When you use `[[wikilinks]]`, the [foam-vscode](https://github.com/foambubble/foam/tree/main/packages/foam-vscode) extension can automatically generate [Markdown Link Reference Definitions](https://spec.commonmark.org/0.29/#link-reference-definitions) at the bottom of the file. This is not needed to navigate your workspace with foam-vscode, but is useful for files to remain compatible with various Markdown tools (e.g. parsers, static site generators, VS code plugins etc), which don't support `[[wikilinks]]`.
Link reference definitions make your notes compatible with standard Markdown processors by converting wikilinks to standard Markdown references.
## Example
Foam doesn't need references in order to work, but this feature is aimed at supporting other tools you might want to integrate with.
The following example:
## What Are Link Reference Definitions?
```md
- [[wikilinks]]
- [[github-pages]]
Foam can automatically add reference definitions to the bottom of your notes:
**Your note:**
```markdown
# Machine Learning
Related to [[Data Science]] and [[Statistics]].
```
...generates the following link reference definitions to the bottom of the file:
**With reference definitions:**
```md
[wikilinks]: wikilinks 'Wikilinks'
[github-pages]: github-pages 'GitHub Pages'
```markdown
# Machine Learning
Related to [[Data Science]] and [[Statistics]].
[//begin]: # 'Autogenerated link references for markdown compatibility'
[Data Science]: data-science.md 'Data Science'
[Statistics]: statistics.md 'Statistics'
[//end]: # 'Autogenerated link references'
```
You can open the [raw markdown](https://foambubble.github.io/foam/user/features/link-reference-definitions.md) to see them at the bottom of this file
## Enabling Reference Definitions
## Specification
The three components of a link reference definition are `[link-label]: link-target "Link Title"`
- **link label:** The link text to match in the surrounding markdown document. This matches the inner bracket of the double-bracketed `[[wikilink]]` notation
- **link destination** The target of the matched link
- By default we generate links without extension. This can be overridden, see [Configuration](#configuration) below
- **"Link Title"** Optional title for link (The Foam template has a snippet of JavaScript to replace this on the website at runtime)
## Configuration
You can choose to generate link reference definitions with or without file extensions, depending on the target, or to disable the generation altogether. As a rule of thumb:
- Links with file extensions work better with standard markdown-based tools, such as GitHub web UI.
- Links without file extensions work better with certain web publishing tools that treat links as literal urls and don't transform them automatically, such as the standard GitHub pages installation.
By default, Foam generates links without file extensions for legacy reasons, but this may change in future versions.
You can override this setting in your Foam workspace's `settings.json`:
- `"foam.edit.linkReferenceDefinitions": "withoutExtensions"` (default)
- `"foam.edit.linkReferenceDefinitions": "withExtensions"`
- `"foam.edit.linkReferenceDefinitions": "off"`
### Ignoring files
Sometimes, you may want to ignore certain files or folders, so that Foam doesn't generate link reference definitions to them.
There are three options for excluding files from your Foam project:
1. `files.exclude` (from VSCode) will prevent the folder from showing in the file explorer.
> "Configure glob patterns for excluding files and folders. For example, the file explorer decides which files and folders to show or hide based on this setting. Refer to the Search: Exclude setting to define search-specific excludes."
2. `files.watcherExclude` (from VSCode) prevents VSCode from constantly monitoring files for changes.
> "Configure paths or glob patterns to exclude from file watching. Paths or basic glob patterns that are relative (for example `build/output` or `*.js`) will be resolved to an absolute path using the currently opened workspace. Complex glob patterns must match on absolute paths (i.e. prefix with `**/` or the full path and suffix with `/**` to match files within a path) to match properly (for example `**/build/output/**` or `/Users/name/workspaces/project/build/output/**`). When you experience the file watcher process consuming a lot of CPU, make sure to exclude large folders that are of less interest (such as build output folders)."
3. `foam.files.ignore` (from Foam) ignores files from being added to the Foam graph.
> "Specifies the list of globs that will be ignored by Foam (e.g. they will not be considered when creating the graph). To ignore the all the content of a given folder, use `<folderName>/**/*`" (requires reloading VSCode to take effect).
For instance, if you're using a local instance of [Jekyll](https://jekyllrb.com/), you may find that it writes copies of each `.md` file into a `_site` directory, which may lead to Foam generating references to them instead of the original source notes.
You can ignore the `_site` directory by adding any of the following settings to your `.vscode/settings.json` file:
Configure in your settings:
```json
"files.exclude": {
"**/_site": true
},
"files.watcherExclude": {
"**/_site": true
},
"foam.files.ignore": [
"_site/**/*"
]
{
"foam.edit.linkReferenceDefinitions": "withExtensions"
}
```
After changing the setting in your workspace, you can run the [[workspace-janitor]] command to convert all existing definitions.
**Options:**
- `"off"` - Disabled (default)
- `"withoutExtensions"` - References without extension
- `"withExtensions"` - References with extension
If you are using your notes only within Foam, you can keep definitions `off` (also to reduce clutter), otherwise pick your setting based on what is required by your use case.
## How It Works
1. Scans your note for wikilinks
2. Generates reference definitions when you save
3. Updates definitions when links change
4. Maintains the auto-generated section
## Benefits
- **Standard Markdown compatibility** - Works with any Markdown processor
- **Publishing platforms** - Compatible with GitHub Pages, Jekyll, etc.
- **Future-proofing** - Not locked into Foam-specific format
- **Team collaboration** - Others can read notes without Foam
See [[link-reference-definition-improvements]] for further discussion on current problems and potential solutions.
[//begin]: # "Autogenerated link references for markdown compatibility"
[workspace-janitor]: ../tools/workspace-janitor.md "Janitor"
[link-reference-definition-improvements]: ../../dev/proposals/link-reference-definition-improvements.md "Link Reference Definition Improvements"
[//end]: # "Autogenerated link references"

6
docs/user/features/note-properties.md
View File

@@ -29,8 +29,8 @@ Some properties have special meaning for Foam:
| Name | Description |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title` | will assign the name to the note that you will see in the graph, regardless of the filename or the first heading (also see how to [[write-notes-in-foam]]) |
| `type` | can be used to style notes differently in the graph (also see [[graph-visualization]]). The default type for a document is `note` unless otherwise specified with this property. |
| `title` | will assign the name to the note that you will see in the graph, regardless of the filename or the first heading (also see how to [[note-taking-in-foam]]) |
| `type` | can be used to style notes differently in the graph (also see [[graph-view]]). The default type for a document is `note` unless otherwise specified with this property. |
| `tags` | can be used to add tags to a note (see [[tags]]) |
| `alias` | can be used to add aliases to the note. an alias will show up in the link autocompletion |
@@ -47,7 +47,7 @@ alias: alias1, alias2
## Foam Template Properties
There also exists properties that are even more specific to Foam templates, see [[note-templates#Metadata]] for more info.
There also exists properties that are even more specific to Foam templates, see [[templates#Metadata]] for more info.
[//begin]: # "Autogenerated link references for markdown compatibility"
[write-notes-in-foam]: ../getting-started/write-notes-in-foam.md "Writing Notes"

113
docs/user/features/tags.md
View File

@@ -1,62 +1,81 @@
---
tags: my-tag1 my-tag2 my-tag3/notes
---
# Tags
You can add tags to your notes to categorize or link notes together.
Tags provide flexible categorization and organization for your notes beyond wikilinks and folders.
## Creating a tag
## Creating Tags
There are two ways of creating a tag:
### Inline Tags
- Adding a `#tag` anywhere in the text of the note, for example: #my-tag1
- Using the `tags: tag1, tag2` yaml frontmatter [[note-properties|note property]]. Notice `my-tag1` and `my-tag2` tags which are added to this document this way.
Add tags directly in note content:
Tags can also be hierarchical, so you can have `#parent/child` such as #my-tag3/info.
```markdown
# Machine Learning Fundamentals
### Tag completion
This covers basic algorithms and applications.
Typing the `#` character will launch VS Code's "Intellisense." This provider will show a list of possible tags that match the character. If you are editing in the frontmatter [[note-properties|note property]], you can invoke tag completion on the `tags:` line by either typing the `#` character, or using the ["trigger suggest"](https://code.visualstudio.com/docs/editor/intellisense) keybinding (usually `ctrl+space`). If the `#` is used in the frontmatter, it will be removed when the tag is inserted.
## Using *Tag Explorer*
It's possible to navigate tags via the Tag Explorer panel. Expand the Tag Explorer view in the left side bar which will list all the tags found in current Foam environment. Then, each level of tags can be expanded until the options to search by tag and a list of all files containing a particular tag are shown.
Tags can also be visualized in the Foam Graph Explorer. See [[graph-visualization]] for more info including how to change the color of nodes representing tags.
## Styling tags
It is possible to customize the way that tags look in the Markdown Preview panel that renders your Foam notes. This requires some knowledge of the CSS language, which is used to customize the styles of web technologies such as VSCode. A cursory introduction to CSS can be [found here](https://www.freecodecamp.org/news/get-started-with-css-in-5-minutes-e0804813fc3e/).
1. Create a CSS file within your Foam project, for example in `.foam/css/custom-tag-style.css` or [.vscode/custom-tag-style.css](../../.vscode/custom-tag-style.css)
2. Add CSS code that targets the `.foam-tag` class
3. Add a rule for each [CSS property](https://www.w3schools.com/cssref/index.php) you would like applied to your tags.
4. Open the `.vscode/settings.json` file (or the Settings browser with `ctrl+,`)
5. Add the path to your new stylesheet to the `markdown.styles` setting.
> Note: the file path for the stylesheet will be relative to the currently open folder in the workspace when changing this setting for the current workspace. If changing this setting for the user, then the file path will be relative to your global [VSCode settings](https://code.visualstudio.com/docs/getstarted/settings).
The end result will be a CSS file that looks similar to the content below. Now you can make your tags standout in your note previews.
```css
.foam-tag{
color:#ffffff;
background-color: #000000;
}
#machine-learning #data-science #algorithms #beginner
```
![custom tag style demo](../../assets/images/custom-tag-style.png)
### Front Matter Tags
## Using backlinks in place of tags
Add tags in YAML front matter:
Given the power of backlinks, some people prefer to use them as tags.
For example you can tag your notes about books with [[book]].
```markdown
---
tags: [machine-learning, data-science, algorithms, beginner]
---
```
[note-properties|note property]: note-properties.md "Note Properties"
[graph-visualization]: graph-visualization.md "Graph Visualization"
### Hierarchical Tags
Create tag hierarchies using forward slashes:
```markdown
#programming/languages/python
#programming/frameworks/react
#work/projects/website-redesign
#personal/health/exercise
```
## Autocompletion
Typing `#` shows existing tags. In front matter, use `Ctrl+Space` for tag suggestions.
## Tag Explorer
Use the Tag Explorer panel in VS Code's sidebar to:
- Browse hierarchical tag structure
- Filter by tag names
- Click tags to see all associated notes
- View tag usage counts
Tags also appear in the [[graph-view]] with customizable colors.
## Custom Tag Styling
Customize tag appearance in markdown preview by adding CSS:
1. Create `.foam/css/custom-tag-style.css`
2. Add CSS targeting `.foam-tag` class:
```css
.foam-tag {
color: #ffffff;
background-color: #000000;
}
```
3. Update `.vscode/settings.json`:
```json
{
"markdown.styles": [".foam/css/custom-tag-style.css"]
}
```
## Tags vs Backlinks
Some users prefer [[book]] backlinks instead of #book tags for categorization. Both approaches work - choose what fits your workflow.
[//begin]: # "Autogenerated link references for markdown compatibility"
[note-properties|note property]: note-properties.md "Note Properties"
[graph-visualization]: graph-visualization.md "Graph Visualization"
[//end]: # "Autogenerated link references"
[graph-view]: graph-view.md "Graph Visualization"
[//end]: # "Autogenerated link references"

0
docs/user/features/note-templates.md → docs/user/features/templates.md
View File

55
docs/user/features/wikilinks.md
View File

@@ -1,44 +1,45 @@
# Wikilinks
Wikilinks are the internal links that connect the files in your knowledge base. (Also called `[[MediaWiki]]` links).
Wikilinks are internal links that connect files in your knowledge base using `[[double bracket]]` syntax.
## Creating and navigating wikilinks
## Creating Wikilinks
To create a wikilink, type `[[` and then start typing the name of another note in your repo. Once the desired note is selected press the `tab` key to autocomplete it. For example: [[graph-visualization]].
1. **Type `[[`** and start typing a note name
2. **Select from autocomplete** and press `Tab`
3. **Navigate** with `Ctrl+Click` (`Cmd+Click` on Mac) or `F12`
4. **Create new notes** by clicking on non-existent wikilinks
`Cmd` + `Click` ( `Ctrl` + `Click` on Windows ) on wikilink to navigate to that note (`F12` also works while your cursor is on the wikilink). If the file doesn't exist it will be created in your workspace based on your default [[note-templates]] settings.
Example: [[graph-view]]
## Placeholders
You can also create a [[placeholder]]. <!--NOTE: this placeholder link should NOT have an associated file. This is to demonstrate the concept-->
A placeholder is a wikilink that doesn't have a target file and a link to a placeholder is styled differently so you can easily tell them apart.
They can still be helpful to highlight connections.
Wikilinks to non-existent files create [[placeholder]] links, styled differently to show they need files created. They're useful for planning your knowledge structure.
Open the graph with `Foam: Show Graph` command, and look at the placeholder node.
View placeholders in the graph with `Foam: Show Graph` command or in the `Placeholders` panel.
Remember, with `CTRL/CMD+click` on a wikilink you can navigate to the note, or create it (if the link is a placeholder).
## Section Links
## Support for sections
Link to specific sections using `[[note-name#Section Title]]` syntax. Foam provides autocomplete for section titles.
Foam supports autocompletion, navigation, embedding and diagnostics for note sections. Just use the standard wiki syntax of `[[resource#Section Title]]`.
- If it's an external file, `[your link will need the filename](other-file.md#that-section-I-want-to-link-to)`, but
- if it's an anchor within the same document, `[you just need an octothorpe and the section name](#that-section-above)`.
- Doesn't matter what heading-level the anchor is; whether you're linking to an `H1` like `# MEN WALK ON MOON` or an `H2` like `## Astronauts Land on Plain`, the link syntax uses a single octothorpe: `[Walk!](#men-walk-on-moon)` and `[Land!](#astronauts-land-on-plain-collect-rocks-plant-flag)`. Autocomplete is your friend here.
Examples:
## Markdown compatibility
- External file: `[link text](other-file.md#section-name)`
- Same document: `[link text](#section-name)`
The [Foam for VSCode](https://marketplace.visualstudio.com/items?itemName=foam.foam-vscode) extension automatically generates [[link-reference-definitions]] at the bottom of the file to make wikilinks compatible with other Markdown tools and parsers.
## Markdown Compatibility
## Read more
Foam can automatically generates [[link-reference-definitions]] at the bottom of files to make wikilinks compatible with standard Markdown processors.
- [[foam-file-format]]
- [[note-templates]]
- See [[link-reference-definition-improvements]] for further discussion on current problems and potential solutions.
## Related
[//begin]: # "Autogenerated link references for markdown compatibility"
[graph-visualization]: graph-visualization.md "Graph Visualization"
[note-templates]: note-templates.md "Note Templates"
[link-reference-definitions]: link-reference-definitions.md "Link Reference Definitions"
[foam-file-format]: ../../dev/foam-file-format.md "Foam File Format"
[link-reference-definition-improvements]: ../../dev/proposals/link-reference-definition-improvements.md "Link Reference Definition Improvements"
[//end]: # "Autogenerated link references"
- [[foam-file-format]] - Technical details
- [[templates]] - Creating new notes
- [[link-reference-definition-improvements]] - Current limitations
[//begin]: # 'Autogenerated link references for markdown compatibility'
[graph-visualization]: graph-visualization.md 'Graph Visualization'
[link-reference-definitions]: link-reference-definitions.md 'Link Reference Definitions'
[foam-file-format]: ../../dev/foam-file-format.md 'Foam File Format'
[note-templates]: note-templates.md 'Note Templates'
[link-reference-definition-improvements]: ../../dev/proposals/link-reference-definition-improvements.md 'Link Reference Definition Improvements'
[//end]: # 'Autogenerated link references'

15
docs/user/getting-started/creating-new-notes.md
View File

@@ -1,15 +0,0 @@
# Creating New Notes
- Write out a new `[[wikilink]]` and `Cmd` + `Click` to create a new file and enter it.
- For keyboard navigation, use the 'Follow Definition' key `F12` (or [remap the 'editor.action.revealDefinition' key binding](https://code.visualstudio.com/docs/getstarted/keybindings) to something more ergonomic)
- `Cmd` + `Shift` + `P` (`Ctrl` + `Shift` + `P` for Windows), execute `Foam: Create Note` and enter a **Title Case Name** to create `Title Case Name.md`
- Add a keyboard binding to make creating new notes easier. See [[commands]] for more info on this.
- The [[note-templates]] used by this command can be customized.
- You shouldn't worry too much about categorizing your notes. You can always [[search-for-notes]], and explore them using the [[graph-visualization]].
[//begin]: # "Autogenerated link references for markdown compatibility"
[commands]: ../features/commands.md "Foam Commands"
[note-templates]: ../features/note-templates.md "Note Templates"
[search-for-notes]: ../recipes/search-for-notes.md "Search for Notes"
[graph-visualization]: ../features/graph-visualization.md "Graph Visualization"
[//end]: # "Autogenerated link references"

209
docs/user/getting-started/first-workspace.md Normal file
View File

@@ -0,0 +1,209 @@
# Creating Your First Workspace
A Foam workspace is where all your notes, ideas, and knowledge live. Think of it as your digital garden where thoughts can grow and connect. This guide will help you set up a workspace that's organized, scalable, and tailored to your thinking style.
## Understanding Workspaces
A Foam workspace is simply a folder containing **Markdown files** (`.md`) - your actual notes.
Optionally it can contain:
- **Configuration files** - VS Code settings and Foam preferences
- **Assets** - images, attachments, and other media
- **Templates** - reusable note structures
### Single vs. Multiple Workspaces
**Recommended: Single Workspace**
- Keep all your knowledge in one place
- Better link discovery and graph visualization
- Easier to maintain and backup
- Follows the "unified knowledge base" principle
**Deprecated: Multiple Workspaces** (deprecated - advanced users only)
- Separate professional and personal knowledge
- Isolate sensitive information
- Different workflows for different projects
Multiple workspaces are to be considered deprecated at this point, and might become unsupported in the future.
You can simulate a complex workspace by using file/folder links.
## Method 1: Using the Foam Template (Recommended)
The easiest way to start is with our pre-configured template:
### Step 1: Create from Template
1. **Visit** [github.com/foambubble/foam-template](https://github.com/foambubble/foam-template)
2. **Click "Use this template"** (you'll need a GitHub account)
3. **Name your repository** (e.g., "john-knowledge-base", "my-second-brain")
4. **Choose visibility:**
- **Private** - for personal notes (recommended)
- **Public** - if you want to share your knowledge openly
### Step 2: Clone Locally
```bash
git clone https://github.com/yourusername/your-repo-name.git
cd your-repo-name
```
### Step 3: Open in VS Code
1. **Launch VS Code**
2. **File > Open Folder**
3. **Select your cloned repository folder**
## Method 2: Start from Scratch
For a minimal setup:
1. **Create a new folder** on your computer
2. **Open the folder** in VS Code (`File > Open Folder`)
That's all, you can start working with your markdown files and Foam will take care of the rest.
## Ideas for your knowledge base
### 1. Customize Your Settings
Review and adjust `.vscode/settings.json` based on your preferences:
- **Daily notes location** - where your daily notes are stored
- **Image handling** - how pasted images are organized
- **Link format** - with or without file extensions
### 2. Set Up Your Inbox
Create `inbox.md` as your default capture location:
```markdown
# Inbox
Quick notes and ideas go here before being organized.
## Today's Captures
-
## To Process
-
## Ideas
-
```
### 3. Create Core Structure Notes
## Workspace Organization Strategies
Establish your main organizational notes.
You can use any methodology, Foam is not opinionated.
The only recommendation is to get started, you can improve later.
The two main methods adopted by users are [PARA](https://fortelabs.com/blog/para/) and [Zettelkasten](https://zettelkasten.de/overview/).
### The PARA Method
Organize around four categories:
- **Projects** - Things with deadlines
- **Areas** - Ongoing responsibilities
- **Resources** - Future reference materials
- **Archive** - Inactive items
### Zettelkasten Approach
Number-based system for atomic ideas:
- **Permanent notes** - `202501251030-idea-title.md`
- **Literature notes** - `book-author-year.md`
- **Index notes** - `index-topic.md`
### 4. Configure Daily Notes
Daily notes are perfect for:
- Daily planning and reflection
- Meeting notes
- Journal entries
- Quick captures
Test your daily notes setup:
1. **Press `Ctrl+Shift+P` / `Cmd+Shift+P`**
2. **Type "Foam: Open Daily Note"**
3. **Verify the note is created in the right location**
Alternatively you can press `Alt+D` to open today's daily note, or `Alt+H` to open another day's daily note.
Use the `.foam/templates/daily-note.md` to customize your daily note.
## Best Practices for New Workspaces
### 1. Start Small
- Begin with just a few notes
- Don't over-organize initially
- Let structure emerge naturally
### 2. Use Templates
- Create templates for common note types
- Maintain consistency across similar notes
- Save time on repetitive formatting
### 3. Link Early and Often
- Use `[[wikilinks]]` liberally
- Don't worry about creating "perfect" links
- Foam handles broken links gracefully
### 4. Regular Reviews
- Weekly workspace cleanup
- Archive completed projects
- Identify missing connections
## Syncing and Backup
Foam works on simple files, you can add whatever backup method you prefer on top of it.
### Git
Your workspace is a Git repository:
```bash
git add .
git commit -m "Add new notes and ideas"
git push origin main
```
You can also use other VS Code extensions to manage the git synching if that's helpful.
### Alternative Sync Methods
- **Cloud storage** - Dropbox, OneDrive, Google Drive
- **Local backup** - Time Machine, File History
- **Manual export** - Regular ZIP backups
## What's Next?
With your workspace set up, you're ready to:
1. **[Learn note-taking fundamentals](note-taking)** - Master Markdown and writing effective notes
2. **[Explore navigation](navigation.md)** - Connect your thoughts with wikilinks
3. **[Discover the graph view](graph-view.md)** - Visualize your knowledge network
4. **[Set up templates](templates)** - Standardize your note creation process
## Getting Help
If you encounter setup issues:
- Check the [Installation Guide](installation.md) for prerequisites
- Visit the [FAQ](../faq.md) for common workspace problems
- Join the [Foam Community Discord](https://foambubble.github.io/join-discord/w)

245
docs/user/getting-started/get-started-with-vscode.md
View File

@@ -1,47 +1,256 @@
# Getting started with VS Code
# Using Foam with VS Code Features
VS Code is a powerful text editor, hidden behind a simple interface.
Foam builds on Visual Studio Code's powerful editing capabilities, integrating seamlessly with VS Code's native features to create a comprehensive knowledge management experience. This guide explores how to leverage VS Code's built-in functionality alongside Foam.
### Keyboard shortcuts
VS Code supports various **keyboard shortcuts**, the most important for us are:
| Shortcut | Action |
| ------------- | ---------------------------- |
| `cmd+N` | create a new file |
| `cmd+S` | save the current file |
| `cmd+O` | open a file |
| `cmd+P` | use quickpick to open a file |
| `cmd+shift+P` | invoke a command (see below) |
| Shortcut | Action |
| ------------- | ----------------------------- |
| `cmd+N` | create a new file |
| `cmd+S` | save the current file |
| `cmd+O` | open a file |
| `cmd+P` | use quickpick to open a file |
| `alt+D` | open the daily note for today |
| `alt+H` | open the daily note for a day |
| `cmd+shift+P` | invoke a command (see below) |
For more information, see the [VS Code keyboard cheat sheets](https://code.visualstudio.com/docs/getstarted/keybindings#_keyboard-shortcuts-reference), where you can also see how to customize your keybindings.
## Commands
### Commands
Commands make VS Code extremely powerful.
To invoke a command, press `cmd+shift+P` and select the command you want to execute.
For example, to see the Foam graph:
- press `cmd+shift+P`
- press `cmd+shift+P` to open the command bar
- start typing `show graph`
- select the `Foam: Show Graph` command
And watch the magic unfold.
To see all foam commands, type "foam" in the command bar.
For more information on commands, see [commands on the VS Code site](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette).
If you want to learn more about VS Code, check out their [website](https://code.visualstudio.com/docs#first-steps).
## Panels
### Panels
You can see a few panels on the left, including:
Foam integrates with VS Code panels to provide insights into individual notes and the whole knowledge base.
- `Outline`: this panel shows you the structure of the file based on the headings
- `Tag Explorer`: This shows you the tags in your workspace, see [[tags]] for more information on tags
- **`Foam: links`**: Shows all notes that link to and from the currently active note, helping you understand connections and navigate your knowledge graph
- **`Foam: Orphaned Notes`**: Displays notes that have no incoming or outgoing links, helping you identify isolated content that might need better integration
- **`Tag Explorer`**: Shows all tags used across your workspace in a hierarchical view, see [[tags]] for more information on tags
- **`Foam: Graph`**: Visual representation of your note connections (also available as a separate graph view)
### Styling and Themes
VS Code is very configurable when it comes to themes and style. Find your ideal set up by running the command `Color Theme`.
For more information see the [VS Code documentation](https://code.visualstudio.com/docs/configure/themes).
### Multi-Cursor Editing
Edit multiple locations simultaneously for efficient note management:
**Basic Multi-Cursor:**
- `Alt+Click` / `Option+Click` - Add cursor at click location
- `Ctrl+Alt+Down` / `Cmd+Option+Down` - Add cursor below
- `Ctrl+Alt+Up` / `Cmd+Option+Up` - Add cursor above
- `Ctrl+D` / `Cmd+D` - Select next occurrence of word
- `Ctrl+Shift+L` / `Cmd+Shift+L` - Select all occurrences
**Bulk wikilink creation:**
1. **Select a word** (e.g., "Python")
2. **Press `Ctrl+Shift+L`** to select all occurrences
3. **Type `[[]]`** to wrap all instances
4. **Arrow key** to position cursor inside brackets
### Find and Replace
Powerful search and replace for note maintenance:
**Basic Find/Replace:**
- `Ctrl+F` / `Cmd+F` - Find in current file
- `Ctrl+H` / `Cmd+H` - Replace in current file
- `Ctrl+Shift+F` / `Cmd+Shift+F` - Find across workspace
- `Ctrl+Shift+H` / `Cmd+Shift+H` - Replace across workspace
### Text Folding
Organize long notes with collapsible sections:
**Folding Controls:**
- **Click fold icons** in the gutter next to headings
- `Ctrl+Shift+[` / `Cmd+Option+[` - Fold current section
- `Ctrl+Shift+]` / `Cmd+Option+]` - Unfold current section
- `Ctrl+K Ctrl+0` / `Cmd+K Cmd+0` - Fold all
- `Ctrl+K Ctrl+J` / `Cmd+K Cmd+J` - Unfold all
## File Management
### Explorer Integration
Leverage VS Code's file explorer for note organization:
**File Operations:**
- **Drag and drop** files to reorganize
- **Right-click context menus** for quick actions
- **New file/folder** creation with shortcuts
- **Bulk selection** with Ctrl+Click / Cmd+Click
**Quick File Actions:**
- `F2` - Rename file (Foam updates links automatically)
- `Delete` - Move to trash
- `Ctrl+C` / `Cmd+C` then `Ctrl+V` / `Cmd+V` - Copy/paste files
- **Right-click → Reveal in Explorer/Finder** - Open in file system
### Quick Open
Rapid file navigation for large knowledge bases:
**Quick Open Commands:**
- `Ctrl+P` / `Cmd+P` - Go to file
- `Ctrl+Shift+O` / `Cmd+Shift+O` - Go to symbol (headings in Markdown)
- `Ctrl+T` / `Cmd+T` - Go to symbol in workspace
- `Ctrl+G` / `Cmd+G` - Go to line number
**Search Patterns:**
```
# Go to File (Ctrl+P)
machine # Finds "machine-learning.md"
proj alpha # Finds "project-alpha.md"
daily/2025 # Finds files in daily/2025 folder
# Go to Symbol (Ctrl+Shift+O)
@introduction # Jump to "Introduction" heading
@#setup # Jump to "Setup" heading
:50 # Go to line 50
```
## Search and Discovery
### Global Search
Find content across your entire knowledge base:
**Search Interface (`Ctrl+Shift+F` / `Cmd+Shift+F`):**
- **Search box** - Enter your query
- **Replace box** - Toggle with replace arrow
- **Include/Exclude patterns** - Filter by file types or folders
- **Match case** - Case-sensitive search
- **Match whole word** - Exact word matching
- **Use regular expression** - Advanced pattern matching
### Timeline View
Track changes to your notes over time:
**Accessing Timeline:**
1. **Open Explorer panel**
2. **Expand "Timeline" section** at bottom
3. **Select a file** to see its change history
4. **Click timeline entries** to see diff views
**Timeline Features:**
- **Git commits** show when notes were changed
- **File saves** track editing sessions
- **Diff views** highlight what changed
- **Restore points** for recovering previous versions
### Outline View
Navigate long notes with hierarchical structure:
**Outline Panel:**
1. **Enable in Explorer** (expand "Outline" section)
2. **Shows heading hierarchy** for current note
3. **Click headings** to jump to sections
4. **Collapse/expand** sections in outline
## Version Control Integration
### Git Integration
Track changes to your knowledge base:
**Source Control Panel:**
- **View changes** - See modified files
- **Stage changes** - Click `+` to stage files
- **Commit changes** - Enter message and commit
- **Sync changes** - Push/pull from remote
**Git Workflow for Notes:**
1. **Write and edit** your notes
2. **Review changes** in Source Control panel
3. **Stage relevant files** for commit
4. **Write meaningful commit message**
5. **Commit and push** to backup/share
**Useful Git Features:**
- **Diff view** - See exactly what changed
- **File history** - Track note evolution over time
- **Branch management** - Experiment with different organization approaches
- **Merge conflicts** - Resolve when collaborating
## Markdown Features
### Preview Integration
View formatted notes alongside editing:
**Preview Commands:**
- `Ctrl+Shift+V` / `Cmd+Shift+V` - Open preview
- `Ctrl+K V` / `Cmd+K V` - Open preview to side
- **Preview lock** - Pin preview to specific file
**Diagrams (with Mermaid extension):**
````markdown
```mermaid
graph TD
A[Foam Workspace] --> B[Notes]
A --> C[Templates]
A --> D[Assets]
B --> E[Wikilinks]
B --> F[Tags]
E --> G[Graph View]
```
````
## Extension Ecosystem
Extend Foam's capabilities with complementary extensions.
Look for them in the [VS Code Marketplace](https://marketplace.visualstudio.com/).
## What's Next?
With VS Code mastery, explore advanced Foam topics:
1. **[[recommended-extensions]]** - See complementary extensions to improve your note taking experience
2. **[[publishing]]** - Share your knowledge base
## Settings
To view or change the settings in VS Code, press `cmd+,` on Mac and `ctrl+,` on Windows/Linux.
[//begin]: # "Autogenerated link references for markdown compatibility"
[tags]: ../features/tags.md "Tags"
[//end]: # "Autogenerated link references"
[recommended-extensions]: recommended-extensions.md "Recommended Extensions"
[publishing]: ../publishing/publishing.md "Publishing pages"
[//end]: # "Autogenerated link references"

79
docs/user/getting-started/installation.md Normal file
View File

@@ -0,0 +1,79 @@
# Installation
Getting started with Foam is straightforward. This guide will walk you through installing everything you need to begin your knowledge management journey.
## Step 1: Install Visual Studio Code
Foam is built on VS Code, Microsoft's free, open-source code editor. You can download it at https://code.visualstudio.com/
### Why VS Code?
VS Code provides:
- Excellent Markdown editing capabilities
- Rich extension ecosystem
- Cross-platform compatibility
- Integrated terminal and Git support
- Customizable interface and shortcuts
To learn more about using VS Code with Foam, check [[get-started-with-vscode]]
## Step 2: Install the Foam Extension
The Foam extension adds knowledge management superpowers to VS Code.
1. **Open VS Code**
2. **Click the Extensions icon** in the sidebar (or press `Ctrl+Shift+X` / `Cmd+Shift+X`)
3. **Search for "Foam"** in the extensions marketplace
4. **Click "Install"** on the official Foam extension by Foam Team
5. **Reload VS Code** when prompted
### What the Foam Extension Provides
- Wikilink auto-completion and navigation
- Backlink discovery and panel
- Graph visualization
- Powerful note template engine
- Daily notes functionality
## Step 3: Install Recommended Extensions
While Foam works on its own, it is focused on the networking aspect of your notes. You might want to install additional extensions to improve the editing experience or the functionility of your notes.
### Useful Extensions
- **Markdown All in One** - Rich Markdown editing features. Highly recommended.
Other extensions:
- **Spell Right** - Spell checking for your notes
- **Paste Image** - Easily insert images from clipboard
- **Todo Tree** - Track TODO items across your workspace
## What's Next?
Now that Foam is installed, you're ready to:
1. **[[first-workspace]]** - Set up your knowledge base structure
2. **[[get-started-with-vscode]]** - Learn how to use VS Code for note taking
3. **[[note-taking-in-foam]]** - Write your first Markdown notes
4. **[[navigation]]** - Connect your thoughts with wikilinks
5. **[[graph-view]]** - Visualize your knowledge network
## Getting Help
If you encounter issues:
- Check the [[frequently-asked-questions]] for common problems
- Visit the [Foam Community Discord](https://foambubble.github.io/join-discord/w)
- Browse [GitHub Issues](https://github.com/foambubble/foam/issues) for known problems
- Ask questions in [GitHub Discussions](https://github.com/foambubble/foam/discussions)
[//begin]: # "Autogenerated link references for markdown compatibility"
[get-started-with-vscode]: get-started-with-vscode.md "Using Foam with VS Code Features"
[first-workspace]: first-workspace.md "Creating Your First Workspace"
[note-taking-in-foam]: note-taking-in-foam.md "Note-Taking in Foam"
[navigation]: navigation.md "Navigation in Foam"
[graph-view]: ../features/graph-view.md "Graph Visualization"
[frequently-asked-questions]: ../frequently-asked-questions.md "Frequently Asked Questions"
[//end]: # "Autogenerated link references"

162
docs/user/getting-started/navigation.md Normal file
View File

@@ -0,0 +1,162 @@
# Navigation in Foam
Navigation is where Foam truly shines. Unlike traditional file systems or notebooks, Foam lets you move through your knowledge by following connections between ideas. This guide will teach you how to navigate efficiently using wikilinks, backlinks, and other powerful features.
_[📹 Watch: Mastering navigation in Foam]_
## Understanding Wikilinks
Wikilinks are the backbone of Foam navigation. They connect your thoughts and let you jump between related concepts instantly.
### Basic Wikilink Syntax
```markdown
I'm learning about [[Machine Learning]] and its applications in [[Data Science]].
This reminds me of my notes on [[Python Programming]] from yesterday.
```
When you type `[[`, Foam shows you a list of existing notes to link to. If the note doesn't exist, Foam creates a placeholder that you can click to create the note later.
### Wikilink Variations
**Link to a specific heading:**
```markdown
See the [[Project Management#Risk Assessment]] section for details.
```
**Link to a specific block:**
```markdown
See the [[Project Management#^block-id]] paragraph for details.
```
**Link with alias:**
```markdown
According to [[Einstein, Albert|Einstein]], imagination is more important than knowledge.
```
### Autocomplete and Link Assistance
Foam provides intelligent autocomplete when creating links:
1. **Type `[[`** - Foam shows a dropdown of existing notes
2. **Start typing** - The list filters to matching notes
3. **Use arrow keys** to navigate suggestions
4. **Press Enter** to insert the selected link
## The Foam Graph
For a visual overview of your knowledge base, Foam offers a [[graph-view]]. This feature renders your notes as nodes and the links between them as connections, creating an interactive map of your thoughts.
_[📹 Watch: Navigation with the Foam Graph]_
### Using the Graph
1. **Open the Command Palette** (`Ctrl+Shift+P` / `Cmd+Shift+P`)
2. **Run the "Foam: Show Graph" command**
3. The graph will open in a new panel. You can:
- **Click on a node** to navigate to that note.
- **Pan and zoom** to explore different areas of your knowledge base.
- **See how ideas cluster** and identify central concepts.
## Backlinks: The Power of Reverse Navigation
Backlinks show you which notes reference the current note. This creates a web of knowledge where ideas naturally connect.
### Viewing Backlinks
1. **Open any note**
2. **Look for the "Connections" panel** in the sidebar
3. **See all notes that link to your current note**
4. **Click any backlink** to jump to that note
## Quick Navigation Features
### Command Palette Navigation
Press `Ctrl+Shift+P` / `Cmd+Shift+P` and try these commands:
- **"Foam: Open Random Note"** - Discover forgotten knowledge
- **"Foam: Open Daily Note"** - Quick access to today's notes
- **"Go to File"** (`Ctrl+P` / `Cmd+P`) - Fast file opening
- **"Go to Symbol"** (`Ctrl+Shift+O` / `Cmd+Shift+O`) - Jump to headings within a note
### File Explorer Integration
The VS Code file explorer shows your note structure:
- **Click any `.md` file** to open it
- **Use the search box** to filter files
- **Right-click** for context menus (rename, delete, etc.)
Foam also supports the Note Explorer, which is like the file explorer, but centered around the Foam metadata.
### Quick Open
Press `Ctrl+P` / `Cmd+P` and start typing:
- **File names** - `machine` finds "machine-learning.md"
- **Partial paths** - `daily/2025` finds daily notes from 2025
- **Recent files** - Empty search shows recently opened files
## Link Management and Maintenance
### Finding Broken Links - Placeholders
In Foam broken links are considered placeholders for future notes.
Placeholders (references to non-existent notes) appear differently:
- In editor: `[[missing-note]]` will be highlighted a different color
- In preview: Shows as regular text or with special styling
Clicking on a placeholder in the editor will create the corresponding note.
**To find all placeholders:**
You can find placeholders by looking at the `Placeholders` treeview.
### Renaming and Moving Notes
When you rename a note file:
1. **Use VS Code's rename function** (`F2` key)
2. **Foam automatically updates** all links to that note
3. **Check the "Problems" panel** for any issues
Currently you cannot rename whole folders.
## What's Next?
With navigation mastered, you're ready to:
1. **[Explore the graph view](graph-view.md)** - Visualize your knowledge network
2. **[Learn about backlinks](../features/backlinks.md)** - Master bidirectional linking
3. **[Set up templates](../features/templates.md)** - Standardize your note creation
4. **[Use tags effectively](../features/tags.md)** - Add another layer of organization
## Advanced Navigation Topics
For power users, consider exploring:
- Graph-based navigation strategies
- Custom link types and conventions
- Automated link generation
- Integration with external knowledge bases
- Multi-workspace navigation patterns
---
## Suggestions for Further Refinement
- Add section on link analytics (most connected notes, orphaned notes, etc.)
- Include navigation keyboard shortcuts specific to Foam
- Create troubleshooting flowchart for navigation issues
- Add section on collaborative navigation in shared workspaces
- Include performance tips for large knowledge bases
- Create navigation workflow templates for different user types
- Add section on mobile navigation apps and compatibility
- Include accessibility considerations for navigation (screen readers, keyboard-only, etc.)

239
docs/user/getting-started/note-taking-in-foam.md Normal file
View File

@@ -0,0 +1,239 @@
# Note-Taking in Foam
Effective note-taking is the foundation of any knowledge management system. In Foam, you'll write notes in Markdown, a simple and powerful format that's both human-readable and widely supported. This guide will teach you everything you need to know about writing great notes in Foam.
## Markdown Basics
Markdown is a lightweight markup language that uses simple syntax to format text. Here are the essentials:
### Headings
```markdown
# Heading 1 (Main Title)
## Heading 2 (Major Section)
### Heading 3 (Subsection)
#### Heading 4 (Minor Section)
```
### Text Formatting
```markdown
**Bold text**
_Italic text_
**_Bold and italic_**
~~Strikethrough~~
`Inline code`
```
### Lists
```markdown
## Unordered Lists
- First item
- Second item
- Nested item
- Another nested item
## Ordered Lists
1. First step
2. Second step
1. Sub-step
2. Another sub-step
```
### Links and Images
```markdown
[External link](https://example.com)
![Image description](./assets/images/screenshot.png)
```
### Code Blocks
````markdown
```javascript
function greet(name) {
return `Hello, ${name}!`;
}
```
````
### Tables
```markdown
| Column 1 | Column 2 | Column 3 |
| -------- | -------- | -------- |
| Data 1 | Data 2 | Data 3 |
| Data 4 | Data 5 | Data 6 |
```
### Quotes and Dividers
```markdown
> This is a quote or important note
> It can span multiple lines
---
Use three dashes for horizontal dividers
```
_[📹 Watch: Markdown syntax essentials for note-taking]_
## Foam-Specific Features
Beyond standard Markdown, Foam adds several powerful features:
### Wikilinks
Connect your notes with double brackets:
```markdown
I'm reading about [[Project Management]] and its relationship to [[Personal Productivity]].
This connects to [[2025-01-25-daily-note]] where I first had this insight.
```
### Note Embedding
Include content from other notes via [[embeds]]:
```markdown
![[Project Management#Key Principles]]
This embeds the "Key Principles" section from the Project Management note.
```
### Tags
Organize your content with [[docs-v2/user/features/tags]]:
```markdown
#productivity #learning #foam
Tags can be anywhere in your note and help with organization and filtering.
```
Use nested tags for better organization:
```markdown
#work/projects/website
#learning/programming/javascript
#personal/health/exercise
```
Those tags will show as a tree structure in the [Tag Explorer](../features/tags.md)
### Note Properties (YAML Front Matter)
Add metadata to your notes:
```markdown
---
title: 'Advanced Note-Taking Strategies'
tags: [productivity, learning, methods]
created: 2025-01-25
modified: 2025-01-25
status: draft
---
# Advanced Note-Taking Strategies
Your note content goes here...
```
## Writing Effective Notes
### The Atomic Principle
Each note should focus on one concept or idea:
**Good Example:**
```markdown
# The Feynman Technique
A learning method where you explain a concept in simple terms as if teaching it to someone else.
## Steps
1. Choose a topic to learn
2. Explain it in simple terms
3. Identify gaps in understanding
4. Simplify and use analogies
## Why It Works
- Forces active engagement with material
- Reveals knowledge gaps quickly
- Improves retention through teaching
Related: [[Active Learning]] [[Study Methods]]
```
**Avoid:**
Mixing multiple unrelated concepts in one note.
### Use Descriptive Titles
Your note titles should clearly indicate the content:
**Good:** `REST API Design Principles`
**Good:** `Meeting Notes - Product Roadmap Review 2025-01-25`
**Avoid:** `Stuff I Learned Today`
**Avoid:** `Notes`
### Link Generously
Don't hesitate to create links, even to notes that don't exist yet:
```markdown
# Machine Learning Fundamentals
Machine learning is a subset of [[Artificial Intelligence]] that focuses on creating algorithms that can learn from [[Data]].
Key concepts include:
- [[Supervised Learning]]
- [[Unsupervised Learning]]
- [[Neural Networks]]
- [[Feature Engineering]]
This connects to my work on [[Customer Behavior Analysis]] and [[Predictive Analytics]].
```
Foam will create placeholder pages for missing notes, making it easy to fill in knowledge gaps later.
## Keyboard Shortcuts
Essential VS Code shortcuts for note-taking:
| Shortcut | Action |
| ------------------------------ | --------------------- |
| `Ctrl+N` / `Cmd+N` | New file |
| `Ctrl+S` / `Cmd+S` | Save file |
| `Ctrl+P` / `Cmd+P` | Quick file open |
| `Ctrl+Shift+P` / `Cmd+Shift+P` | Command palette |
| `Ctrl+K V` / `Cmd+K V` | Open Markdown preview |
| `Ctrl+[` / `Cmd+[` | Decrease indent |
| `Ctrl+]` / `Cmd+]` | Increase indent |
| `Alt+Z` / `Option+Z` | Toggle word wrap |
## What's Next?
Now that you understand note-taking basics:
1. **[[navigation]]** - Learn to move efficiently between notes with wikilinks
2. **[Explore the graph view](graph-view.md)** - Visualize the connections in your knowledge base
3. **[Set up templates](../features/templates.md)** - Create reusable note structures
4. **[Use daily notes](../features/daily-notes.md)** - Establish a daily capture routine
[//begin]: # "Autogenerated link references for markdown compatibility"
[navigation]: navigation.md "Navigation in Foam"
[//end]: # "Autogenerated link references"

24
docs/user/getting-started/recommended-extensions.md
View File

@@ -4,7 +4,7 @@ These extensions defined in `.vscode/extensions.json` are automatically installe
This list is subject to change.
- [Foam for VSCode](https://marketplace.visualstudio.com/items?itemName=foam.foam-vscode) (alpha)
- [Foam for VSCode](https://marketplace.visualstudio.com/items?itemName=foam.foam-vscode)
- [Markdown All In One](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one)
- [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)
@@ -12,14 +12,14 @@ This list is subject to change.
These extensions are not defined in `.vscode/extensions.json`, but have been used by others and shown to play nice with Foam.
- [Emojisense](https://marketplace.visualstudio.com/items?itemName=bierner.emojisense)
- [Markdown Emoji](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-emoji) (adds `:smile:` syntax, works with emojisense to provide autocomplete for this syntax)
- [Markdown Preview Mermaid Support](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-mermaid)
- [Mermaid Markdown Syntax Highlighting](https://marketplace.visualstudio.com/items?itemName=bpruitt-goddard.mermaid-markdown-syntax-highlighting)
- [Excalidraw whiteboard and sketching tool integration](https://marketplace.visualstudio.com/items?itemName=pomdtr.excalidraw-editor)
- [VSCode PDF Viewing](https://marketplace.visualstudio.com/items?itemName=tomoki1207.pdf)
- [Project Manager](https://marketplace.visualstudio.com/items?itemName=alefragnani.project-manager) (to quickly switch between projects)
- [Markdown Extended](https://marketplace.visualstudio.com/items?itemName=jebbs.markdown-extended) (with `kbd` option disabled, `kbd` turns wikilinks into non-clickable buttons)
- [GitDoc](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.gitdoc) (easy version management via git auto commits)
- [Markdown Footnotes](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-footnotes) (Adds [^footnote] syntax support to VS Code's built-in markdown preview)
- [Todo Tree](https://marketplace.visualstudio.com/items?itemName=Gruntfuggly.todo-tree) (Searches workspace for TODO and related comments and summarizes those lines in vs-code gutter)
- [Emojisense](https://marketplace.visualstudio.com/items?itemName=bierner.emojisense) (provides emoji autocomplete and suggestions in markdown files)
- [Markdown Emoji](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-emoji) (adds `:smile:` syntax support, works with emojisense to provide autocomplete for this syntax)
- [Markdown Preview Mermaid Support](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-mermaid) (renders Mermaid diagrams in markdown preview for flowcharts, sequence diagrams, and more)
- [Mermaid Markdown Syntax Highlighting](https://marketplace.visualstudio.com/items?itemName=bpruitt-goddard.mermaid-markdown-syntax-highlighting) (adds syntax highlighting for Mermaid code blocks in markdown)
- [Excalidraw whiteboard and sketching tool integration](https://marketplace.visualstudio.com/items?itemName=pomdtr.excalidraw-editor) (create and edit hand-drawn style diagrams and sketches directly in VS Code)
- [VSCode PDF Viewing](https://marketplace.visualstudio.com/items?itemName=tomoki1207.pdf) (view PDF files directly within VS Code without external applications)
- [Project Manager](https://marketplace.visualstudio.com/items?itemName=alefragnani.project-manager) (easily switch between multiple projects and workspaces)
- [Markdown Extended](https://marketplace.visualstudio.com/items?itemName=jebbs.markdown-extended) (extended markdown syntax support with additional formatting options - use with `kbd` option disabled as it conflicts with wikilinks)
- [GitDoc](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.gitdoc) (automatic git commits for easy version management and backup of your notes)
- [Markdown Footnotes](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-footnotes) (adds footnote syntax support `[^footnote]` to VS Code's built-in markdown preview)
- [Todo Tree](https://marketplace.visualstudio.com/items?itemName=Gruntfuggly.todo-tree) (scans workspace for TODO, FIXME, and other comment tags, displaying them in a tree view and editor gutter)

0
docs/user/getting-started/sync-notes-with-source-control.md → docs/user/getting-started/sync-notes.md
View File

74
docs/user/getting-started/write-notes-in-foam.md
View File

@@ -1,74 +0,0 @@
# Writing Notes
Notes are simple text files with some extra flavor, in the shape of Markdown syntax and support for extra properties (see [[note-properties]]).
## Foam Syntax
Foam uses standard Markdown, with a few added twists:
- the title of a note (e.g. in the [[graph-visualization]]) is given by precedence based on:
- the `title` property (see [[note-properties]])
- the first `# heading 1` of the file
- the file name
## Markdown Syntax
With Markdown, we can style our notes in a simple way, while keeping the document a simple text file (the best way to future-proof your writings!).
You can see the formatted output by running the `Markdown: Open Preview to the Side` command.
Here is a high level overview of Markdown, for more information on the Markdown syntax [see here](https://commonmark.org/help/).
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6
This is a [link to google](https://www.google.com).
This is a wikilink (aka internal link) to [[note-properties]].
Here is an image:
![image](../../attachments/foam-icon.png)
> this is a blockquote
> it can span multiple lines
- list item
- list item
- list item
1. One
2. Two
3. Three
This text is **in bold** and this is *italic*.
The following is a horizontal rule
---
This is a table:
| Column 1 | Column 2 |
| -------- | -------- |
| R1C1 | R1C2 |
| R2C1 | R2C2 |
You can `inline code` or
```text
you can create
code blocks
```
[//begin]: # "Autogenerated link references for markdown compatibility"
[note-properties]: ../features/note-properties.md "Note Properties"
[graph-visualization]: ../features/graph-visualization.md "Graph Visualization"
[//end]: # "Autogenerated link references"

55
docs/user/index.md
View File

@@ -1,33 +1,50 @@
# Using Foam
Foam is a collection VS Code extensions and recipes that power up the editor
into a full-blown note taking system. This folder contains user documentation
describing how to get started using Foam, what its main features are, and
strategies for getting the most out of Foam. The full docs are included in the
`foam-template` repo that most users start from.
Foam is a personal knowledge management system built on [Visual Studio Code](https://code.visualstudio.com/) and [GitHub](https://github.com/). It helps you organize research, create discoverable notes, and publish your knowledge.
> See also [[frequently-asked-questions]].
## Key Features
- **Wikilinks** - Connect thoughts with `[[double bracket]]` syntax
- **Embeds** - Include content from other notes with `![[note]]` syntax
- **Backlinks** - Automatically discover connections between notes
- **Graph visualization** - See your knowledge network visually
- **Daily notes** - Capture timestamped thoughts
- **Templates** - Standardize note creation
- **Tags** - Organize and filter content
## Why Choose Foam?
- **Free and open source** - No subscriptions or vendor lock-in
- **Own your data** - Notes stored as standard Markdown files
- **VS Code integration** - Leverage powerful editing and extensions
- **Git-based** - Version control and collaboration built-in
Foam is like a bathtub: _What you get out of it depends on what you put into it._
## Getting Started
- [[installation]]
- [[get-started-with-vscode]]
- [[recommended-extensions]]
- [[creating-new-notes]]
- [[write-notes-in-foam]]
- [[sync-notes-with-source-control]]
- [[first-workspace]]
- [[note-taking-in-foam]]
- [[sync-notes]]
- [[keyboard-shortcuts]]
## Features
- [[wikilinks]]
- [[embeds]]
- [[tags]]
- [[backlinking]]
- [[daily-notes]]
- [[including-notes]]
- [[embeds]]
- [[spell-checking]]
- [[graph-visualization]]
- [[graph-view]]
- [[note-properties]]
- [[note-templates]]
- [[templates]]
- [[paste-images-from-clipboard]]
- [[custom-markdown-preview-styles]]
- [[link-reference-definitions]]
@@ -53,21 +70,21 @@ See [[publishing]] for more details.
[//begin]: # "Autogenerated link references for markdown compatibility"
[frequently-asked-questions]: frequently-asked-questions.md "Frequently Asked Questions"
[get-started-with-vscode]: getting-started/get-started-with-vscode.md "Getting started with VS Code"
[installation]: getting-started/installation.md "Installation"
[get-started-with-vscode]: getting-started/get-started-with-vscode.md "Using Foam with VS Code Features"
[recommended-extensions]: getting-started/recommended-extensions.md "Recommended Extensions"
[creating-new-notes]: getting-started/creating-new-notes.md "Creating New Notes"
[write-notes-in-foam]: getting-started/write-notes-in-foam.md "Writing Notes"
[sync-notes-with-source-control]: getting-started/sync-notes-with-source-control.md "Sync notes with source control"
[note-taking-in-foam]: getting-started/note-taking-in-foam.md "Note-Taking in Foam"
[sync-notes]: getting-started/sync-notes.md "Sync notes with source control"
[keyboard-shortcuts]: getting-started/keyboard-shortcuts.md "Keyboard Shortcuts"
[wikilinks]: features/wikilinks.md "Wikilinks"
[tags]: features/tags.md "Tags"
[backlinking]: features/backlinking.md "Backlinking"
[backlinking]: features/backlinking.md "Backlinks"
[daily-notes]: features/daily-notes.md "Daily Notes"
[including-notes]: features/including-notes.md "Including notes in a note"
[embeds]: features/embeds.md "Note Embeds"
[spell-checking]: features/spell-checking.md "Spell Checking"
[graph-visualization]: features/graph-visualization.md "Graph Visualization"
[graph-view]: features/graph-view.md "Graph Visualization"
[note-properties]: features/note-properties.md "Note Properties"
[note-templates]: features/note-templates.md "Note Templates"
[templates]: features/templates.md "Note Templates"
[paste-images-from-clipboard]: features/paste-images-from-clipboard.md "Paste Images from Clipboard"
[custom-markdown-preview-styles]: features/custom-markdown-preview-styles.md "Custom Markdown Preview Styles"
[link-reference-definitions]: features/link-reference-definitions.md "Link Reference Definitions"

21
docs/user/recipes/make-backlinks-more-prominent.md
View File

@@ -1,21 +0,0 @@
# Make Backlinks More Prominent
One of the most most common early feature requests in Foam is to make the Markdown Notes Backlinks Explorer more prominent.
This #recipe shows you how to do that.
At the moment, you can drag the explorer pane to your bottom pane, and either show it side by side with another pane, or have take the full width of the editor:
![Demo of dragging and dropping the pane](../../assets/images/demo-backlinks-explorer.gif)
In the future we'll want to improve this feature by
- [[materialized-backlinks]]
- Providing more context around back link reference
- Could be done by tweaking Markdown Notes slightly. Maybe a user setting?
- Make back links editable using [VS Code Search Editors](https://code.visualstudio.com/updates/v1_43#_search-editors)
- [Suggested by @Jash on Discord](https://discordapp.com/channels/729975036148056075/729978910363746315/730999992419876956)
[//begin]: # "Autogenerated link references for markdown compatibility"
[materialized-backlinks]: ../../dev/proposals/materialized-backlinks.md "Materialized Backlinks (stub)"
[//end]: # "Autogenerated link references"

58
docs/user/recipes/note-macros.md
View File

@@ -1,58 +0,0 @@
# Custom Note Macros
This #recipe allows you to create custom note macros.
## Installation
**This extension is not included in the template**
To install search note-macros in vscode or head to [note-macros - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=NeelyInnovations.note-macros)
## Instructions
### Run macro From command palette
Simply use `Ctrl+P` or `Alt+P` depend on your os, and type `Note Macros: Run A Macro` then chose the macro you want to execute.
### Create Custom Note Macros
Create your own custom macros by adding them to your `settings.json` (Code|File > Preferences > User Settings). A full example can be found at [settings.json](https://github.com/kneely/note-macros/blob/master/settings.json)
For example:
This macro creates a Weekly note in the Weekly note Directory.
```json
{
"note-macros": {
"Weekly": [
{
"type": "note",
"directory": "Weekly",
"extension": ".md",
"name": "weekly-note",
"date": "yyyy-W"
}
]
}
}
```
For an explanation of the fields please go to [note-macros - Explanation of Fields](https://github.com/kneely/note-macros#explanation-of-fields)
### Add Keybindings to Run your Macros
in `keybindings.json` (Code|File > Preferences > Keyboard Shortcuts) add bindings to your macros:
```json
{
"key": "ctrl+cmd+/",
"command": "note-macros.Weekly"
}
```
## Issues and Feedback
If you have any issues or questions please look at the [README.md](https://github.com/kneely/note-macros#note-macros) on the [note-macros](https://github.com/kneely/note-macros) GitHub.
If you run into any issues that are not fixed by referring to the README or feature requests please open an [issue](https://github.com/kneely/note-macros/issues).

6
docs/user/recipes/recipes.md
View File

@@ -30,7 +30,7 @@ A #recipe is a guide, tip or strategy for getting the most out of your Foam work
## Discover
- Explore your notes using [[graph-visualization]]
- Explore your notes using [[graph-view]]
- Discover relationships with [[backlinking]]
- Simulating [[unlinked-references]]
@@ -44,7 +44,7 @@ A #recipe is a guide, tip or strategy for getting the most out of your Foam work
- Use shortcuts for [[creating-new-notes]]
- Instantly create and access your [[daily-notes]]
- Add and explore [[tags]]
- Create [[note-templates]]
- Create [[templates]]
- Find [[orphans]]
- Use custom [[note-macros]] to create weekly, monthly etc. notes
- Draw [[diagrams-in-markdown]]
@@ -59,7 +59,7 @@ A #recipe is a guide, tip or strategy for getting the most out of your Foam work
- _More..._
- VS Code Advanced Features [[todo]] [[good-first-task]]
- Focus with Zen Mode
- Display content of other notes in the preview tab by [[including-notes]]
- Display content of other notes in the preview tab by [[embeds]]
## Version control