` tag to create a nice Markdown-style link. ## Instructions 1. Highlight desired URL 2. `Cmd` + `Shift` + `P` 3. `Expand URL to Markdown` 4. Profit Tip: If you paste a lot of links, give the action a custom [key binding](https://code.visualstudio.com/docs/getstarted/keybindings) ## Feedback and issues Have an idea for the extension? [Feel free to share! 🎉](https://github.com/Skn0tt/markdown-link-expander/issues) --- ### User Recipes Capture Notes With Drafts Pro (`docs/user/recipes/capture-notes-with-drafts-pro.md`) # Capture Notes With Drafts Pro With this #recipe you can create notes on your iOS device, which will automatically be imported into Foam. ## Context - You use [Foam for VSCode](https://marketplace.visualstudio.com/items?itemName=foam.foam-vscode) to manage your notes - You wish to adopt a practice such as [A writing inbox for transient and incomplete notes](https://notes.andymatuschak.org/A%20writing%20inbox%20for%20transient%20and%20incomplete%20notes) - You wish to use [Drafts Pro](https://docs.getdrafts.com/) to capture quick notes into your Foam notes from your iOS device ## Other tools - We assume you are familiar with how to use GitHub (if you are using Foam this is implicit) - You have an iOS device with [Drafts](https://getdrafts.com/) - You have upgraded to [Drafts Pro](https://docs.getdrafts.com/draftspro) (needed to edit actions). ## Instructions 1. [Create a new action in Drafts](https://docs.getdrafts.com/docs/actions/editing-actions) 2. Add a single [step](https://docs.getdrafts.com/actions/steps/) of type Script 3. Edit the script adding the code from the block below 4. Edit settings at the top of the script to suit your preferences 5. Set other Action options in Drafts as you wish 6. Save the Action 7. In GitHub [create a Personal Access Token](https://github.com/settings/tokens) and give it `repo` scope - make a note of the token 8. In Drafts create a note 9. Select the action you created in steps 1-6 10. On the first run you will need to add the following information: 1. your GitHub username 2. the repository name of your Foam repo 3. the GitHub access token from step 7 4. An author name 11. Check your GitHub repo for a commit 12. If you are publishing your Foam to the web you may want to edit your publishing configuration to exclude inbox files - as publishing (and method) is a user choice that is beyond the scope of this recipe ## Code for Drafts Action ``` /* Detailed source-code truncated for AI context efficiency. */ ``` --- ### User Recipes Capture Notes With Shortcuts And Github Actions (`docs/user/recipes/capture-notes-with-shortcuts-and-github-actions.md`) # Capture Notes With Shortcuts and GitHub Actions With this #recipe you can create notes on your iOS device, which will automatically be imported into Foam. ## Context - You use [Foam for VSCode](https://marketplace.visualstudio.com/items?itemName=foam.foam-vscode) to manage your notes - You wish to adopt a practice such as [A writing inbox for transient and incomplete notes](https://notes.andymatuschak.org/A%20writing%20inbox%20for%20transient%20and%20incomplete%20notes) - You wish to use [Shortcuts](https://support.apple.com/guide/shortcuts/welcome/ios) to capture quick notes into your Foam notes from your iOS device ## Other tools - We assume you are familiar with how to use GitHub (if you are using Foam this is implicit) - You have an iOS device. ## Instructions 1. Setup the [`foam-capture-action`]() in your GitHub Repository, to be triggered by "Workflow dispatch" events. ``` name: Manually triggered workflow on: workflow_dispatch: inputs: data: description: 'What information to put in the knowledge base.' required: true jobs: store_data: runs-on: ubuntu-latest # If you encounter a 403 error from a workflow run, try uncommenting the following 2 lines (taken from: https://stackoverflow.com/questions/75880266/cant-make-push-on-a-repo-with-github-actions accepted answer) # permissions: # contents: write steps: - uses: actions/checkout@master - uses: anglinb/foam-capture-action@main with: {% raw %} capture: ${{ github.event.inputs.data }} {% endraw %} - run: | git config --local user.email "example@gmail.com" git config --local user.name "Your name" git commit -m "Captured from workflow trigger" -a git push -u origin master ``` 2. In GitHub [create a Personal Access Token](https://github.com/settings/tokens) and give it `repo` scope - make a note of the token 3. Run this command to find your `workflow-id` to be used in the Shortcut. ```bash curl \ -H "Accept: application/vnd.github.v3+json" \ -H "Authorization: Bearer <GITHUB_TOKEN>" \ https://api.github.com/repos/<owner>/<repository>/actions/workflows ``` 4. Copy this [Shortcut](https://www.icloud.com/shortcuts/57d2ed90c40e43a5badcc174ebfaaf1d) to your iOS devices and edit the contents of the last step, `GetContentsOfURL` - Make sure you update the URL of the shortcut step with the `owner`, `repository`, `workflow-id` (from the previous step) - Make sure you update the headers of the shortcut step, replaceing `[GITHUB_TOKEN]` with your Personal Access Token (from step 2) 5. Run the shortcut & celebrate! ✨ (You should see a GitHub Action run start and the text you entered show up in `inbox.md` in your repository.) --- ### User Recipes Diagrams In Markdown (`docs/user/recipes/diagrams-in-markdown.md`) # Diagrams in Markdown We have two alternative #recipe for displaying diagrams in markdown: - [Diagrams in Markdown](#diagrams-in-markdown) - [Mermaid](#mermaid) - [Draw.io](#drawio) - [Using Draw.io](#using-drawio) ## Mermaid You can use [Mermaid](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-mermaid) plugin to draw and preview diagrams in your content. ## Draw.io [Draw.io](https://marketplace.visualstudio.com/items?itemName=hediet.vscode-drawio) extension allows you to create, edit, and display your diagrams without leaving Visual Studio Code. The `.drawio.svg` or `.drawio.png` files can be automatically embedded and displayed in published Foams, no export needed. FYI, the diagram below was made using Draw.io! You can check the diagram [here](../../assets/images/diagram-drawio-demo.drawio.svg). ### Using Draw.io 1. Install [Draw.io](https://marketplace.visualstudio.com/items?itemName=hediet.vscode-drawio) VS Code extension. 2. Create a new `*.drawio.svg` or `*.drawio.png` file. 3. Start drawing your diagram. Once you done, save it. 4. Embed the diagram file as you embedding the image file, for example: `` --- ### User Recipes Export To Pdf (`docs/user/recipes/export-to-pdf.md`) # Export to PDF This #recipe shows how to export a note to PDF. ## Required extensions - **[vscode-pandoc](https://marketplace.visualstudio.com/items?itemName=chrischinchilla.vscode-pandoc)** ## Required third-party tools - [Pandoc](https://pandoc.org/installing.html) - A [LaTeX distribution](https://www.latex-project.org/get/) such as TeXLive (Linux), MacTeX (MacOS), or MikTeX (Windows) Check that Pandoc is installed by opening a terminal and running `pandoc --version`. Check that Pandoc can produce PDFs with LaTeX by running the following in the terminal. ``` echo It is working > test.md pandoc test.md -o test.pdf ``` ## Instructions 1. Create a folder in your workspace named `.pandoc`. Take note of the full path to this directory. The rest of this recipe will refer to this path as `$WORKSPACE/.pandoc`. 2. Download the template file [`foam.latex`](https://raw.githubusercontent.com/Hegghammer/foam-templates/main/foam.latex) from [Hegghammer/foam-templates](https://github.com/Hegghammer/foam-templates) and place it in `$WORKSPACE/.pandoc`. 3. In VSCode, open `settings.json` for your user (or just for your workspace if you prefer), and add the following line: ``` "pandoc.pdfOptString": "--from=markdown+wikilinks_title_after_pipe --resource-path $WORKSPACE/.pandoc --template foam --listings", ``` Make sure to replace `$WORKSPACE/.pandoc` with the real full path to the `.pandoc` directory you created earlier. 4. Open a Foam note in VSCode. 5. Press `Ctrl` + `k`, `p`. Choose "pdf", and press `Enter`. The PDF should look something like this: ## Options If you include a name in the `author` parameter in the YAML of the Foam note, that name will feature in the PDF header on the top left. If you don't want syntax highlighting and frames around the codeblocks, remove `--listings` from the `pandoc.pdfOptString` parameter in `settings.json`. ## Further customization If you know some LaTeX, you can [tweak](https://bookdown.org/yihui/rmarkdown-cookbook/latex-template.html) the `foam.latex` template to your needs. Alternatively, you can supply another ready-made template such as [Eisvogel](https://github.com/Wandmalfarbe/pandoc-latex-template); just place the `TEMPLATE_NAME.latex` file in `$WORKSPACE/.pandoc`. You can also use all of Pandoc's [other functionalities](https://learnbyexample.github.io/customizing-pandoc/) by tweaking the `pandoc.pdfOptString` parameter in `settings.json`. --- ### User Recipes Generate Material For Mkdocs Site (`docs/user/recipes/generate-material-for-mkdocs-site.md`) # Generate a site using the Material for MkDocs theme Configuring a static-site generator (SSG) to publish your Foam provides access to functionality not available through Foam's default publishing mechanism. For example, compare the [original Foam documentation site](https://docs.foam.md/) with a [Material for MkDocs version](https://djplaner.github.io/foam-with-material-for-mkdocs/) created using the simple configuration detailed below. Try out the search functionality on the Material for MkDocs version. This [digital garden](https://djon.es/memex) and this [blog](https://djon.es/blog/) provide more advanced examples of Foam content published using Material for MkDocs. The following explains how to configure the [Material for MkDocs theme](https://squidfunk.github.io/mkdocs-material/) for the [MkDocs SSG](https://www.mkdocs.org) to publish your Foam. Like most SSGs (e.g. [Gatsby](https://www.gatsbyjs.com/) is another SSG that can be [used to publish your Foam](https://docs.foam.md/publishing/generate-gatsby-site/)) site content is accepted in the form of Markdown files. Like those produced by Foam. SSGs differ in the languages they are written in (MkDocs is Python, Gatsby is Javascript and React) and the features they provide. MkDocs and Material for MkDocs are designed to support project documentation. Gatsby is more general purpose and provides a nice feature set. You choose your poison. ## Requirements To use Material for MkDocs to publish your Foam you need: - An existing Foam workspace with content. - [Python installed on your computer](https://realpython.com/installing-python/). - Some familiarity and comfort with using the command line on your computer. ## Instructions Configuring Material for MkDocs to publish your Foam involves the following steps: 1. [Install Material for MkDocs and other requirements](#install-material-for-mkdocs-and-other-requirements). Install the Material for MkDocs theme, MkDocs, and other required Python modules. 2. [Configure Material for MkDocs for your Foam](#configure-material-for-mkdocs-for-your-foam). Create a `mkdocs.yml` file in the root of your Foam workspace directory. This file configures Material for MkDocs to work with your Foam. 3. [Preview and test your site locally](#preview-and-test-your-site-locally). Run MkDocs to preview and test your Material for MkDocs Foam site locally. Good for testing and local use. 4. [Further customise Material for MkDocs](#further-customise-material-for-mkdocs). Explore and leverage the additional configuration settings, possible customisations, and additional themes and plugins to customise your site to your needs. 5. [Publish your site](#publish-your-site). Publish your Material for MkDocs Foam site to the web for others to enjoy. There are many options for publishing your site, including GitHub, GitLab, Netlify, and others. ### Install Material for MkDocs and other requirements Material for MkDocs provides [detailed installation instructions](https://squidfunk.github.io/mkdocs-material/getting-started/) which cover the full range of options for installing and configuring Material for MkDocs. The following is a summary of the recommended process. 1. Within your Foam workspace directory, create a [Python virtual environment](https://realpython.com/what-is-pip/#using-pip-in-a-python-virtual-environment) - `python -m venv .venv` - `source .venv/bin/activate` (Linux/Mac) or `.venv\Scripts\activate` (Windows) 2. Install Material for MkDocs - `pip install mkdocs-material` 3. Install additional Python modules - `pip install mkdocs-roamlinks-plugin` - `pip install mkdocs-exclude` ### Configure Material for MkDocs for your Foam To configure Material for MkDocs for your Foam workspace, create a `mkdocs.yml` file in the root of your Foam workspace directory. Below you will find a sample `mkdocs.yml` file (adapted from the [foam-mkdocs-template repository](https://github.com/Jackiexiao/foam-mkdocs-template/tree/master)). Copy and paste it into your `mkdocs.yml` file, then edit it to suit your needs. In particular, don't forget to change the `site_name` and `site_url` to match your Foam workspace. Though this can be left a little later. Material for MkDocs provides documentation on both [minimal](https://squidfunk.github.io/mkdocs-material/creating-your-site/#minimal-configuration) and [advanced](https://squidfunk.github.io/mkdocs-material/creating-your-site/#advanced-configuration) configuration of `mkdocs.yml`. Which are revisited in the [customise section below](#further-customise-your-site) ```yaml site_name: My site # Change this to your site name site_url: https://mydomain.org/mysite # change this theme: name: material features: - navigation.expand - tabs markdown_extensions: - attr_list - pymdownx.tabbed - nl2br - toc: permalink: '#' slugify: !!python/name:pymdownx.slugs.uslugify - admonition - codehilite: guess_lang: false linenums: false - footnotes - meta - def_list - pymdownx.arithmatex - pymdownx.betterem: smart_enable: all - pymdownx.caret - pymdownx.critic - pymdownx.details - pymdownx.inlinehilite - pymdownx.magiclink - pymdownx.mark - pymdownx.smartsymbols - pymdownx.superfences - pymdownx.tasklist - pymdownx.tilde plugins: - search - roamlinks - exclude: glob: - '*.tmp' - '*.pdf' - '*.gz' regex: - '.*\.(tmp|bin|tar)$' ``` ### Preview and test your site locally MkDocs provides a live preview server allowing you to preview and test your Material for MkDocs Foam site. The server will continue to rebuid your site as you write. The simplest method to use the preview service is to run the following command whilst in the rood directory of your Foam workspace: ```bash mkdocs serve ``` See the Material for MkDocs site for more, including [how to run the preview server via docker](https://squidfunk.github.io/mkdocs-material/creating-your-site/#previewing-as-you-write) ### Further customise your site Further customisation is available through expanding the configuration of Material for MkDocs, using additional MkDocs plugins, customising HTML/CSS, using Markdown extensions, writing your own Python scripts, and more. For more on the available customisation paths, see the following: - Material for MkDocs [Advanced configuration](https://squidfunk.github.io/mkdocs-material/creating-your-site/#advanced-configuration) or the [Set up section](https://squidfunk.github.io/mkdocs-material/setup/) For more configuration options to be included in your `mkdocs.yml` file, including customising: colours, fonts, language, icons, navigation, header, footer etc. - Material for MkDocs [Customisation](https://squidfunk.github.io/mkdocs-material/customization/) For advice on enhancing the visual design of your site by customising and replacing provided HTML, CSS, and Javascript. - Material for MkDocs [Reference](https://squidfunk.github.io/mkdocs-material/reference/) An overview of customisation methods that can be used directly within your Markdown files, including: admonitions, annotations, buttons, code blocks, content tabs, data tables, diagrams, grids, Mathematics, etc. - a [catalog of 300 MkDocs projects and plugins](https://github.com/mkdocs/catalog#readme) For functionality and ideas not included in Material for MkDocs, including: additional themes, plugins, and extensions. ### Building and publishing your site As a Static Site Generator (SSG), MkDocs generates a collection of static HTML and other types of files. Publishing your site involves building those HTML files and placing them onto your web server. The method will vary depending on your web server and hosting provider. The MkDocs documentation site provides an explanation of the [simplest method to publish your site to any provider](https://www.mkdocs.org/user-guide/deploying-your-docs/#other-providers) using `mkdocs build` and `scp`. The Material for MkDocs [publish page](https://squidfunk.github.io/mkdocs-material/publishing-your-site/) lists options for publishing to - GitHub using [mkdocs](https://squidfunk.github.io/mkdocs-material/publishing-your-site/#with-mkdocs) Perhaps the simplest method, if you are already using GitHub to host your Foam workspace. - GitHub using [GitHub actions](https://squidfunk.github.io/mkdocs-material/publishing-your-site/github-actions/) A more automated method of publishing your site to GitHub, using GitHub actions. - [GitLab](https://squidfunk.github.io/mkdocs-material/publishing-your-site/#with-mkdocs) - [Cloudflage pages](https://deborahwrites.com/guides/deploy-host-mkdocs/deploy-mkdocs-material-cloudflare/) - [Netlify](https://deborahwrites.com/guides/deploy-host-mkdocs/deploy-mkdocs-material-netlify/) - [Fly.io](https://documentation.breadnet.co.uk/cloud/fly/mkdocs-on-fly/#prerequisites) - [Scaleway](https://www.scaleway.com/en/docs/tutorials/using-bucket-website-with-mkdocs/) --- ### User Recipes How To Write Recipes (`docs/user/recipes/how-to-write-recipes.md`) # How to Write Recipes This is an example of how to structure a Recipe. The first paragraph or two should explain the purpose of the recipe succinctly, including why it's useful, if that's not obvious. Recipes are intended to document: - How to use Foam's basic features - Power user pro-tips - Useful customisations of the default Foam environment - Integrations with third party tools and extensions (should be listed below) ## Required Extensions - **[Hacker Typer](https://marketplace.visualstudio.com/items?itemName=jevakallio.vscode-hacker-typer)** (not really required for this recipe, just an example) - [Foam for VSCode](https://marketplace.visualstudio.com/items?itemName=foam.foam-vscode) (installed by default) The first section should be a bulleted list of extensions required to use this recipe. At a minimum, this section should list all additional, non-standard extensions. Ideally, you should also note which Foam [[recommended-extensions]] are responsible for providing this feature, so any issue reports can be directed to the correct repositories. When creating new recipes, if you don't know which extension does what, you can leave it out. ## Instructions Here we describe how the extension should be used. You may include a screenshot or GIF of the feature in action by uploading an image to the `assets/images` directory. Please try to keep GIFs as small as possible by recording them with a low frame rate. That's pretty much it! ## How to contribute You can add [[recipes]] by creating a pull request to [foambubble/foam](https://github.com/foambubble/foam) on GitHub. Read more in our [contribution guide](https://github.com/foambubble/foam/blob/main/CONTRIBUTING.md). [recommended-extensions]: ../getting-started/recommended-extensions.md 'Recommended Extensions' [recipes]: recipes.md 'Recipes' --- ### User Recipes Markup Converter (`docs/user/recipes/markup-converter.md`) # Markup Converter This #recipe allows you to convert any document into Markdown for storing them in your notes. We will be using [Pandoc](https://pandoc.org/), a popular universal document converter. It can convert documents in Microsoft Word, HTML, LaTeX, and many other formats to various formats including markdown and many others. ## Instructions We will go through the example of converting Microsoft Word documents to Markdown. For detailed instructions on how to use Pandoc, please refer to the [Pandoc documentation](https://pandoc.org/MANUAL.html). 1. [Install Pandoc](https://pandoc.org/installing.html) 1. Open the terminal of your choice and verify that Pandoc is installed by running `pandoc --version` 1. Copy the Microsoft Word documents that you want to convert into a new folder 1. Change the current directory to the folder containing the Microsoft Word documents 1. Copy one of the following commands (based on your operating system) into your terminal and press `Enter` to run ### Linux and macOS (Bash) ```bash find -name "*.docx" -type f -exec sh -c ' for f; do pandoc --extract-media=./ -f docx -t markdown -o "${f%.*}.md" "$f" done ' find-sh {} + ``` ### Windows (PowerShell) ```powershell Get-ChildItem . -Filter *.docx | Foreach-Object { pandoc --extract-media=./ --from docx --to markdown $_ -o $_.Name.Replace('.docx', '.md') } ``` ### Relevant Configurations [Pandoc](https://pandoc.org/) accepts a range of command line arguments to control the conversion process. Here, we'll mention a few that are relevant to the example above. - `--extract-media=./` is used to extract the images from the Microsoft Word documents and store them in a subfolder named `media` - `-t markdown` converts the Microsoft Word documents to [Pandoc’s Markdown](https://pandoc.org/MANUAL.html#pandocs-markdown). You can also use `-t gfm` to convert to [GitHub Flavored Markdown](https://docs.github.com/en/get-started/writing-on-github) Note that you may want to review the converted Markdown files to ensure that the conversion was successful. Then, You may want to delete the original Microsoft Word documents. --- ### User Recipes Migrating From Obsidian (`docs/user/recipes/migrating-from-obsidian.md`) # Coming from Obsidian Good news: an Obsidian vault is, for the most part, already a Foam workspace. Both store your notes as plain Markdown files in a directory, so in most cases you can just open your vault folder in VS Code with the Foam extension installed and start working. ## Try it in 30 seconds 1. Install the [Foam extension](https://marketplace.visualstudio.com/items?itemName=foam.foam-vscode) in VS Code. 2. **File → Open Folder…** and pick your existing Obsidian vault. 3. That's it — wikilinks, backlinks, the graph, and tags should all work. You can keep using Obsidian on the same folder side-by-side. Foam doesn't change your files unless you ask it to. ## What works the same | Obsidian | Foam | | --------------------- | ------------------- | | `[[wikilinks]]` | [[wikilinks]] | | `![[embeds]]` | [[embeds]] | | `[[note#^block-id]]` | [[block-anchors]] | | Backlinks panel | [[backlinking]] | | Graph view | [[graph-view]] | | Daily notes | [[daily-notes]] | | Templates | [[templates]] | | Tags (`#tag`) | [[tags]] | | Frontmatter / aliases | [[note-properties]] | ## What's different or missing These are the things most likely to surprise you: - **Live preview / WYSIWYG editing.** Foam uses VS Code's standard split editor + preview pane rather than inline rendering. - **Community plugins.** Obsidian plugins don't run in Foam. Foam relies on the wider VS Code extension ecosystem instead — see [[recommended-extensions]]. - **Canvas.** Not supported (tracked in [#1450](https://github.com/foambubble/foam/issues/1450)). - **Tasks plugin syntax.** Not supported (tracked in [#1466](https://github.com/foambubble/foam/issues/1466)). - **Callouts / Admonitions** (`> [!note]`). Not rendered natively; works as a normal blockquote. - **Wikilink resolution.** Foam and Obsidian agree on most cases but resolve identifier-style links slightly differently. See the comparison table in [[wikilinks]]. ## A few practical tips - **`.obsidian/` folder.** Leave it alone if you're keeping both tools. Add it to `.gitignore` if you only want to track notes. - **Templates.** Foam templates live in `.foam/templates/` — see [[templates]] for the format. - **Don't see something here?** Search [open issues](https://github.com/foambubble/foam/issues) — chances are someone has already asked. ## Related - [[wikilinks]] — full link syntax reference - [[first-workspace]] — set up Foam from scratch - [[recommended-extensions]] — VS Code extensions that pair well with Foam [wikilinks]: ../features/wikilinks.md 'Wikilinks' [embeds]: ../features/embeds.md 'Note Embeds' [block-anchors]: ../features/block-anchors.md 'Block Anchors' [backlinking]: ../features/backlinking.md 'Backlinking' [graph-view]: ../features/graph-view.md 'Graph Visualization' [daily-notes]: ../features/daily-notes.md 'Daily Notes' [templates]: ../features/templates.md 'Note Templates' [tags]: ../features/tags.md 'Tags' [note-properties]: ../features/note-properties.md 'Note Properties' [recommended-extensions]: ../getting-started/recommended-extensions.md 'Recommended Extensions' [first-workspace]: ../getting-started/first-workspace.md 'Creating Your First Workspace' --- ### User Recipes Migrating From Onenote (`docs/user/recipes/migrating-from-onenote.md`) # Migrating from OneNote This guide mostly duplicates the instructions at the repo for the PowerShell [script](https://github.com/nixsee/ConvertOneNote2MarkDown). ## Summary The powershell script 'ConvertOneNote2MarkDown-v2.ps1' will utilize the OneNote Object Model on your workstation to convert all OneNote pages to Word documents and then utilizes PanDoc to convert the Word documents to Markdown (.md) format. It will also: - Create a folder structure for your Notebooks and Sections. - Process pages that are in sections at the Notebook, Section Group and 1st Nested Section Group levels. - Allow you you choose between putting all Images in a central '/media' folder for each notebook, or in a separate '/media' folder in each folder of the hierarchy. - Fix image references in the resulting .md files, generating relative references to the image files within the markdown document. - A title, description, and date header will be added to each file as well. - And more (see details at repo)! ## Usage 1. Start the OneNote application. All notebooks currently loaded in [OneNote](https://getonetastic.com/download) will be converted. 2. It is advised that you install [Onetastic](https://getonetastic.com/download) and the attached macro, which will automatically expand any collapsed paragraphs in the notebook. They won't be exported otherwise. - To install the macro, click the New Macro Button within the Onetastic Toolbar and then select File -> Import and select the .xml macro included in the release. - Run the macro for each Notebook that is open 3. For the next sections, it is highly recommended that you use VS Code, and its embedded PowerShell terminal, as this allows you to edit and run the script, as well as check the results of the .md output all in one window. 4. Whatever you choose, you will need to do the following: 1. Clone the script to your computer (see [here](https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository), if you're unfamiliar with git). 2. Once cloned, navigate to the repo folder. In VS Code, use File -> Add Folder to Workspace, right click on the folder in the left side bar and click [Open In Integrated Terminal](../../assets/images/migrating-one-note.png). 3. Run the script by executing `.\ConvertOnenote2Markdown-v2` * if you receive an error, try running this line to bypass security: ```Set-ExecutionPolicy Bypass -Scope Process``` * if you still have trouble, try running both Onenote and Powershell as an administrator. 5. It will ask you for the path to store the markdown folder structure. Please use an empty folder. If using VS Code, you might not be able to paste the filepath - right click on the blinking cursor and it will paste from clipboard. **Attention:** use a full absolute path for the destination. 6. Read the prompts carefully to select your desired options. If you aren't actively editing your pages in Onenote, it is HIGHLY recommended that you don't delete the intermediate word docs, as they take 80+% of the time to generate. They are stored in their own folder, out of the way. You can then quickly re-run the script with different parameters until you find what you like. 7. Sit back and wait until the process completes. 8. To stop the process at any time, press Ctrl+C. 9. If you like, you can inspect some of the .md files prior to completion. If you're not happy with the results, stop the process, delete the .md and re-run with different parameters. 10. At this point, you should be ready to load the new directory into Foam! --- ### User Recipes Multi Root Workspaces (`docs/user/recipes/multi-root-workspaces.md`) # Multi-root workspaces A VS Code [multi-root workspace](https://code.visualstudio.com/docs/editor/multi-root-workspaces) has several folders side by side. A common setup is a knowledge base you add to each of your projects, so both your own notes and the project's notes are at hand: ``` my-project.code-workspace ├── my-project/ ← first folder └── knowledge-base/ ← your knowledge base, added to every workspace ``` Foam indexes every folder, so links and the graph work across them. What needs care is where new notes go: by default, Foam creates them in the first folder. ## Settings Put Foam settings in the `.code-workspace` file or in your user settings. In a multi-root workspace, VS Code ignores them in a folder's own `.vscode/settings.json`. ## Templates Foam looks for [[templates]] in the templates folder (`.foam/templates` by default) of every folder in the workspace: - **Foam: Create New Note From Template** lists the templates of all folders. When two folders have a template with the same name, it shows which folder each one is in. - For the special `new-note` and `daily-note` templates, Foam checks each folder in the order they're listed and uses the first one it finds. - New templates are created in the first folder. ## Create notes in a specific folder A template's `filepath` can name the folder a note goes in: start it with `/` and the folder's name. For example, if you want all new notes to go in `knowledge-base/inbox/`, your `new-note` template, `knowledge-base/.foam/templates/new-note.md`, would look like this: ```markdown --- foam_template: filepath: '/knowledge-base/inbox/$FOAM_SLUG.md' --- # $FOAM_TITLE ``` **Foam: Create New Note**, and Ctrl+clicking a `[[placeholder]]`, then create the note in `knowledge-base/inbox/`, in every workspace you add `knowledge-base` to, as long as the project has no `new-note` template of its own. To choose for each note instead, give the template another name, such as `global-note.md`, and pick it with **Foam: Create New Note From Template**. [[daily-notes]] work the same way, with `knowledge-base/.foam/templates/daily-note.md`: ```markdown --- foam_template: filepath: '/knowledge-base/journal/$FOAM_DATE_YEAR-$FOAM_DATE_MONTH-$FOAM_DATE_DATE.md' --- # $FOAM_DATE_YEAR-$FOAM_DATE_MONTH-$FOAM_DATE_DATE ``` A few things to know: - Use the folder's name on disk, with the same capitalization, not a different name you gave it in the `.code-workspace` file. - If no folder has that name, the path starts from the first folder: `/journal/today.md` goes in `my-project/journal/`. - The same template works when you open the knowledge base on its own: `/knowledge-base/inbox/` is then its own `inbox/` folder. With the default settings, notes created without a `filepath`, such as with **Foam: Create New Note** when there's no `new-note` template, go in the first folder. ## Related - [[templates]] — the full template reference - [[daily-notes]] — daily note templates - [[notes-in-a-subfolder]] — notes inside a bigger project, in a single folder [templates]: ../features/templates.md 'Note Templates' [daily-notes]: ../features/daily-notes.md 'Daily Notes' [notes-in-a-subfolder]: notes-in-a-subfolder.md 'Keep your notes in a subfolder' --- ### User Recipes Notes In A Subfolder (`docs/user/recipes/notes-in-a-subfolder.md`) # Keep your notes in a subfolder Sometimes your notes live inside a bigger project rather than in a repository of their own — a `knowledge-base` folder next to your source code, say: ``` my-project/ ├── knowledge-base/ ← your notes ├── src/ └── README.md ``` Foam works in this layout with three bits of configuration. There's no single "Foam root" setting: instead you tell Foam which files to index, where your templates live, and where new notes should go. ## 1. Index only your notes In `.vscode/settings.json`: ```json { "foam.files.include": ["knowledge-base/**"] } ``` Foam now builds the graph from your notes alone and ignores the rest of the project. Reload the window to apply it. ## 2. Point at your templates ```json { "foam.files.include": ["knowledge-base/**"], "foam.templates.folder": "knowledge-base/.foam/templates" } ``` Your [[templates]] live at `knowledge-base/.foam/templates/` rather than the project root. ## 3. Create new notes in the right place By default, clicking a `[[new-note]]` placeholder creates the file at the top of the project. To send it to your notes folder instead, create `knowledge-base/.foam/templates/new-note.md`: ```markdown --- foam_template: filepath: 'knowledge-base/${FOAM_TITLE}.md' --- # ${FOAM_TITLE} ``` Foam uses `new-note.md` whenever it creates a note without being told where to put it, so this covers Ctrl+clicking a placeholder as well as the **Foam: Create New Note** command. For [[daily-notes]], do the same in `knowledge-base/.foam/templates/daily-note.md`: ```markdown --- foam_template: filepath: 'knowledge-base/journal/${FOAM_DATE_YEAR}-${FOAM_DATE_MONTH}-${FOAM_DATE_DATE}.md' --- # ${FOAM_DATE_YEAR}-${FOAM_DATE_MONTH}-${FOAM_DATE_DATE} ``` ## Linking `[[wikilinks]]` work exactly as they do anywhere else — `[[my-note]]` finds `knowledge-base/my-note.md`, because Foam only indexes your notes folder. The one thing to know is that a leading slash means "the folder you opened in VS Code", not "my notes folder". So `[[/my-note]]` and `[my note](/my-note.md)` point at `my-project/my-note.md`, which isn't where your notes are. Write `[[/knowledge-base/my-note]]` if you want the full path — or just use `[[my-note]]`, which is shorter and unambiguous. This also means you can link out to the rest of the project: `[the build script](/scripts/build.sh)` does what you'd expect, and works on GitHub too. ## What stays at the project root When you delete a note, Foam moves it to `.foam/trash/` at the top of the project, and [[smart-folders]] are saved under `.foam/queries/`. If you'd rather keep everything together, move those folders into your notes directory by hand — Foam will recreate them at the project root next time, so it's a matter of taste rather than correctness. ## Related - [[first-workspace]] — setting up a Foam workspace - [[templates]] — the full template reference - [[wikilinks]] — link syntax, including paths and identifiers [templates]: ../features/templates.md 'Note Templates' [daily-notes]: ../features/daily-notes.md 'Daily Notes' [wikilinks]: ../features/wikilinks.md 'Wikilinks' [smart-folders]: ../features/smart-folders.md 'Smart Folders' [first-workspace]: ../getting-started/first-workspace.md 'Creating Your First Workspace' --- ### User Recipes Predefined User Snippets (`docs/user/recipes/predefined-user-snippets.md`) # Pre-defined User Snippets This #recipe allows us to introduce slash-style commands to Foam, by using [VS Code Snippets](https://code.visualstudio.com/docs/editor/userdefinedsnippets). Consider the below snippets: ```json { "Zettelkasten Id": { "scope": "markdown", "prefix": "/id", "description": "Zettelkasten Id", "body": [ "${CURRENT_YEAR}-${CURRENT_MONTH}-${CURRENT_DATE} ${CURRENT_HOUR}:${CURRENT_MINUTE}:${CURRENT_SECOND}" ] }, "Current date": { "scope": "markdown", "prefix": "/date", "description": "Current date", "body": [ "${CURRENT_YEAR}-${CURRENT_MONTH}-${CURRENT_DATE} ${CURRENT_HOUR}:${CURRENT_MINUTE}:${CURRENT_SECOND}" ] } } ``` Which would look like: Using snippets enables Foam users to add [[custom-snippets]] themselves so they live alongside the first-class `/commands`. ## Notes & Considerations - VS Code supplies "commands" already via the command palette - Consider the UX around this. Users less familiar with VS Code are more likely to be familiar with `/` to trigger a command menu. Experienced VS Code users may be more likely to favour the command palette. - We can use `TabCompletionProvider` and `snippets` and mix them (maybe) via the following VS Code setting: `"editor.snippetSuggestions": "inline" | "top" | "bottom" | "none"` - For more discussion, consult the PR [here](https://github.com/foambubble/foam/pull/192). ## Simplifying Markdown Syntax Some markdown syntax is difficult for users who have never authored markdown before. Take for example a checkbox/todo. The following syntax is required: ``` - [ ] Something todo... ``` We could provide snippets that expand out into the associated markdown syntax, like in the below GIF: The JSON for these snippets can be found [here](https://github.com/foambubble/foam/pull/192#issuecomment-666736270). [custom-snippets]: ../features/custom-snippets.md 'Adding Custom Snippets' --- ### User Recipes Real Time Collaboration (`docs/user/recipes/real-time-collaboration.md`) # Real-time Collaboration This #recipe is here to just tell you that VS Code Live Share will allow you to collaborate live on your notes. --- ### User Recipes Recipes (`docs/user/recipes/recipes.md`) # Recipes A #recipe is a guide, tip or strategy for getting the most out of your Foam workspace! - [Recipes](#recipes) - [Contribute](#contribute) - [Take smart notes](#take-smart-notes) - [Discover](#discover) - [Organise](#organise) - [Write](#write) - [Version control](#version-control) - [Publish](#publish) - [Collaborate](#collaborate) - [Workflow](#workflow) - [Creative ideas](#creative-ideas) - [Other](#other) ## Contribute - Start by reading the [contribution guide](https://github.com/foambubble/foam/blob/main/CONTRIBUTING.md) - If you discover features not listed here, we'd love to have them! [[how-to-write-recipes]]. ## Take smart notes - Clip webpages with [[web-clipper]] - Convert Microsoft Word files into Markdown with [[markup-converter]] - Coming from Obsidian? See [[migrating-from-obsidian]] - Coming from OneNote? See [[migrating-from-onenote]] ## Discover - [[search-and-navigate-notes]] - Explore your notes using [[graph-view]] - Discover relationships with [[backlinking]] ## Organise - Using [[backlinking]] for reference lists. - Keeping your notes inside a bigger project with [[notes-in-a-subfolder]]. - Using one notes folder across several projects with [[multi-root-workspaces]]. ## Write - Link documents with [[wikilinks]]. - Create notes with custom [[commands]] and key bindings - Instantly create and access your [[daily-notes]] - Add and explore [[tags]] - Create [[templates]] - Find [[orphans]] - Draw [[diagrams-in-markdown]] - Prettify your links, [[automatically-expand-urls-to-well-titled-links]] - Style your environment with [[custom-markdown-preview-styles]] - Paste and link [[add-images-to-notes]] - [[shows-image-preview-on-hover]] - [Markdown All-in-One](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one) features - Manage checklists - Automatic Table of Contents - Live preview markdown - _More..._ - VS Code Advanced Features - Focus with Zen Mode - Display content of other notes in the preview tab by [[embeds]] ## Version control - Quick commits with VS Code's built-in source control - Store your workspace in an auto-synced GitHub repo with [[write-your-notes-in-github-gist]] - Sync your GitHub repo automatically using the [GitDoc VSCode Plugin](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.gitdoc) [[automatic-git-syncing]]. ## Publish - Publish using official Foam template - Publish to [[publish-to-github-pages]] - Publish to [[publish-to-gitlab-pages]] - Publish to [[publish-to-azure-devops-wiki]] - Publish to [[publish-to-vercel]] - Publish using community templates - [[publish-to-netlify-with-eleventy]] by [@juanfrank77](https://github.com/juanfrank77) - [[generate-gatsby-site]] by [@mathieudutour](https://github.com/mathieudutour) and [@hikerpig](https://github.com/hikerpig) - [[generate-material-for-mkdocs-site]] by [@djplaner](https://github.com/djplaner) - Make the site your own by [[publish-to-github]]. - Render math symbols, by either - adding client-side [[math-support-with-mathjax]] to the default [[publish-to-github-pages]] site - adding a custom Jekyll plugin to support [[math-support-with-katex]] - Export note to PDF [[export-to-pdf]] ## Collaborate - Give your team push access to your [GitHub repo](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/inviting-collaborators-to-a-personal-repository) - Real-time collaboration via VS Code Live Share [[real-time-collaboration]] - Accept patches via GitHub PRs ## Workflow - Capture notes from Drafts app on iOS [[capture-notes-with-drafts-pro]] - Capture notes from iOS Shortcuts [[capture-notes-with-shortcuts-and-github-actions]] ## Creative ideas Creative ideas welcome! - Support [Anki](https://apps.ankiweb.net/) cards from notes like [Remnote](https://www.remnote.io/) _See [[how-to-write-recipes]] and the [contribution guide](https://github.com/foambubble/foam/blob/main/CONTRIBUTING.md)._ ## Other Thought of a recipe but don't see a category for them? Add them here and we'll organise them once we detect a theme. _See [[how-to-write-recipes]] and the [contribution guide](https://github.com/foambubble/foam/blob/main/CONTRIBUTING.md)._ [how-to-write-recipes]: how-to-write-recipes.md 'How to Write Recipes' [search-and-navigate-notes]: search-and-navigate-notes.md 'Search and Navigate Notes' [web-clipper]: web-clipper.md 'Web Clipper' [markup-converter]: markup-converter.md 'Markup Converter' [migrating-from-obsidian]: migrating-from-obsidian.md 'Coming from Obsidian' [migrating-from-onenote]: migrating-from-onenote.md 'Migrating from OneNote' [backlinking]: ../features/backlinking.md 'Backlinking' [wikilinks]: ../features/wikilinks.md 'Wikilinks' [commands]: ../features/commands.md 'Foam Commands' [daily-notes]: ../features/daily-notes.md 'Daily Notes' [tags]: ../features/tags.md 'Tags' [orphans]: ../tools/orphans.md 'Orphaned Notes' [diagrams-in-markdown]: diagrams-in-markdown.md 'Diagrams in Markdown' [automatically-expand-urls-to-well-titled-links]: automatically-expand-urls-to-well-titled-links.md 'Automatically Expand URLs to Well-Titled Links' [custom-markdown-preview-styles]: ../features/custom-markdown-preview-styles.md 'Custom Markdown Preview Styles' [add-images-to-notes]: add-images-to-notes.md 'Add images to your notes' [shows-image-preview-on-hover]: shows-image-preview-on-hover.md 'Shows Image Preview on Hover' [write-your-notes-in-github-gist]: write-your-notes-in-github-gist.md 'Write your notes in GitHub Gist' [automatic-git-syncing]: automatic-git-syncing.md 'Automatically Sync with Git' [publish-to-github-pages]: ../publishing/publish-to-github-pages.md 'GitHub Pages' [publish-to-gitlab-pages]: ../publishing/publish-to-gitlab-pages.md 'GitLab Pages' [publish-to-azure-devops-wiki]: ../publishing/publish-to-azure-devops-wiki.md 'Publish to Azure DevOps Wiki' [publish-to-vercel]: ../publishing/publish-to-vercel.md 'Publish to Vercel' [publish-to-netlify-with-eleventy]: ../publishing/publish-to-netlify-with-eleventy.md 'Publish to Netlify with Eleventy' [generate-gatsby-site]: ../publishing/generate-gatsby-site.md 'Generate a site using Gatsby' [generate-material-for-mkdocs-site]: generate-material-for-mkdocs-site.md 'Generate a site using the Material for MkDocs theme' [publish-to-github]: ../publishing/publish-to-github.md 'Publish to GitHub' [math-support-with-mathjax]: ../publishing/math-support-with-mathjax.md 'Math Support' [math-support-with-katex]: ../publishing/math-support-with-katex.md 'Katex Math Rendering' [export-to-pdf]: export-to-pdf.md 'Export to PDF' [real-time-collaboration]: real-time-collaboration.md 'Real-time Collaboration' [capture-notes-with-drafts-pro]: capture-notes-with-drafts-pro.md 'Capture Notes With Drafts Pro' [capture-notes-with-shortcuts-and-github-actions]: capture-notes-with-shortcuts-and-github-actions.md 'Capture Notes With Shortcuts and GitHub Actions' [graph-view]: ../features/graph-view.md 'Graph Visualization' [templates]: ../features/templates.md 'Note Templates' [embeds]: ../features/embeds.md 'Note Embeds' [notes-in-a-subfolder]: notes-in-a-subfolder.md 'Keep your notes in a subfolder' [multi-root-workspaces]: multi-root-workspaces.md 'Multi-root workspaces' --- ### User Recipes Search And Navigate Notes (`docs/user/recipes/search-and-navigate-notes.md`) # Search and Navigate Notes This #recipe covers the ways you can find and navigate notes in Foam. ## Quick Open Press `Cmd+P` (`Ctrl+P` on Windows) and type a note name to open it directly. Partial matches work — `proj meet` will find `projects/meeting-notes.md`. ## Full-text Search Press `Cmd+Shift+F` (`Ctrl+Shift+F` on Windows) to search across all note content. Use the filter icon to restrict search to specific folders or file types. ## Note Navigator Panel The **Note Navigator** panel in the sidebar lets you browse and filter all notes in your workspace. Use the filter input to narrow by name, and switch between flat and grouped-by-folder views from the panel toolbar. ## Other Panels Foam adds several panels to the sidebar that help you discover notes: - **Backlinks** — shows which notes link to the currently open note - **Placeholders** — lists wikilinks that don't yet have a corresponding file - **Orphans** — lists notes with no incoming or outgoing links (see [[orphans]]) - **Tags** — browse all tags and jump to tagged notes (see [[tags]]) ## Graph View The [[graph-view]] gives a visual overview of your entire knowledge base. Click any node to open that note. You can also [[resource-filters|filter the graph]] to focus on a subset of notes by tag, type, path, or title. ## Random Note Run **"Foam: Open Random Note"** from the command palette to resurface forgotten notes. [orphans]: ../tools/orphans.md 'Orphaned Notes' [tags]: ../features/tags.md 'Tags' [graph-view]: ../features/graph-view.md 'Graph View' [resource-filters]: ../features/resource-filters.md 'Resource Filters' --- ### User Recipes Shows Image Preview On Hover (`docs/user/recipes/shows-image-preview-on-hover.md`) # Shows Image Preview on Hover This #recipe allows you to see a preview of an image on hover. Use extension: [Image preview](https://marketplace.visualstudio.com/items?itemName=kisstkondoros.vscode-gutter-preview) to shows image preview in the gutter and on hover It looks like this --- ### User Recipes Take Notes From Mobile Phone (`docs/user/recipes/take-notes-from-mobile-phone.md`) # Take notes on mobile phones This #recipe offers solutions to taking Foam notes on the go. For the time being we have decided to not build a mobile app, but rely on third parties. The most promising options are: ### [GitJournal](https://gitjournal.io/) Pros - Open source - Already a usable solution. - Provides functionality to edit, create, and browser markdown files. - Support journal mode, todo lists, and free writing - Syncs to GitHub repo - Supports Wikilinks - Supports Backlinks - Developer is happy to prioritize Foam compatibility Cons - Doesn't generate link reference lists (but this is ok, since [[workspace-lint]] as a GitHub action can solve this) - Not as sleek as Apple/Google notes, some keyboard state glitching on Android, etc. - Lack of control over roadmap. Established product with a paid plan, so may not be open to Foam-supportive changes and additions that don't benefit most users. Verdict: Good. By far best effort/outcome ratio would be to help improve GitJournal rather than building a [bespoke mobile app](#bespoke-mobile-app-for-foam). ### GitHub Codespaces Pros - Works out of the box just like the desktop app Cons - not generally available quite yet - [Pricing](https://docs.github.com/en/free-pro-team@latest/github/developing-online-with-codespaces/about-billing-for-codespaces) For a quick demo, see <https://www.youtube.com/watch?v=KI5m4Uy8_4I>. Verdict: Good. Pricing should be reasonable for taking notes on the fly. Harder to assess for people who would constantly use Foam from mobile phone. ## Bespoke mobile app for Foam Given we already have a solution, why would we spend time and effort building a bespoke mobile app? - Taking notes on the go is a key part of a good note taking process, and the process should feel effortless - Having a custom app could help us support key user workflows in a more Foam-specific manner If such an app was worth building, it would have to have the following features: - Instant loading and syncing for quick notes - Sleek, simple, beautifully designed user experience. - Ability to search and navigate forward links and back links (only in paid GitJournal version) - Killer feature that makes it the best note taking tool for Foam (?) Given the effort vs reward ratio, it's a low priority for core team, but if someone wants to work on this, we can provide support! Talk to us on the #mobile-apps channel on [Foam Discord](https://discord.com/invite/HV2tn2FpEk). [workspace-lint]: ../tools/workspace-lint.md 'Lint' --- ### User Recipes Web Clipper (`docs/user/recipes/web-clipper.md`) # Web Clipper This #recipe allows you to convert any web content into Markdown for storing them in your notes. There are a couple of options when it comes to clipping web pages: - [Web Clipper](https://marketplace.visualstudio.com/items?itemName=jsartelle.web-clipper) - This is a Web Clipper as a VSCode extension, takes a webpage URL and outputs Markdown. Uses [mercury](https://github.com/postlight/mercury-parser) - [Markdown Clipper](https://github.com/deathau/markdownload) - A Firefox and Google Chrome extension to clip websites and download them into a readable markdown file. - [Web Clipper](https://clipper.website/) - A Firefox, Chrome and Edge extension to clip websites and save them directly to the GitHub repository into a readable markdown file. --- ### User Recipes Write Your Notes In Github Gist (`docs/user/recipes/write-your-notes-in-github-gist.md`) # Write your notes in GitHub Gist This #recipe will allow you to persist your notes in a GitHub repository, and automatically sync changes without needing to manually commit/push/pull, then GistPad might be an option worth exploring. [GistPad](https://aka.ms/gistpad) is a Visual Studio Code extension that allows you to edit your GitHub gists and repos, without needing to clone anything locally. It provides support for editing Foam workspaces, complete with `[[link]]` [completion/navigation](https://github.com/vsls-contrib/gistpad#links), [daily pages](https://github.com/vsls-contrib/gistpad#daily-pages), [pasting images](https://github.com/vsls-contrib/gistpad#pasting-images-1) and [backlinks](https://github.com/vsls-contrib/gistpad#backlinks). <img width="700px" src="https://user-images.githubusercontent.com/116461/87234714-96ba9400-c388-11ea-92c3-544d9a3bb633.png" /> ## Getting started To start using GistPad for your Foam-based knowledge base, simply perform the following steps: 1. Download the [GistPad extension](https://aka.ms/gistpad) and then re-start Visual Studio Code 1. Run the `GistPad: Sign In` command and then complete the authentication flow using your GitHub account 1. Run the `GistPad: Open Repository` command and select the `Create repo from template...` or `Create private repo from template...` depending on your preference 1. Select the `Foam-style wiki` template, and then specify a name for your Foam workspace (e.g. `my-foam-notes`, `johns-knowledge-base`) Your new repo will be created in your GitHub account, and the `Foam` welcome page will be automatically opened. If you already have an existing Foam workspace in GitHub, then when you run step #3 above, simply select or specify the name of the GitHub repository instead. > Note: If you have any and all feedback on how GistPad can be improved to support your Foam workflow, please don't hesitate to [let us know](https://github.com/vsls-contrib/gistpad)! 👍 <img width="700px" src="https://user-images.githubusercontent.com/116461/87863222-c1b76180-c90d-11ea-87d9-04bee1c58a0d.png" /> ## Managing your workspace Once you've opened/created the Foam repository, it will appear in the `Repositories` view of the `GistPad` tab (the one with the little notebook icon). From this tree view, you can add/edit/delete/rename new pages, upload local files, as well as view the backlinks for each page (they appear as child notes of a page). <img width="250px" src="https://user-images.githubusercontent.com/116461/87234704-83a7c400-c388-11ea-90a8-2a660bef4dc5.png" /> ## Editing your workspace When you create or open a page, you can edit the markdown content as usual, as well as [paste images](https://github.com/vsls-contrib/gistpad#pasting-images-1), and create [`[[links]]` to other pages](https://github.com/vsls-contrib/gistpad#links). When you type `[[`, you'll receive auto-completion for the existing pages in your workspace, and you can also automatically create new pages by simply creating a link to it. Since you're using the Visual Studio Code markdown editor, you can benefit from all of the rich language services (e.g. syntax highlighting, header collapsing), as well as the extension ecosystem (e.g. [Emojisense](https://marketplace.visualstudio.com/items?itemName=bierner.emojisense)). ## Navigating your workspace When editing a file, you can easily navigate `[[links]]` by hovering over them to see a preview of their contents and/or `cmd+clicking` on them in order to jump to the respective page. Furthermore, when you add a link to a page, a [backlink](https://github.com/vsls-contrib/gistpad#backlinks) is automatically added to it. You can view a page's backlinks using either of the following techniques: 1. Expanding the file's node in the `Repositories` tree, since it's child nodes will represent backlinks. This makes it easy to browse your pages and their backlinks in a single hierarchical view. 1. Opening a file, and then viewing it's backlinks list at the bottom of the editor view. This makes it easy to read a page and then see its backlinks in a contextually rich way. ## Daily Pages In addition to creating arbitrary pages, you can use GistPad for journaling or capturing [daily notes](https://github.com/vsls-contrib/gistpad#daily-pages). Simply click the calendar icon in the `Repositories` tree, which will open up the page that represents today. If the page doesn't already exist, then it will be created in the workspace before being opened. <img width="700px" src="https://user-images.githubusercontent.com/116461/87234721-b356cc00-c388-11ea-946a-e7f9c92258a6.png" /> --- ### User Tools Cli (`docs/user/tools/cli.md`) # Foam CLI The `foam` command line tool lets you work with your Foam workspace from the terminal — search, inspect, and manage notes without opening VS Code. ## Installation ```bash npm install foam-cli ``` ## Usage ``` foam <command> [options] ``` Set the `FOAM_WORKSPACE` environment variable to avoid typing `--workspace` on every command: ```bash export FOAM_WORKSPACE=/path/to/your/notes ``` All commands accept `--format json` for machine-readable output, useful for scripting. ## Files outside the workspace Commands only change files inside the workspace. If a path leads outside it, for example through a folder that is a symlink to somewhere else, the command stops with `Cannot write outside the workspace: <path>` instead of writing there. To work with those files, run the command with `--workspace` pointing at the folder they live in. ## Commands | Command | Description | | ----------- | ------------------------------------------------- | | [[daily]] | Show or create the daily note for a date | | [[grep]] | Search note content by pattern | | [[links]] | Show links to and from a note | | [[lint]] | Check notes for issues | | [[list]] | List notes, tags, orphans, placeholders, and more | | [[mcp]] | Expose the workspace to AI agents via MCP | | [[note]] | Show, create, move, or delete notes | | [[outline]] | Show the heading structure of a note | | [[rename]] | Rename notes, tags, sections, or block anchors | | [[search]] | Search notes by title, tag, or frontmatter | | [[tag]] | List, rename, or search tags | | [[update]] | Check for a newer version of foam-cli | [daily]: cli/daily.md 'foam daily' [grep]: cli/grep.md 'foam grep' [links]: cli/links.md 'foam links' [lint]: cli/lint.md 'foam lint' [list]: cli/list.md 'foam list' [mcp]: cli/mcp.md 'foam mcp' [note]: cli/note.md 'foam note' [outline]: cli/outline.md 'foam outline' [rename]: cli/rename.md 'foam rename' [search]: cli/search.md 'foam search' [tag]: cli/tag.md 'foam tag' [update]: cli/update.md 'foam update' --- ### User Tools Foam Logging In Vscode (`docs/user/tools/foam-logging-in-vscode.md`) # Foam logging in VsCode The Foam extension logs details about what its doing in vscode's `Output` tab. Generally this is only useful if you're reporting an issue about Foam. 1. To show the tab, click on `View > Output`. 2. In the dropdown on the right of the tab, select `Foam`. When reporting an issue about Foam, set the log level to `Debug`: ## Change the log level for the session Execute the command `Foam: Set log level`. ## Change the default logging level 1. Open workspace settings (`cmd+,`, or execute the `Preferences: Open Workspace Settings` command) 2. Look for the entry `Foam > Logging: Level` --- ### User Tools Orphans (`docs/user/tools/orphans.md`) # Orphaned Notes Foam helps you to find orphans: notes that have neither forward links nor backlinks. Orphans can be found in the Orphans panel. Two settings allows you to control the behaviour of the Orphans panel: - `foam.orphans.exclude`: list of glob patterns that will be used to exclude directories. For example, a value of `["journal/**/*"]` would exclude your daily notes. - `foam.orphans.groupBy`: sets the default view mode of the Orphans panel: either groups by folder (by default), or lists all orphans. The view can be toggled on the fly from the panel, but it won't overwrite the setting. To list orphans from the terminal, see [[list|foam list orphans]]. [list|foam list orphans]: cli/list.md 'foam list' --- ### User Tools Telemetry (`docs/user/tools/telemetry.md`) # Telemetry Foam collects anonymous usage data to help understand how Foam is used and to prioritize improvements. This page describes what is sent, what is never sent, and how to opt out. ## What is never collected This applies to every Foam component: - Note content, titles, file names, or tag names - Wikilink targets, search queries, or any text you typed - Folder paths or any user-defined string - Free-text configuration values - Command arguments, CLI flag values, or MCP tool arguments - Stack traces or error messages (only the error class name is sent) - Anything that could identify you personally ## What is collected Every event includes: - Which component sent it (`vscode`, `cli`, `mcp`) - The version of that component and of `@foam/core` - Your OS family — CLI/MCP send `os.platform` (`darwin`, `linux`, `win32`) and Node version; VS Code's library reports OS and version via its own `common.*` properties (see [Common properties](#common-properties)) - An anonymous identifier — CLI and MCP share an installation UUID generated locally on first run. VS Code uses the pseudonymous machine ID provided by Microsoft's `@vscode/extension-telemetry` library (`common.vscodemachineid`); we cannot disable that and we never link it to the CLI/MCP ID. At a high level: - **VS Code extension** sends a small set of session events: that Foam loaded, which commands you ran, your enum/boolean settings, and bucketed workspace size (e.g. "201-500 notes"). No file names, paths, or note titles. - **CLI** sends one event per invocation: which command ran, how long it took (bucketed: `0-10ms`, `11-50ms`, `51-300ms`, `301-1000ms`, `1-5s`, `5-30s`, `30s+`), and bucketed workspace size. - **MCP** sends one event per tool call the LLM makes: which tool was called, how long it took, and whether it succeeded. Tool arguments and returned content are never sent. The full event list is at the [bottom of this page](#full-event-list). ## How to opt out ### VS Code extension Foam respects VS Code's global telemetry setting. Open Settings, search for `telemetry.telemetryLevel`, and set it to `off`. ### CLI On the first run, the CLI prints a notice describing what is collected and asks you to confirm. The default is **enabled** — pressing Enter accepts it. Your choice is saved in `~/.config/foam/config.json` and not asked again. If the CLI is run non-interactively (CI, piped input, MCP launched by Claude Desktop / Cursor, etc.), it cannot prompt — it prints a disclosure to stderr and defaults to enabled **for that session only**. No choice is persisted, so the next interactive CLI run will still ask. To make the choice durable in a non-interactive context, set `FOAM_TELEMETRY=0` or `FOAM_TELEMETRY=1` in the environment, or edit `~/.config/foam/config.json` directly. You can change your choice at any time: - Set `FOAM_TELEMETRY=0` in your environment, or - Edit `~/.config/foam/config.json` and set `"telemetry.enabled": false` ### MCP MCP runs as a child of the CLI (`foam mcp ...`, typically configured in Claude Desktop / Cursor / `mcp.json`). It inherits the CLI's opt-out — set `FOAM_TELEMETRY=0` in the MCP server's environment, or edit `~/.config/foam/config.json`. ## Where the data goes All events are sent to a single Azure Application Insights resource owned by the Foam project. Connection strings used to send data are not secrets — they only permit writing events, never reading them. Aggregated, anonymized usage data may be shared with the Foam community to inform roadmap discussions. Raw event data is not shared. ## Full event list ### Common properties The properties below are attached to every event. | Property | Components | Example | Description | | ------------------ | --------------------- | -------------------------- | -------------------------------------------------------------------------------------- | | `foam.component` | CLI, MCP, VS Code | `cli`, `mcp`, `vscode` | Which Foam component emitted the event | | `foam.version` | CLI, MCP, VS Code | `0.26.0` | Version of that component | | `foam.coreVersion` | CLI, MCP, VS Code | `0.4.1` | Version of `@foam/core` | | `node.version` | CLI, MCP | `22.5.0` | Node runtime version (CLI/MCP only — VS Code reports it via `common.platformversion`) | | `os.platform` | CLI, MCP | `darwin`, `linux`, `win32` | Operating system family (CLI/MCP only — VS Code reports it via `common.os`) | | `installationId` | CLI, MCP | (random UUID) | Anonymous installation ID shared across CLI and MCP. Sent on the App Insights envelope as the `ai.user.id` tag, not as an event property. Omitted on the `cli.first-run` event. | VS Code events additionally carry the `common.*` properties added by Microsoft's `@vscode/extension-telemetry` library — these are not controlled by Foam: | Property | Description | | ------------------------- | ----------------------------------------------------------------------------------------------------------------- | | `common.extname` | Extension name (`foam.foam-vscode`) | | `common.extversion` | Extension version | | `common.vscodemachineid` | Pseudonymous machine identifier generated by VS Code. Distinct from Foam's `installationId`; we cannot disable it. | | `common.vscodesessionid` | Per-session identifier generated by VS Code | | `common.vscodeversion` | VS Code version | | `common.vscodecommithash` | VS Code commit hash | | `common.os` | OS running VS Code | | `common.platformversion` | OS/platform version | | `common.product` | VS Code host (`desktop`, `github.dev`, `codespaces`, …) | | `common.uikind` | `web` or `desktop` | | `common.remotename` | Type of remote connection if any (`ssh`, `wsl`, `dev-container`, or `other`) | | `common.nodeArch` | Node architecture (e.g. `arm64`, `x64`, or `web`) | You can disable VS Code's telemetry — and therefore everything Foam sends from VS Code — via the global **`telemetry.telemetryLevel`** setting (`off`). The CLI and MCP opt-out is separate and is described above. ### Bucket scales - **Duration**: `<10ms`, `<50ms`, `<500ms`, `<5s`, `<30s`, `30s+` - **Workspace size (note count)**: `0`, `1-10`, `11-50`, `51-200`, `201-500`, `501-1000`, `1001-2000`, `2001-5000`, `5001-10000`, `10000+` ### VS Code events (`vscode.*`) | Event | When it fires | Properties | | ----------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `vscode.session-started` | Once per extension activation | none | | `vscode.session-with-command` | First Foam command in a session | none | | `vscode.session-with-note` | First markdown file opened in a session | none | | `vscode.command` | Every Foam command invocation | `command` (identifier only — no arguments) | | `vscode.config-snapshot` | Once per session | selected enum/boolean settings — e.g. `graph.onStartup`, `completion.linkFormat`, `links.hover.enable`, `graph.viewsConfigured` (count, not names). Free-text settings are never included. | | `vscode.workspace-stats` | Once per session | `noteCount` and `attachmentCount` (both bucketed), `numTemplates` (count of files in the templates folder), `hasDailyNoteTemplate` | | `vscode.error` | An unhandled error in a Foam feature | `context` (feature name), `errorType` (error class name only — no message, no stack) | ### CLI events (`cli.*`) | Event | When it fires | Properties | |---|---|---| | `cli.command-invoked` | Once per CLI invocation that runs a known command, after it completes. Skipped for `--help`, `--version`, `foam config`, and unknown commands (typos) — those never emit telemetry. | `command`, `durationBucket`, `exitCode`. When the command threw an error caught by the dispatcher, also `errorType` (error class name only — no message, no stack) and `errorContext` (where it was caught — `dispatch`). Some commands attach extra properties — e.g. `note create` and `daily --create` attach `template-type` (one of `default`, `daily-note`, `custom`) and `template-format` (`md` / `js`). Both are omitted when no template was applied (e.g. a `note create` that fell back to the minimal `# title` body). `daily` additionally attaches `mode`: `create` when a new daily note was written this invocation, `open` for read-only lookups and for `--create` against a note that already existed (nothing was written). | | `cli.first-run` | At most twice per installation: once for the strongest consent outcome we've recorded so far. Anonymous — carries no `installationId`, no `os.platform`, no `node.version`. An install that runs headlessly first (e.g. MCP) fires once with `default_on`; if the same install later answers an interactive CLI prompt, a second event fires with `granted` / `declined` (the "upgrade"). Subsequent runs of either kind are deduped via state.json. | `consent`: `granted` / `declined` (from an interactive prompt), or `default_on` (non-interactive first encounter) | ### MCP events (`mcp.*`) | Event | When it fires | Properties | |---|---|---| | `mcp.session-started` | Once per server start | `client` (e.g. `claude-desktop`, `cursor`, omitted if not exposed); `noteCount` and `attachmentCount` (both bucketed); `mode` (`read` or `read-write` — `read-write` is set when the CLI is started with `--allow-writes`; the default is `read`) | | `mcp.session-with-tool` | First tool call in a session | none | | `mcp.tool-invoked` | Every tool call (sent unsampled) | `tool` (name only — arguments never recorded), `durationBucket`, `outcome` (`success` / `error`) | | `mcp.error` | An unhandled error during MCP dispatch. Rare in practice: tool handlers are wrapped to convert throws into structured `isError: true` results, which surface as `outcome: 'error'` on `mcp.tool-invoked`. `mcp.error` is the safety net for anything that escapes that wrapping. | `context`, `tool`, `errorType` | --- ### User Tools Workspace Lint (`docs/user/tools/workspace-lint.md`) # Lint To store your personal knowledge graph in markdown files instead of a database, we need some additional tooling to create and maintain relationships with notes. **Foam Lint** (inspired by Andy Matuschak's [note-link-janitor](https://github.com/andymatuschak/note-link-janitor)) helps you migrate existing notes to Foam, and maintain your Foam's health over time. Currently, Foam Lint helps you to: - Ensure your [[link-reference-definitions]] are up to date - Ensure every document has a well-formatted title (required for Markdown Links, Markdown Notes, and Foam Gatsby Template compatibility) The link reference definition check only runs when `foam.edit.linkReferenceDefinitions` is set to `withExtensions` or `withoutExtensions` in your workspace settings. It is `off` by default, so if you want Lint to keep definitions up to date — from VS Code, a git hook, or a GitHub action — turn it on first. See [[link-reference-definitions]]. In the future, Foam Lint can help you with - Lint, format and structure notes - Rename and move notes around while keeping their references up to date. ## Using Lint from VS Code (Experimental) Execute the "Foam: Lint Workspace" command from the command palette. ## Using lint from command line Foam Lint can be installed from [NPM](https://www.npmjs.com/) and executed as a standalone CLI tool: ```sh > npm install foam-cli > foam lint --workspace path/to/workspace ``` You can run Foam Lint as a git hook on every commit to ensure your workspace links are up to date. This can be especially helpful if you edit your markdown documents from other apps. You can also run Foam Lint from a GitHub action to ensure that all changes coming to your workspace are up to date. This can be useful when editing your Foam notes from mobile (i.e. via [GitJournal](https://gitjournal.io)), or your Foam has multiple contributors and you want to ensure that all changes are correctly integrated. [link-reference-definitions]: ../features/link-reference-definitions.md 'Link Reference Definitions' --- ### User Tools Cli Daily (`docs/user/tools/cli/daily.md`) # foam daily Show or create the daily note for a date. ``` foam daily [options] ``` Without `--create`, the command only reports whether the note exists. With `--create`, it writes the note if it doesn't exist yet, using your daily note template if one is configured. ## Options | Option | Description | | --------------------- | -------------------------------------------------------------------------- | | `--date <YYYY-MM-DD>` | Date to target (default: today) | | `--create` | Create the note if it doesn't exist | | `--path-only` | Print only the resolved file path (useful for scripting) | | `--trust` | Run a JavaScript daily note template (`daily-note.js`) | | `--workspace <dir>` | Workspace root (default: `FOAM_WORKSPACE` env var, then current directory) | | `--format <fmt>` | Output format: `text` (default) or `json` | ## Examples Show today's daily note status: ```bash foam daily # journal/2024-01-15.md [exists] ``` Create today's daily note: ```bash foam daily --create ``` Get the path to a specific date's note (for scripting): ```bash foam daily --date 2024-01-10 --path-only # /home/user/notes/journal/2024-01-10.md ``` Open today's note in your editor: ```bash $EDITOR $(foam daily --create --path-only) ``` ## Daily note path If your daily note template (`.foam/templates/daily-note.md` or `.foam/templates/daily-note.js`) sets a file path, the note goes there. Otherwise the deprecated `foam.openDailyNote.*` settings in `.vscode/settings.json` decide, and without them notes go to `journal/YYYY-MM-DD.md` — the same place VS Code puts them. The template, when there is one, always provides the content. The path must stay inside the workspace, even through symlinks: otherwise `foam daily --create` stops with an error telling you to check the template's file path and the `foam.openDailyNote.directory` setting. See [[templates]] for how to configure daily note templates. ## JavaScript templates A JavaScript template runs code on your computer, so when your workspace has `.foam/templates/daily-note.js`, `foam daily` stops with an error unless you add `--trust`: ```bash foam daily --create --trust ``` Only add `--trust` if you wrote the template yourself, or trust whoever did. [templates]: ../../features/templates.md 'Note Templates' --- ### User Tools Cli Grep (`docs/user/tools/cli/grep.md`) # foam grep Search note content by pattern. ``` foam grep <pattern> [options] ``` Searches the text content of all notes in the workspace. The pattern is matched case-insensitively as a regular expression. Unlike [[search|foam search]], this command searches the full text of each note rather than indexed metadata. ## Options | Option | Description | | ------------------- | -------------------------------------------------------------------------- | | `--context <n>` | Show `n` lines of surrounding context around each match | | `--no-line-number` | Omit line numbers from output | | `--limit <n>` | Max number of matching files to return (default: 20) | | `--workspace <dir>` | Workspace root (default: `FOAM_WORKSPACE` env var, then current directory) | | `--format <fmt>` | Output format: `text` (default) or `json` | ## Examples Search for a word across all notes: ```bash foam grep "quantum" # physics/quantum-mechanics.md:3: Quantum mechanics describes... # research/reading-list.md:12: See also quantum entanglement ``` Search with context lines: ```bash foam grep "TODO" --context 2 ``` Limit results: ```bash foam grep "meeting" --limit 5 ``` Use in a script (JSON output): ```bash foam grep "action item" --format json ``` [search]: search.md 'foam search' --- ### User Tools Cli Links (`docs/user/tools/cli/links.md`) # foam links Show links to and from a note. ``` foam links (<identifier> | --path <path>) [options] ``` Displays the outgoing links (notes this note links to) and incoming links (notes that link to this note, also called backlinks). The command can also be invoked as `foam connections`. ## Options | Option | Description | | ------------------- | -------------------------------------------------------------------------- | | `--path <path>` | Target note by exact file path instead of identifier | | `--outgoing` | Show only outgoing links | | `--incoming` | Show only incoming links (backlinks) | | `--workspace <dir>` | Workspace root (default: `FOAM_WORKSPACE` env var, then current directory) | | `--format <fmt>` | Output format: `text` (default) or `json` | By default, both outgoing and incoming links are shown. ## Examples Show all links for a note: ```bash foam links my-note # Outgoing (2): # → related-topic notes/related-topic.md # → another-note notes/another-note.md # # Incoming (1): # ← index index.md ``` Show only backlinks: ```bash foam links my-note --incoming ``` Target by file path: ```bash foam links --path notes/my-note.md ``` Get links as JSON for scripting: ```bash foam links my-note --format json ``` ## Note identifiers Foam identifies notes by the shortest unique part of their filename (without extension). For example, a note at `projects/alpha/notes.md` might be identified as `notes` if that's unique, or `alpha/notes` if there's ambiguity. Use [[note|foam note id]] to check how a note is identified. See also [[backlinking]] for the backlinks panel in VS Code. [backlinking]: ../../features/backlinking.md 'Backlinks' [note]: note.md 'foam note' --- ### User Tools Cli Lint (`docs/user/tools/cli/lint.md`) # foam lint Check notes for issues. ``` foam lint [options] ``` Scans all notes in the workspace and reports problems such as missing headings or stale link reference definitions. With `--fix`, auto-fixable issues are corrected in place. Which rules run depends on your workspace settings — see [Rules](#rules). Exits with code `2` when issues are found (and no `--fix`), making it easy to use in CI pipelines. ## Options | Option | Description | | ------------------- | -------------------------------------------------------------------------- | | `--fix` | Apply all auto-fixable issues | | `--rule <id>` | Run only the given rule (can be repeated) | | `--workspace <dir>` | Workspace root (default: `FOAM_WORKSPACE` env var, then current directory) | | `--format <fmt>` | Output format: `text` (default) or `json` | ## Rules | Rule ID | Description | Auto-fixable | | ------------------- | ------------------------------------------------------ | :----------: | | `missing-heading` | Notes without a top-level heading | Yes | | `stale-definitions` | Link reference definitions that are outdated or unused | Yes | `stale-definitions` only runs when [[link-reference-definitions]] are enabled for the workspace, the same as the "Foam: Lint Workspace" command in VS Code. The `foam.edit.linkReferenceDefinitions` setting is `off` by default, so turn it on in your workspace's `.vscode/settings.json` to have the rule report and fix definitions: ```json { "foam.edit.linkReferenceDefinitions": "withExtensions" } ``` Asking for the rule with `--rule stale-definitions` while the setting is `off` is a command error (exit `1`). ## Exit codes | Code | Meaning | | ---- | --------------- | | `0` | No issues found | | `1` | Command error | | `2` | Issues found | ## Examples Check the workspace for issues: ```bash foam lint # notes/my-note.md # 5:1 warning Missing heading missing-heading # # 1 problem (0 errors, 1 warning, 1 fixable with --fix) ``` Fix all auto-fixable issues: ```bash foam lint --fix ``` Run only one rule: ```bash foam lint --rule missing-heading ``` Use in CI: ```bash foam lint || echo "Lint issues found — please fix before merging" ``` Get results as JSON: ```bash foam lint --format json ``` See also [[workspace-lint]] for running lint from VS Code. [workspace-lint]: ../workspace-lint.md 'Workspace Lint' [link-reference-definitions]: ../../features/link-reference-definitions.md 'Link Reference Definitions' --- ### User Tools Cli List (`docs/user/tools/cli/list.md`) # foam list List notes, tags, orphans, placeholders, dead-ends, or templates. ``` foam list <what> [options] ``` ## What to list | Value | Description | | -------------- | ------------------------------------------------ | | `notes` | All notes in the workspace | | `tags` | All tags used across notes | | `orphans` | Notes with no links in or out | | `deadends` | Notes with no outgoing links | | `placeholders` | Wikilinks that don't resolve to an existing note | | `templates` | Note templates in `.foam/templates/` | ## Options | Option | Description | | ---------------------- | ---------------------------------------------------------------------------------- | | `--type <type>` | (notes) Filter by resource type: `note` (any markdown file), `attachment`, `image` | | `--tag <tag>` | (notes) Filter by tag — repeat for multiple tags (AND logic) | | `--limit <n>` | (notes, tags) Maximum number of results | | `--prefix <str>` | (tags) Filter by tag prefix | | `--sort <count\|name>` | (tags) Sort order (default: `name`) | | `--workspace <dir>` | Workspace root (default: `FOAM_WORKSPACE` env var, then current directory) | | `--format <fmt>` | Output format: `text` (default) or `json` | ## Examples List all notes: ```bash foam list notes ``` List notes with a specific tag: ```bash foam list notes --tag project ``` List notes tagged both `project` and `active`: ```bash foam list notes --tag project --tag active ``` List all tags sorted by usage count: ```bash foam list tags --sort count ``` List tags starting with `project/`: ```bash foam list tags --prefix project/ ``` Find orphaned notes (no links in or out): ```bash foam list orphans ``` Find broken wikilinks (links that don't resolve to a note): ```bash foam list placeholders ``` List available templates: ```bash foam list templates ``` See also [[orphans]] for the orphaned notes panel in VS Code, and [[tags]] for tag management in the editor. [orphans]: ../orphans.md 'Orphaned Notes' [tags]: ../../features/tags.md 'Tags' --- ### User Tools Cli Mcp (`docs/user/tools/cli/mcp.md`) # foam mcp Run a [Model Context Protocol](https://modelcontextprotocol.io) server over stdio so AI agents (Claude Desktop, Cursor, Zed, …) can read and traverse your Foam workspace as a knowledge graph instead of grepping files. ``` foam mcp [options] ``` The server stays running for the whole agent session: it loads the workspace once at startup and watches the filesystem so subsequent tool calls reflect notes you edited in your editor. ## Options | Option | Description | | ------------------- | -------------------------------------------------------------------------- | | `--workspace <dir>` | Workspace root (default: `FOAM_WORKSPACE` env var, then current directory) | | `--allow-writes` | Let the agent create, edit, delete, and rename notes and tags. Off by default. | By default the server is **read-only**. Add `--allow-writes` to let the agent modify your notes. ## Connecting an AI client Most MCP clients accept a JSON configuration similar to this — point them at `foam-cli`: ```json { "mcpServers": { "foam": { "command": "npx", "args": ["foam-cli", "mcp", "--workspace", "/path/to/your/notes"] } } } ``` For Claude Desktop the file is `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS and `%APPDATA%\Claude\claude_desktop_config.json` on Windows. Restart the client after editing. To allow the agent to edit notes too, add `"--allow-writes"` to the `args` array. ## What the agent can do Read tools (always available): - Browse the workspace (`list_resources`, `get_resource`, `read_resource`, `get_workspace_info`) - Follow the link graph (`get_connections`, `traverse_graph`, `get_orphans`, `get_deadends`, `get_placeholders`, `get_graph_summary`) - Search by tag, frontmatter property, or text (`list_tags`, `search_by_tag`, `search_by_property`, `search_resources`) - Inspect note structure (`get_outline`) Write tools (only with `--allow-writes`): - Create, update, delete, and move notes (`create_resource`, `update_resource`, `delete_resource`, `move_resource`) - Add, remove, or rename tags (`add_tags`, `remove_tags`, `rename_tag`) Write tools only change files inside the workspace. A change that would land outside it, including through a symlinked folder, fails with `Cannot write outside the workspace`. ## Logs Foam writes its logs to stderr (stdout is reserved for MCP traffic). To increase verbosity for troubleshooting: ```bash FOAM_LOG_LEVEL=debug foam mcp --workspace /path/to/notes ``` Valid values: `debug`, `info`, `warn`, `error` (default). --- ### User Tools Cli Note (`docs/user/tools/cli/note.md`) # foam note Show, create, move, or delete notes. ``` foam note <subcommand> [options] ``` ## Subcommands ### show Print metadata for a note. ```bash foam note show (<identifier> | --path <path>) [--links] [--content] ``` | Option | Description | | --------------- | ------------------------------------------------- | | `--links` | Include outgoing and incoming links in the output | | `--content` | Print the full note content instead of metadata | | `--path <path>` | Target by exact file path | Example: ```bash foam note show my-note # ID: my-note # Title: My Note # Path: notes/my-note.md # Type: note # Tags: #project #active ``` ### id Print the Foam identifier for a note. ```bash foam note id (<identifier> | --path <path>) ``` Useful for resolving how Foam identifies a note when there could be ambiguity: ```bash foam note id my-note # my-note ``` ### create Create a new note. ```bash foam note create [options] ``` | Option | Description | | ---------------------- | -------------------------------------------- | | `--title <title>` | Note title (default: `untitled`) | | `--dir <dir>` | Directory relative to workspace root | | `--property <key=val>` | Add a frontmatter property (can be repeated) | If a `new-note` template exists in `.foam/templates/`, it is used to generate the note content and file path. See [[templates]] for details. Example: ```bash foam note create --title "Meeting Notes" --dir meetings # Created: meetings/meeting-notes.md (id: meeting-notes) ``` ### move Move a note to a new path, rewriting all wikilinks that point to it. ```bash foam note move (<identifier> | --path <path>) --to <new-path> ``` | Option | Description | | --------------- | --------------------------------------------- | | `--to <path>` | Destination path (relative to workspace root) | | `--path <path>` | Target by exact file path | Example: ```bash foam note move my-note --to archive/my-note.md # Moved: notes/my-note.md → archive/my-note.md (id: my-note, 3 links updated) ``` ### delete Delete a note. ```bash foam note delete (<identifier> | --path <path>) [--force] [--permanent] ``` By default, deleted notes are moved to `.foam/trash/` rather than permanently removed. You will be prompted to confirm unless `--force` is passed. | Option | Description | | --------------- | --------------------------------------------- | | `--force` | Skip confirmation prompt | | `--permanent` | Delete permanently instead of moving to trash | | `--path <path>` | Target by exact file path | Example: ```bash foam note delete old-draft # Delete notes/old-draft.md? [y/N] y # Trashed: notes/old-draft.md → .foam/trash/notes/old-draft.md ``` ## Global options | Option | Description | | ------------------- | -------------------------------------------------------------------------- | | `--workspace <dir>` | Workspace root (default: `FOAM_WORKSPACE` env var, then current directory) | | `--format <fmt>` | Output format: `text` (default) or `json` | [templates]: ../../features/templates.md 'Note Templates' --- ### User Tools Cli Outline (`docs/user/tools/cli/outline.md`) # foam outline Show the heading structure of a note. ``` foam outline (<identifier> | --path <path>) [options] ``` Prints the headings in a note in order, indented to reflect their level. Useful for getting a quick overview of a long note's structure. ## Options | Option | Description | | ------------------- | -------------------------------------------------------------------------- | | `--path <path>` | Target note by exact file path instead of identifier | | `--workspace <dir>` | Workspace root (default: `FOAM_WORKSPACE` env var, then current directory) | | `--format <fmt>` | Output format: `text` (default) or `json` | ## Examples Show the outline of a note: ```bash foam outline my-note # Introduction ## Background ## Goals # Implementation ## Phase 1 ## Phase 2 # Conclusion ``` Get the outline as JSON (includes line numbers): ```bash foam outline my-note --format json ``` Target by file path: ```bash foam outline --path notes/my-note.md ``` --- ### User Tools Cli Rename (`docs/user/tools/cli/rename.md`) # foam rename Rename notes, tags, sections, or block anchors — with automatic link rewriting. ``` foam rename <subcommand> [options] ``` All subcommands update every wikilink that references the renamed item across the whole workspace. ## Subcommands ### note Rename a note file and rewrite all wikilinks pointing to it. ```bash foam rename note (<identifier> | --path <path>) <new-name> ``` | Option | Description | | ---------------------- | -------------------------------------- | | `--target-path <path>` | Move the file to a different directory | | `--path <path>` | Target by exact file path | Example: ```bash foam rename note old-name new-name # Renamed: notes/old-name.md → notes/new-name.md (id: new-name, 4 links updated) ``` Move to a different directory at the same time: ```bash foam rename note my-note my-note --target-path archive/ ``` ### tag Rename a tag and all its hierarchical children across the workspace. ```bash foam rename tag <old-tag> <new-tag> ``` | Option | Description | | --------- | ------------------------------------------------------------- | | `--force` | Skip confirmation if the rename would merge two existing tags | Example: ```bash foam rename tag project/active project/in-progress # Renamed: #project/active → #project/in-progress (3 notes updated) ``` ### section Rename a heading section in a note and rewrite all `[[note#Section]]` links pointing to it. ```bash foam rename section (<identifier> | --path <path>) <old-label> <new-label> ``` | Option | Description | | --------------- | ------------------------- | | `--path <path>` | Target by exact file path | Example: ```bash foam rename section my-note "Background" "Context" # Renamed section "Background" → "Context" in notes/my-note.md (2 links updated) ``` ### block Rename a block anchor in a note and rewrite all `[[note#^id]]` links pointing to it. ```bash foam rename block (<identifier> | --path <path>) <old-id> <new-id> ``` | Option | Description | | --------------- | ------------------------- | | `--path <path>` | Target by exact file path | Example: ```bash foam rename block my-note key-insight better-insight # Renamed block ^key-insight → ^better-insight in notes/my-note.md (1 link updated) ``` ## Global options | Option | Description | | ------------------- | -------------------------------------------------------------------------- | | `--workspace <dir>` | Workspace root (default: `FOAM_WORKSPACE` env var, then current directory) | | `--format <fmt>` | Output format: `text` (default) or `json` | See also [[wikilinks]] for how wikilinks work, and [[block-anchors]] for block anchor syntax. [wikilinks]: ../../features/wikilinks.md 'Wikilinks' [block-anchors]: ../../features/block-anchors.md 'Block Anchors' --- ### User Tools Cli Search (`docs/user/tools/cli/search.md`) # foam search Search notes by title, alias, tag, or frontmatter property. ``` foam search [<query>] [options] ``` Searches the workspace index. The optional `<query>` is matched against note titles and aliases (substring, case-insensitive). Combine it with `--tag` and `--property` filters to narrow results. For full-text content search, use [[cli-grep|foam grep]] instead. ## Options | Option | Description | | ---------------------- | ------------------------------------------------------------------------------ | | `<query>` | Substring to match against note titles and aliases | | `--tag <tag>` | Filter by tag (repeat for AND logic) | | `--property <key=val>` | Filter by frontmatter property; omit `=val` to match any note that has the key | | `--type <type>` | Filter by resource type: `note` (any markdown file), `attachment`, `image` | | `--limit <n>` | Maximum number of results (default: 20) | | `--workspace <dir>` | Workspace root (default: `FOAM_WORKSPACE` env var, then current directory) | | `--format <fmt>` | Output format: `text` (default) or `json` | ## Examples Search by title: ```bash foam search "meeting" # notes/team-meeting.md:1: # Team Meeting Notes # notes/one-on-one-meeting.md:1: # One-on-One Meeting ``` Filter by tag: ```bash foam search --tag project ``` Combine a title query with a tag filter: ```bash foam search "alpha" --tag active ``` Find all notes with a specific frontmatter property: ```bash foam search --property status=draft ``` Find all notes that have a `due` property (any value): ```bash foam search --property due ``` List only daily notes (matches the `type` set in the note's frontmatter): ```bash foam search --property type=daily-note ``` --- ### User Tools Cli Tag (`docs/user/tools/cli/tag.md`) # foam tag List, rename, or search tags. ``` foam tag <subcommand> [options] ``` ## Subcommands ### list List all tags in the workspace. ```bash foam tag list [options] ``` This is an alias for `foam list tags`. Accepts the same filtering and sorting options. | Option | Description | | ---------------------- | ---------------------------- | | `--prefix <str>` | Filter by tag prefix | | `--sort <count\|name>` | Sort order (default: `name`) | | `--limit <n>` | Maximum number of results | Example: ```bash foam tag list # #daily (12 notes) # #project (8 notes) # #project/active (3 notes) ``` ### rename Rename a tag across the entire workspace, including its hierarchical children. ```bash foam tag rename <old> <new> ``` | Option | Description | | --------- | ------------------------------------------------------------- | | `--force` | Skip confirmation if the rename would merge two existing tags | Example: ```bash foam tag rename todo in-progress # Renamed: #todo → #in-progress (5 notes updated) ``` Renaming a parent tag also renames its children. Renaming `project` to `work` will also rename `project/active` to `work/active`. ### search Find all notes with a given tag. ```bash foam tag search <tag> ``` This is an alias for `foam search --tag <tag>`. Example: ```bash foam tag search project # notes/alpha.md:1: # Project Alpha # notes/beta.md:1: # Project Beta ``` ## Global options | Option | Description | | ------------------- | -------------------------------------------------------------------------- | | `--workspace <dir>` | Workspace root (default: `FOAM_WORKSPACE` env var, then current directory) | | `--format <fmt>` | Output format: `text` (default) or `json` | See also [[tags]] for tag management in VS Code. [tags]: ../../features/tags.md 'Tags' --- ### User Tools Cli Update (`docs/user/tools/cli/update.md`) # foam update Check whether a newer version of `foam-cli` is available. ``` foam update ``` The command compares your installed version against the latest release on npm and prints the install command if a newer version exists. It does not install anything for you. If the npm registry can't be reached, the command falls back to printing the install command without a version comparison. ## Options | Option | Description | | -------- | -------------- | | `--help` | Show this help | ## Examples Check for updates: ```bash foam update # Current version: 0.41.0 # Latest version: 0.42.0 # # To update, run: # npm install foam-cli@latest ``` When already up to date: ```bash foam update # Current version: 0.42.0 # You are already on the latest version. ``` --- --- METRICS --- - Files Extracted: 88 - Estimated Token Budget: ~94383 tokens - Canonical Reference: https://codewiki.google/github.com/foambubble/foam

# Technical Documentation: foambubble/foam > ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/foambubble/foam) ### Index (`docs/index.md`) # What is Foam? 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. ## 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._

New! Join Foam community Discord for users and contributors!

Star Use this template

## Table of Contents - [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) - [Contributing](#contributing) - [Thanks and attribution](#thanks-and-attribution) - [License](#license) ## How do I use Foam? Foam helps you create relationships between thoughts and information through: 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 Success with Foam depends on consistent note-taking and linking habits. ## What's in a Foam? Foam combines existing tools: 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 > This documentation was created using Foam. ## Getting started **Requirements:** GitHub account and Visual Studio Code 1. **Create repository** - Use the [foam-template](https://github.com/foambubble/foam-template) to generate a new repository 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 **Next steps:** - 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 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 Explore [[recipes]] for usage patterns and workflows. ## Contributing Foam is an evolving project and we welcome contributions: - 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

_{Jani Eväkallio} 💻 📖	_{Joe Previte} 💻 📖	_Riccardo 💻 📖	_{Janne Ojanaho} 💻 📖	_{Paul Shen} 📖	_coffenbacher 📖	_{Mathieu Dutour} 📖
_{Michael Hansen} 📖	_{David Nadlinger} 📖	_Fernando 📖	_{Juan Gonzalez} 📖	_{Louie Christie} 📖	_Sandro 📖	_{Simon Knott} 📖
_Steven 📖	_Tim 📖	_{Saurav Khdoolia} 📖	_{Ankit Tiwari} 📖 ⚠️ 💻	_{Ayush Baweja} 📖	_TaiChi-IO 📖	_{Juan F Gonzalez} 📖
_{Sanket Dasgupta} 📖 💻	_{Nicholas Stafie} 📖	_{Francis Hamel} 💻	_digiguru 💻 📖	_{CHIRAG SINGHAL} 💻	_{Jonathan Carter} 📖	_{Julian Elve} 📖
_{Thomas Koppelaar} 💬 💻 📓	_Akshay 💻	_{John Lindquist} 📖	_{Ashwin Ramaswami} 📖	_{Claudio Canales} 📖	_{vitaly-pevgonen} 📖	_{Dmitry Shemetov} 📖
_hooncp 📖	_{Martin Laws} 📖	_{Sean K Smith} 💻	_{Kevin Neely} 📖	_{Arief Rahmansyah} 📖	_{Vishesh Handa} 📖	_{Hitesh Kumar} 📖
_{Spencer Woo} 📖	_ingalless 💻 📖	_{José Duarte} 💻 📖	_Yenly 📖	_hikerpig 💻	_{Sigfried Gold} 📖	_{Tristan Sokol} 💻
_{Danil Rodin} 📖	_{Scott Williams} 📖	_jackiexiao 📖	_{John B Nelson} 📖	_{Asif Mehedi} 📖	_{Tan Li} 💻	_{Shauna Gordon} 📖
_{Mike Cluck} 💻	_{Brandon Pugh} 💻	_{Max Davitt} 📖	_{Brian Anglin} 📖	_elswork 📖	_{léon h} 💻	_{Nikhil Nygaard} 📖
_{Mark Dixon} 💻	_{Joel James} 💻	_{Hashiguchi Ryo} 📖	_{Michael Overmeyer} 💻	_{Derrick Qin} 📖	_{Omar López} 📖	_{Robin King} 💻
_Dheepak 📖	_{Daniel VG} 📖	_Barabas 💻	_{Engincan VESKE} 📖	_{Paul de Raaij} 💻	_{Scott Bronson} 📖	_{Rafael Riedel} 📖
_Pearcekieser 📖	_{Owen Young} 📖 🖋	_{Prashanth Subrahmanyam} 📖	_{Jonas SPRENGER} 💻	_Paul 📖	_{Ikko Ashimine} 📖	_memeplex 💻
_AndreiD049 💻	_Yan 📖	_{Jim Tittsler} 📖	_{Malcolm Mielle} 📖	_Veesar 📖	_bentongxyz 💻	_{Brian DeVries} 💻
_{Clifford Fajardo} 🔧	_{Chris Usick} 💻	_{Joe DeCock} 💻	_{Drew Tyler} 📖	_Lauviah0622 💻	_{Josh Dover} 💻	_{Phil Helm} 📖
_{Larry Li} 💻	_{Joe Taber} 📖	_{Woosuk Park} 📖	_{Daniel Murphy} 💻	_{Dominic D} 💻	_luca 📖	_{Lloyd Jackman} 📖
_{sn3akiwhizper} 📖	_{jonathan berger} 📖	_{Daniel Wang} 💻	_{Liu YongLiang} 📖	_{Scott Akerman} 💻	_{Jim Graham} 💻	_{Zhizhen He} 🔧
_{Tony Cheneau} 📖	_{Nicholas Latham} 💻	_{Tomochika Hara} 📖	_{Daniel Carosone} 📖	_{Miguel Angel Bruni Montero} 💻	_{Kevin Walsh} 📖	_{Xinglan Liu} 💻
_{Thomas Hegghammer} 📖	_{Piotr Mrzygłosz} 📖	_{Mark Schaver} 📖	_{Nathan Layman} 💻	_{Emmanuel Ferdman} 📖	_Tenormis 💻	_{David Jones} 📖
_{S. Jacob Powell} 💻	_{Davi Figueiredo} 📖	_{CT Hall} 💻	_meestahp 💻	_qwloh 📖	_{Ryan N} 💻	_{Nils Henrik Hals} 💻
_{Florian Meyer} 💻	_Sherlock290 💻

Foam was inspired by [Zettelkasten methodology](https://zettelkasten.de/posts/overview). 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). [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' --- ### User Index (`docs/user/index.md`) # Using Foam 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 - **Block anchors** - Link or embed specific paragraphs, list items, and headings with `[[note#^id]]` - **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]] - [[first-workspace]] - [[note-taking-in-foam]] - [[sync-notes]] - [[keyboard-shortcuts]] - [[search-and-navigate-notes]] Coming from Obsidian? See [[migrating-from-obsidian]]. ## Features - [[wikilinks]] - [[footnotes]] - [[block-anchors]] - [[embeds]] - [[foam-queries]] - [[smart-folders]] - [[tags]] - [[backlinking]] - [[daily-notes]] - [[spell-checking]] - [[graph-view]] - [[note-properties]] - [[templates]] - [[paste-images-from-clipboard]] - [[custom-markdown-preview-styles]] - [[link-reference-definitions]] - [[custom-snippets]] ## Recipes [[recipes]] is a collection of user-contributed patterns that describe different ways you could utilize Foam or integrate it with other tools. ## Publishing You can publish your Foam notes for consumption in different formats. Examples: [[publish-to-github-pages]], [[generate-gatsby-site]], [[publish-to-vercel]] See [[publishing]] for more details. ## Tools - [[cli]] — work with your workspace from the terminal (`search`, `list`, `daily`, `lint`, and more) - [[workspace-lint]] - [[orphans]] - [[foam-logging-in-vscode]] - [[telemetry]] [frequently-asked-questions]: frequently-asked-questions.md 'Frequently Asked Questions' [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' [first-workspace]: getting-started/first-workspace.md 'Creating Your First Workspace' [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' [search-and-navigate-notes]: recipes/search-and-navigate-notes.md 'Search and Navigate Notes' [migrating-from-obsidian]: recipes/migrating-from-obsidian.md 'Coming from Obsidian' [wikilinks]: features/wikilinks.md 'Wikilinks' [footnotes]: features/footnotes.md 'Footnotes' [block-anchors]: features/block-anchors.md 'Block Anchors' [embeds]: features/embeds.md 'Note Embeds' [foam-queries]: features/foam-queries.md 'Foam Queries' [smart-folders]: features/smart-folders.md 'Smart Folders' [tags]: features/tags.md 'Tags' [backlinking]: features/backlinking.md 'Backlinks' [daily-notes]: features/daily-notes.md 'Daily Notes' [spell-checking]: features/spell-checking.md 'Spell Checking' [graph-view]: features/graph-view.md 'Graph Visualization' [note-properties]: features/note-properties.md 'Note Properties' [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' [custom-snippets]: features/custom-snippets.md 'Adding Custom Snippets' [recipes]: recipes/recipes.md 'Recipes' [publish-to-github-pages]: publishing/publish-to-github-pages.md 'GitHub Pages' [generate-gatsby-site]: publishing/generate-gatsby-site.md 'Generate a site using Gatsby' [publish-to-vercel]: publishing/publish-to-vercel.md 'Publish to Vercel' [publishing]: publishing/publish-to-github-pages.md 'Publishing' [cli]: tools/cli.md 'Command Line Interface' [workspace-lint]: tools/workspace-lint.md 'Lint' [orphans]: tools/orphans.md 'Orphaned Notes' [foam-logging-in-vscode]: tools/foam-logging-in-vscode.md 'Foam logging in VsCode' [telemetry]: tools/telemetry.md 'Telemetry' --- ### Inbox (`docs/inbox.md`) # Inbox Uncategorised thoughts, to be added - Release notes - Markdown Preview - It's possible to customise the markdown preview styling. **Maybe make it use local foam workspace styles for live preview of the site??** - See: - Use VS Code [CodeTour](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour) for onboarding - Investigate other similar extensions: - [Unotes](https://marketplace.visualstudio.com/items?itemName=ryanmcalister.Unotes) - [vscode-memo](https://github.com/svsool/vscode-memo) - Open in Foam - When you want to open a Foam published website in your own VS Code, we could have a "Open in Foam" link that opens the link in VS Code via a url binding (if possible), downloads the github repo locally, and opens it as a Foam workspace. - Every Foam could have a different theme even in the editor, so you'll see it like they see it - UI and layout design of your workspace can become a thing - VS Code Notebooks API - - Future architecture - Could we do publish-related settings as a pre-push git hook, e.g. generating footnote labels - Running them on GitHub Actions to edit stuff as it comes in - Ideally, we shouldn't have to touch files, should be just markdown - Looking at the errors/warnings/output panes makes me think, what kind of automated quality tools could we write. - Deduplication, finding similarities... - Thought Debugger? - Knowledge Debugger? - Janitor? Gardener? - Foam Compiler? - Should support Netlify deploys out of the box - Foam should tick at the same frequency as your brain, and the Foam graph you build should match the mental model you have in your head, making navigation effortless. - Maps have persistent topologies. As the graph grows, you should be able to visualise where an idea belongs. Maybe a literal map? And island? A DeckGL visualization? Testing: This file is served from the /docs directory. --- ### Principles (`docs/principles.md`) # Principles ## Table of Contents - [Principles](#principles) - [Table of Contents](#table-of-contents) - [Foam enables you to do your best thinking](#foam-enables-you-to-do-your-best-thinking) - [Foam wants you to own your thoughts](#foam-wants-you-to-own-your-thoughts) - [Foam helps you share your thoughts with the world.](#foam-helps-you-share-your-thoughts-with-the-world) - [Foam allows people to collaborate in discovering better ways to work, together.](#foam-allows-people-to-collaborate-in-discovering-better-ways-to-work-together) - [Foam is for hackers, not only for programmers](#foam-is-for-hackers-not-only-for-programmers) ## Foam enables you to do your best thinking - **Foam works for you, you don't work for Foam.** You should be able to focus on your work and not fight against Foam, or having to perform fiddly operations or maintenance jobs to keep Foam happy. - **Foam is not a package deal.** You must be able to adopt only the parts of Foam that you want. There must be no tight coupling between Foam's features. - **Foam is a starting point** You must be able to customise how foam looks and feels, and combine it with other tools you find helpful in your personal workflow. - **Foam is not a philosophy.** Whether you use a methodology like Zettelkasten is up to you. **You should be able to use Foam without joining a cult.** ## Foam wants you to own your thoughts - **Foam doesn't want your data.** You can store your documents wherever you want. Some of Foam's suggested workflows include GitHub, if you don't want to use it to store your data, or you want to stop using it in the future, you should be able to migrate to alternative storage options. If you choose to not upload your notes to any cloud service or remote repository, remember to keep frequent local and occasional offsite backups of your data! - **Foam should not lock you in.** Foam's content files, structure and metadata should be in interoperable format that supports migrating it to another tool if you prefer to. Users of Foam should be able to develop and share such tools freely. - **Foam should not leak your secrets.** Nobody, including the developers of Foam, should have access to your personal knowledge graph unless you choose to give it to them. Foams should always be private by default, but [easy to share](#foam-helps-you-share-your-thoughts-with-the-world) if you choose to. ## Foam helps you share your thoughts with the world. This principle may seem like it contradicts [Foam wants you to own your thoughts](#foam-wants-you-to-own-your-thoughts), but it's actually a compatible corollary. You should be able to do both, because: > [...] environments that build walls around good ideas tend to be less innovative in the long run than more open-ended environments. Good ideas may not want to be free, but they do want to connect, fuse, recombine. —_Steven Johnson, Where Good Ideas Come From_ - **Foam should make it easy to publish your knowledge graph.** With zero code, you should be able to make your graph public to the world. You should have full control over how it looks, feels, and where it's hosted. - **Foam should make it easy to collaborate on ideas.** Foam should allow you to work closely together with your collaborators, and accept feedback, input and improvements from others. - **Foam should make it easy to publish what you choose.** Foam should double as a low-barrier blog/publishing platform, so you can share content to an audience without inviting them to intrude on your entire workspace. ## Foam allows people to collaborate in discovering better ways to work, together. - **Foam is a collection of ideas.** Foam was released to the public not to share the few good ideas in it, but to learn many good ideas from others. As you improve your own workflow, share your work on your own Foam blog. - **Foam is open for contributions.** If you use a tool or workflow that you like that fits these principles, please contribute them back to the Foam template as [[recipes]], [[recommended-extensions]] or documentation in [this workspace](https://github.com/foambubble/foam). See also: [[contribution-guide]]. - **Foam is open source.** Feel free to fork it, improve it and remix it under the terms of our [MIT license](LICENSE.txt). - **No idea is too big.** If it doesn't fit with Foam's core workflow, we might make it a [[recipes]] page instead. ## Foam is for hackers, not only for programmers While Foam uses tools popular among computer programmers, Foam should be inclusive of everyone who wants to improve their own workflow to improve themselves. - **Foam embraces the hacker mindset.** The target audience for Foam are people who look for creative ways to improve their ability to collect and organise information. - **Foam is not just for programmers.** If you're a programmer, feel free to write scripts and extensions to support your own workflow, and publish them for others to use, but the out of the box Foam experience should not require you to know how to do so. You should, however, be curious and open to adopting new tools that are unfamiliar to you, and evaluate whether they could work for you. - **Foam is for everyone** As a foam user, you support everyone's quest for knowledge and self-improvement, not only your own, or folks' who look like you. All participants in Foam repositories, discussion forums, physical and virtual meeting spaces etc are expected to respect each other as described in our [[code-of-conduct]]. **Foam is not for toxic tech bros.** [recipes]: user/recipes/recipes.md "Recipes" [recommended-extensions]: user/getting-started/recommended-extensions.md "Recommended Extensions" [contribution-guide]: dev/contribution-guide.md "Contribution Guide" [code-of-conduct]: dev/code-of-conduct.md "Code of Conduct" --- ### Dev Code Of Conduct (`docs/dev/code-of-conduct.md`) --- redirect_from: - /code-of-conduct --- # Code of Conduct We follow the [Contributor Covenant](https://www.contributor-covenant.org/) code of conduct. ## Our Pledge We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. ## Our Standards Examples of behavior that contributes to a positive environment for our community include: - Demonstrating empathy and kindness toward other people - Being respectful of differing opinions, viewpoints, and experiences - Giving and gracefully accepting constructive feedback - Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience - Focusing on what is best not just for us as individuals, but for the overall community Examples of unacceptable behavior include: - The use of sexualized language or imagery, and sexual attention or advances of any kind - Trolling, insulting or derogatory comments, and personal or political attacks - Public or private harassment - Publishing others' private information, such as a physical or email address, without their explicit permission - Other conduct which could reasonably be considered inappropriate in a professional setting ## Enforcement Responsibilities Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful. Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate. ## Scope This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. ## Enforcement Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at `riki.code+foam@gmail.com`. All complaints will be reviewed and investigated promptly and fairly. All community leaders are obligated to respect the privacy and security of the reporter of any incident. ## Enforcement Guidelines Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct: ### 1. Correction **Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community. **Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested. ### 2. Warning **Community Impact**: A violation through a single incident or series of actions. **Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. ### 3. Temporary Ban **Community Impact**: A serious violation of community standards, including sustained inappropriate behavior. **Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. ### 4. Permanent Ban **Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals. **Consequence**: A permanent ban from any sort of public interaction within the community. ## Attribution This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0, available at . Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity). [homepage]: https://www.contributor-covenant.org For answers to common questions about this code of conduct, see the FAQ at . Translations are available at . --- ### Dev Contribution Guide (`docs/dev/contribution-guide.md`) # Contribution Guide The contribution guide has moved to [CONTRIBUTING.md](../../CONTRIBUTING.md) at the repository root. --- ### Dev Devcontainers (`docs/dev/devcontainers.md`) # Using Dev Containers Foam provides a [devcontainer](https://devcontainer.ai/) configuration to make it easy to contribute without installing Node and Yarn locally. ## Quick start 1. Install [VS Code](https://code.visualstudio.com/) and the [Dev Containers](https://aka.ms/vscode-remote/download/extension) extension. 2. Open the Foam repository in VS Code. 3. Run **Dev Containers: Reopen in Container** from the command palette. This will build a Docker image with Node 18 and install dependencies using `yarn install`. Once ready you can run the usual build and test commands from the integrated terminal. --- ### Dev Releasing Foam (`docs/dev/releasing-foam.md`) # Releasing Foam Foam uses [Changesets](https://github.com/changesets/changesets) to manage versions and changelogs across the monorepo (`foam-vscode`, `@foam/cli`, `@foam/core`). Changesets owns the arithmetic — which package gets which bump, and assembling `CHANGELOG.md`. Deciding _what_ to write is covered by the [changelog rules](#changelog-rules) below. ## Writing changesets Fragments are written at release time, reconstructed from the history on `main` since the last release: see [Generating fragments from git history](#generating-fragments-from-git-history). Changes don't carry them, so a pull request leaves `.changeset/` alone. ### ⚠️ Changes to `@foam/core` must also bump its dependents `foam-vscode` and `@foam/cli` both **bundle** `@foam/core` at build time (esbuild inlines it), and both declare it as a `devDependency` — not a runtime `dependency`. Because of that, Changesets' automatic internal-dependency bumping (`updateInternalDependencies`) does **not** cascade a `@foam/core` bump to them. It won't add the fragments for you. So whenever a change touches `packages/foam-core`, the changeset must **also** include `foam-vscode` and `@foam/cli` (each usually `patch`), so their republished bundles ship with a correct version and a changelog entry. If you only bump `@foam/core`, the extension and CLI will silently publish updated code under a stale version number. Rule of thumb: **if `@foam/core` is in the fragment, `foam-vscode` and `@foam/cli` almost always belong there too** — unless the core change is genuinely internal-only and reaches neither the extension nor the CLI. ## Changelog rules ### Does the change need a fragment? Yes, if it changes behavior that users of a published package can observe: `foam-vscode`, `@foam/cli`, `@foam/core`. (`@foam/graph-view`, `@foam/mcp` and `@foam/agent-loop` are listed under `ignore` in `.changeset/config.json` and never get fragments.) No, for: - documentation, `CLAUDE.md`, `.agent/` specs - test-only commits — the change they cover carries the fragment - refactors with no user-visible effect and no public API change - build and tooling changes that don't alter what ships ### Which bump? Foam is pre-1.0, so these are conventions rather than strict semver: | Bump | `@foam/core` | `foam-vscode` / `@foam/cli` | | ------- | ------------------------------------------------------------------------------ | ------------------------------------------------------- | | `major` | reserved — decide deliberately | reserved — decide deliberately | | `minor` | new or changed public API surface (new export, new subpath, changed signature) | new user-facing feature | | `patch` | bug fix, security fix, internal change that still ships | bug fix, security fix, manifest or user-facing copy fix | When several commits fold into one fragment, use the highest bump any of them warrants. ### Writing the entry The entry is read by users, not by developers. Make it as short as it can be while still telling them what changed: usually one line, rarely more than two sentences. - Say what changed, not why it was broken or how it was fixed. Causes, mechanisms and internal names belong in the commit message. - If behavior narrowed, say so, and say what to do instead. - Name a changed API only in a `@foam/core` entry, and only name it. - Several related fixes can share one entry as a list, one line per item. - Reference the issue number when there is one, as `(#1215)`. - Don't reuse the commit subject verbatim — commit subjects are written for developers. For example: ```markdown Notes in folders listed in `files.watcherExclude` are no longer left out of the workspace. To exclude a folder, use `foam.files.exclude`. ``` not a paragraph on what `files.watcherExclude` is for, why honouring it saved no CPU, and how the CLI differed. ## Generating fragments from git history At release time, for anything that shipped without a fragment: 1. List what landed since the last release (tags are `vscode@`, `cli@`, `core@`): ``` git log vscode@..HEAD --oneline ``` 2. Group the commits into coherent user-facing changes. Several commits (a fix, its tests, a docs touch-up) usually become one fragment; occasionally one commit becomes two. 3. For each group apply the rules above: does it need a fragment, which packages, which bump, and what does the user need to know. 4. Apply the core cascade rule to every fragment that names `@foam/core`. 5. Write each one as `.changeset/.md`: ```markdown --- 'foam-vscode': patch --- The entry text. ``` The `/update-changelog` slash command can draft these for commits already on `main`. Fragments don't need to be committed before `yarn version-packages` runs — it reads them off disk. Committing them first is still worthwhile if you want the intent recorded independently of the generated changelog. Nothing in CI enforces any of this; it's a review-time and release-time responsibility. ## Cutting a release 1. Get to the latest code - `git checkout main && git fetch && git rebase` 2. Sanity checks - `yarn reset` - `yarn test` 3. Make sure every shipped change since the last release has a fragment in `.changeset/` - If not, write the missing ones — see [Generating fragments from git history](#generating-fragments-from-git-history) - **If any change touched `@foam/core`, confirm `foam-vscode` and `@foam/cli` are also covered by a fragment** (see the warning above). Their bundles pick up core changes at build time, but Changesets will not bump their versions automatically. 4. Apply the fragments — bumps versions in each affected `package.json`, regenerates `CHANGELOG.md`, and deletes the consumed fragments - `yarn version-packages` 5. Review and commit the result - Inspect the generated `CHANGELOG.md` and version bumps - Update `./packages/foam-vscode/WHATS_NEW.md` if the release has something users should act on or learn to use. It is shown on update when its _content hash_ changes, so leaving it untouched shows nothing — appropriate for a release with no new features. - `git add -A && git commit -m "Release"` - `yarn tag-release` - Create per-package tags (`vscode@`, `cli@`, `core@`): - The script reads each package's current version from `package.json` and skips any tag that already exists. 6. Publish - `yarn release` to release them all, otherwise - `yarn release-extension` (packages and publishes to VS Marketplace and OpenVSX) - `yarn release-cli` (packages and publishes `@foam/cli` to npm as `foam-cli`) - `yarn release-core` (publishes `@foam/core` to npm) 7. Push - `git push && git push --tags` 8. Update the release notes in GitHub - In GitHub, top right, click on "releases" - Select "tags" in top left - Select the tag that was just released, click "edit" and copy release information from `CHANGELOG.md` - Publish (no need to attach artifacts) 9. Announce on Discord Steps 1 to 8 should really be replaced by a GitHub action... --- ### Dev Testing Conventions (`docs/dev/testing-conventions.md`) # Testing in Foam VS Code Extension This document explains the testing strategy and conventions used in the Foam VS Code extension. ## Test File Types We use two distinct types of test files, each serving different purposes: ### `.test.ts` Files - Pure Unit Tests - **Purpose**: Test business logic and algorithms in complete isolation - **Dependencies**: No VS Code APIs dependencies - **Environment**: Vitest with Node.js - **Speed**: Very fast execution - **Location**: Throughout the codebase alongside source files ### `.spec.ts` Files - Integration Tests with VS Code APIs - **Purpose**: Test features that integrate with VS Code APIs and user workflows - **Dependencies**: Will likely depend on VS Code APIs (`vscode` module), otherwise avoid incurring the performance hit - **Environment**: Can run in TWO environments: - **Mock Environment**: Vitest with VS Code API mocks (fast) - **Real VS Code**: Full VS Code extension host (slow but comprehensive) - **Speed**: Depends on environment (see performance section below) - **Location**: Primarily in `src/vscode/features/` and service layers ## Key Principle: Environment Flexibility for `.spec.ts` Files **`.spec.ts` files use VS Code APIs**, but they can run in different environments: - **Mock Environment**: Uses our VS Code API mocks for speed - **Real VS Code**: Uses actual VS Code extension host for full integration testing This dual-environment capability allows us to: - Run specs quickly during development (mock environment) - Verify full integration during CI/CD (real VS Code environment) - Gradually migrate specs to mock-compatible implementations ## Performance Comparison | Test Type | Environment | Typical Duration | VS Code APIs | | --------------------- | ---------------------- | ---------------- | ---------------- | | **`.test.ts`** | Vitest (Node.js) | fastest | **No** | | **`.spec.ts` (mock)** | Vitest + VS Code Mocks | fast | **Yes** (mocked) | | **`.spec.ts` (real)** | VS Code Extension Host | sloooooow. | **Yes** (real) | ## Running Tests ### Available Commands - **`yarn test:unit`**: Runs `.test.ts` files (no VS Code dependencies) + `@unit-ready` marked `.spec.ts` files using mocks - **`yarn test:unit-without-specs`**: Runs only `.test.ts` files - **`yarn test:e2e`**: Runs all `.spec.ts` files in full VS Code extension host - **`yarn test`**: Runs both unit and e2e test suites sequentially ## Mock Environment Migration We're gradually enabling `.spec.ts` files to run in our fast mock environment while maintaining their ability to run in real VS Code. ### The `@unit-ready` Annotation Spec files marked with `/* @unit-ready */` can run in both environments: ```typescript /* @unit-ready */ import * as vscode from 'vscode'; // ... test uses VS Code APIs but works with our mocks ``` ### Common Migration Fixes **Configuration defaults**: Our mocks don't load package.json defaults ```typescript // Before const format = getFoamVsCodeConfig('openDailyNote.filenameFormat'); // After (defensive) const format = getFoamVsCodeConfig( 'openDailyNote.filenameFormat', 'yyyy-mm-dd' ); ``` **File system operations**: Ensure proper async handling ```typescript // Mock file operations are immediate but still async await vscode.workspace.fs.writeFile(uri, content); ``` ### When NOT to Migrate Some specs should remain real-VS-Code-only: - Tests verifying complex VS Code UI interactions - Tests requiring real file system watching with timing - Tests validating extension packaging or activation - Tests that depend on VS Code's complex internal state management ## Mock System Capabilities Our `vscode-mock.ts` provides comprehensive VS Code API mocking: ## Contributing Guidelines When adding new tests: 1. **Choose the right type**: - Use `.test.ts` for pure business logic with no VS Code dependencies - Use `.spec.ts` for anything that needs VS Code APIs 2. **Consider mock compatibility**: - When writing `.spec.ts` files, consider if they could run in mock environment - Add `/* @unit-ready */` if the test works with our mocks 3. **Follow naming conventions**: - Test files should be co-located with source files when possible - Use descriptive test names that explain the expected behavior 4. **Performance awareness**: - Prefer unit tests for business logic (fastest) - Use mock-compatible specs for VS Code integration (fast) - Reserve real VS Code specs for complex integration scenarios (comprehensive) This testing strategy gives us the best of both worlds: fast feedback during development and comprehensive integration verification when needed. ## Graph Webview (`@foam/graph-view`) The webview component has its own test stack, separate from the extension tests. - **Framework**: [Vitest](https://vitest.dev/) with [happy-dom](https://github.com/capricorn86/happy-dom) for a browser-like environment - **Location**: Test files live in `packages/foam-graph/src/` - **Command**: `yarn workspace @foam/graph-view test` The webview tests focus on the framework-agnostic library code in `src/lib/` (graph utilities, color logic, painter). Lit component rendering tests can be added as the component grows. --- ### User Frequently Asked Questions (`docs/user/frequently-asked-questions.md`) # Frequently Asked Questions - [Frequently Asked Questions](#frequently-asked-questions) - [Links/Graphs/BackLinks don't work. How do I enable them?](#linksgraphsbacklinks-dont-work-how-do-i-enable-them) - [I don't want Foam enabled for all my workspaces](#i-dont-want-foam-enabled-for-all-my-workspaces) - [I want to publish the graph view to GitHub pages or Vercel](#i-want-to-publish-the-graph-view-to-github-pages-or-vercel) - [Does Foam collect any data?](#does-foam-collect-any-data) ## Links/Graphs/BackLinks don't work. How do I enable them? - Ensure that you have all the [[recommended-extensions]] installed in Visual Studio Code - Reload Visual Studio Code by running `Cmd` + `Shift` + `P` (`Ctrl` + `Shift` + `P` for Windows), type "reload" and run the **Developer: Reload Window** command to for the updated extensions take effect - Check the formatting rules for links on [[wikilinks]] ## I don't want Foam enabled for all my workspaces Any extension you install in Visual Studio Code is enabled by default. Given the philosophy of Foam, it works out of the box without doing any configuration upfront. In case you want to disable Foam for a specific workspace, or disable Foam by default and enable it for specific workspaces, it is advised to follow the best practices as [documented by Visual Studio Code](https://code.visualstudio.com/docs/editor/extension-marketplace#_manage-extensions) ## I want to publish the graph view to GitHub pages or Vercel If you want a different front-end look to your published foam and a way to see your graph view, we'd recommend checking out these templates: - [foam-gatsby](https://github.com/mathieudutour/foam-gatsby-template) by [Mathieu Dutour](https://github.com/mathieudutour) - [foam-gatsby-kb](https://github.com/hikerpig/foam-template-gatsby-kb) by [hikerpig](https://github.com/hikerpig) ## Does Foam collect any data? Foam collects anonymous usage data (which commands are used, which features are configured) to help prioritize development. No note content, file names, or personal information is ever collected. Foam follows VS Code's global telemetry setting (`telemetry.telemetryLevel`). If you have disabled telemetry in VS Code, Foam will not send any data. To inspect what is being sent, set the Foam log level to `Debug` (run `Foam: Set log level` from the command palette) — telemetry events will appear in the Foam output channel. See [[foam-logging-in-vscode]] for details. See [[telemetry]] for the full list of collected data and opt-out instructions. [recommended-extensions]: getting-started/recommended-extensions.md 'Recommended Extensions' [wikilinks]: features/wikilinks.md 'Wikilinks' [telemetry]: tools/telemetry.md 'Telemetry' [foam-logging-in-vscode]: tools/foam-logging-in-vscode.md 'Foam logging in VsCode' --- ### Dev Design Core Model And Api Review (`docs/dev/design/core-model-and-api-review.md`) # Core Model & API Review — Improvement Spec - **Date:** 2026-08-09 - **Scope:** `@foam/core` information model and services, package/API architecture, and the seams to `foam-vscode`, `@foam/cli`, and `@foam/mcp`. Performance items are included where they fall out of the model review. - **Method:** full read of `packages/foam-core/src/model/*` and `src/services/*`, the export subsystem, the consumer packages' integration points, the perf instrumentation (`load-profiler`, benches, `scripts/perf/gate.mjs`), and the open issue tracker. Every finding cites `file:line` against commit `8b03256`. - **Legend:** each proposal carries **Effort** (S ≈ hours, M ≈ 1–3 days, L ≈ 1–2 weeks+), **Breaking** (against the `@foam/core` public surface in `packages/foam-core/src/index.ts`, or user-visible behavior), and **Impact** with rationale. --- ## Executive summary The core model is in good shape structurally — the reversed-trie workspace index, the incremental graph, the `PublishTarget` export abstraction, and the perf-gate CI are all well-designed. The review found no architectural rot, but it did find: 1. **A handful of genuine correctness bugs**, including one silent data-loss case in the workspace index (case-colliding filenames), a divergence between the incremental graph and a full rebuild, and rename/edit paths that can corrupt files (no overlap detection, duplicated definition edits). 2. **A semantic gap advertised but not implemented:** aliases are offered by link completion but never participate in link resolution, so the extension can suggest a link it will then render as broken. 3. **Lifecycle leaks** (tags never disposed, providers never disposed, one failing feature aborts the whole extension activation and strands live resources). 4. **Avoidable hot-path costs** that map directly onto the two open perf issues (#1375, #1689): a wasted nested tree-walk in the block parser, an O(n·m) file matcher, a full SHA-1 + deserialize on every parser-cache *hit*, and a full-workspace clone per rename. 5. **API-surface debt:** a 297-symbol barrel of which ~34% has no in-repo consumer, host concerns embedded in the platform-agnostic core (telemetry endpoint, VS Code-only config getters), and duplicated serializers that make the CLI and MCP emit different wire formats for the same data. 6. **Doc drift:** `CLAUDE.md` describes the pre-`foam-core` repo layout and actively misdirects contributors (and agents). The roadmap at the end sequences these into four phases. Phase 1 (correctness + leaks) is entirely non-breaking and roughly two weeks of work; the breaking items are concentrated in Phase 4 and can ride a single minor/major release. --- ## 1. Correctness fixes ### 1.1 Case-colliding filenames silently overwrite each other in the workspace index `FoamWorkspace` keys its trie by a reversed, **lowercased** path (`workspace.ts:350-365`, `normalize` at `:528`). `/a/Note.md` and `/a/note.md` produce the identical key, so the second file **replaces** the first in `_resources`, and `set()` emits `onDidUpdate` instead of `onDidAdd` (`workspace.ts:127-137`) — which then desynchronizes the graph (it disconnects the old path while connecting the new one, leaving stale backlinks). The existing #1303 regression test (`workspace.test.ts:187-209`) uses files in *different* directories, so this collision is untested. The model currently has two incompatible notions of identity: `find(URI)` is case-insensitive while `URI.isEqual` (`uri.ts:236-244`) is case-sensitive. **Proposal:** store exact-case keys in the trie with a case-insensitive lookup layer (bucket resources under the lowercased key), define identity policy in one place, and add the missing same-directory regression test. **Effort:** M · **Breaking:** No (fixes a currently-broken case) · **Impact:** High — silent data loss in the model; affects any vault with case-variant filenames (common on case-sensitive filesystems / git checkouts). ### 1.2 Incremental graph diverges from a rebuild when an added file changes a non-placeholder resolution `onResourceAdded` (`graph.ts:140-144`) only re-resolves sources currently pointing at a *placeholder*. But adding a file can also change resolution of a link that already resolves to a real note, because ambiguity is broken by path sort (`workspace.ts:290`) and directory-index suffix match (`workspace.ts:229-239`). Example: `[[attachment-a.pdf]]` resolves to `/path/to/more/attachment-a.pdf`; adding `/path/to/attachment-a.pdf` should re-point it — the full-rebuild path asserts exactly this (`graph.test.ts:183-221`), the incremental path misses it. The comment at `graph.ts:136-138` acknowledges the missing inverse-resolution capability. `graph-incremental.test.ts` has no "add steals an already-resolved target" case, and the `[flat]` perf gate (`workspace-graph.bench.ts:132-142`) only covers the update path. **Proposal:** on add, additionally reconnect sources whose links resolve *by identifier* to the new resource's basename (the workspace can expose "which identifiers does this URI answer to"); add the missing incremental test and extend the scaling bench to add/delete paths. **Effort:** M · **Breaking:** No · **Impact:** High — the graph (backlinks panel, orphans, graph view) is quietly wrong after a common operation until the next full reload. ### 1.3 Rename/edit pipeline can corrupt files Three compounding defects: - `TextEdit.apply` (`text-edit.ts:18-50`) has **no overlap detection** — overlapping ranges silently corrupt the document. - The parser resolves every reference link to the **same `NoteLinkDefinition` object** (`markdown-parser.ts:204-206`), so a file with `[a][ref]` and `[b][ref]` makes `heading-edit` emit **two edits with the identical range** (`heading-edit.ts:85-118`, `:215-247`) — no dedup anywhere, including `commands/rename.ts:47-67`. Combined with the missing overlap check, the definition line is rewritten twice. - `createUpdateLinkEdit` throws on external links (`markdown-link.ts:100-102`) and `heading-edit.ts:126` calls it outside its try/catch, so one odd link aborts an entire rename. **Proposal:** dedupe edits by range before applying; make `TextEdit.apply` throw on overlaps; guard the `analyzeLink`/`createUpdateLinkEdit` call sites consistently. Add the `[a][ref] + [b][ref]` test. **Effort:** S · **Breaking:** No · **Impact:** High — these are the operations users trust most (rename heading/block across the vault); failure mode is silent file corruption. ### 1.4 CLI/MCP rename leaves markdown-style links dangling `link-integrity.ts:71` only rewrites `wikilink` connections; markdown `[text](note.md)` links are documented as "delegated to VS Code built-in" (`link-integrity.test.ts:134`). That fallback exists only in the editor — `commands/rename.ts:112` and `commands/note.ts:306` are the CLI/MCP path, where markdown links silently break on rename. **Proposal:** handle `link.type === 'link'` in `link-integrity`, optionally behind a `linkTypes` option so the VS Code host can keep delegating. **Effort:** M · **Breaking:** Behavior change for CLI/MCP renames (strictly a fix) · **Impact:** High for CLI/MCP users — renames are currently unsafe outside the editor. ### 1.5 Tag range extraction has wrong-position bugs - Frontmatter tag ranges use substring search (`markdown-parser.ts:384-386`): tag `foo` matches inside `foobar` on an earlier line, producing a wrong range — and `TagEdit` writes edits at exactly those ranges. - Hashtag ranges assume a single-line text node (`markdown-parser.ts:399-408`): a `#tag` on the second line of a multi-line paragraph gets a range on the wrong line/column. All existing tests use single-line paragraphs. - `tag-edit.ts:79-85` distinguishes hashtag vs frontmatter tags by comparing the **range length**, coupled invisibly to how the parser computes ranges two files away. **Proposal:** fix both range computations (word-boundary anchoring; newline-aware offset mapping) with targeted tests, and add a `source: 'inline' | 'frontmatter'` discriminator to `Tag` (`note.ts:75-78`) so `tag-edit` drops the heuristic (requires a `CACHE_VERSION` bump in `foam-vscode/src/vscode/services/cache.ts:37`). **Effort:** M · **Breaking:** `Tag` field addition is additive; cached-resource schema bump only · **Impact:** Medium-High — tag rename writes edits at wrong positions in these cases; also unblocks #1240-adjacent tag work. ### 1.6 Assorted small correctness fixes (batch) | Fix | Where | |---|---| | `useAngles` off-by-one: target *starting* with a space isn't angle-wrapped | `markdown-link.ts:124`, `note.ts:55` (`indexOf(' ') > 0` → `includes(' ')`) | | Missing null check: `workspace.find(source)` result dereferenced | `markdown-provider.ts:205` | | `.sort()` without comparator on objects — sorts nothing | `markdown-provider.ts:280` | | `/m` vs `/gm` inconsistency stripping block-anchor markers | `markdown-provider.ts:55` vs `:68` | | `String.replace` with string containing user text interprets `$` patterns | `tag-edit.ts:238` | | Attachment extension case inconsistency: `photo.PNG` accepted but misclassified | `attachment-provider.ts:39,65-67,71` | | Watcher change handler race: two rapid changes to one file, last *read* wins not last *event* | `foam.ts:69-73` — serialize per-URI | | Frontmatter `tags` line lookup can be `undefined` → tags silently vanish | `markdown-parser.ts:376-378` | **Effort:** S (one batch PR) · **Breaking:** No · **Impact:** Medium — each is small, but all are user-visible in edge cases and cheap to fix together. --- ## 2. Lifecycle & resource management ### 2.1 `foam.dispose()` leaks `FoamTags`; workspace never disposes providers `bootstrap`'s disposer (`foam.ts:110-114`) disposes subscriptions, workspace, and graph — never `tags`, whose three workspace listeners (`tags.ts:41-45`) and emitter leak. `FoamTags.dispose()` itself also skips its emitter (unlike `FoamGraph.dispose()`, `graph.ts:263-265`). Separately, `FoamWorkspace.dispose` (`workspace.ts:460-464`) never disposes registered providers even though `ResourceProvider extends IDisposable` (`provider.ts:6`). **Proposal:** fix both; better, give `Foam` a `DisposableStore` so new members can't be forgotten. **Effort:** S · **Breaking:** No · **Impact:** Medium — leaks on every reload/deactivate cycle; matters for long-lived hosts and the embeddable MCP library. ### 2.2 One failing feature aborts extension activation and strands live resources `extension.ts:174` joins all features with `Promise.all`; a single rejection means `context.subscriptions.push(foam, watcher, parserCache, …)` at `:185` never runs — `Foam`, the watcher, and the parser cache stay alive and undisposed, and `extendMarkdownIt` is silently lost (preview loses all Foam rendering). Features are anonymous functions (`features/index.ts:15-28`), so the error can't even name the culprit. **Proposal:** switch to `Promise.allSettled` with per-feature error logging; push core resources into `context.subscriptions` immediately after bootstrap; give features an `id` (and optional `supports: 'node' | 'web'`) — `interface FoamFeature { id; supports?; activate(ctx, foam) }`. The `id` also fixes the acknowledged telemetry-key collision risk (`types.d.ts:11-12`) and gives the web build a declarative way to skip Node-only features (see §6.2). **Effort:** M · **Breaking:** No (internal to the extension) · **Impact:** High — converts "any feature bug bricks Foam" into "one feature degrades". ### 2.3 Leaked registrations in graph-webview `graph-webview/index.ts:21` (`onDidChangeConfiguration`) and `:62` (`registerCommand('foam-vscode.show-graph', …)`) discard their disposables; every other feature pushes them into `context.subscriptions`. **Effort:** S · **Breaking:** No · **Impact:** Low — orphaned registrations on deactivate/reactivate. ### 2.4 Honor `FoamTags`' `debounceFor` parameter `tags.ts:33` accepts `debounceFor` but `:40` hardcodes `debounce(..., 500)` — the value is used only as an on/off flag, and `bootstrap` never passes it, so tags are undebounced in production. **Effort:** S · **Breaking:** No · **Impact:** Low alone; pairs with §3.4. --- ## 3. Performance These target the two open perf axes tracked by the bench suite (`workspace-graph.bench.ts:14-30`, #1375) and the slow-load report (#1689, `load-profiler.ts:13-14`). The perf-gate CI (`scripts/perf/gate.mjs`: fail at 2.0×, warn at 1.3×; `[linear]`≤1.8, `[flat]`≤1.0 normalized) will verify each claim. ### 3.1 Block parser does a wasted nested tree-walk per node `blocksPlugin.visit` (`markdown-parser.ts:509-518`) calls `getDirectText(node)` — itself a **full subtree visit** (`:332-340`) — for every paragraph/listItem/blockquote/heading, then discards the text whenever there's no `^` block anchor, which is nearly always. This is a constant-factor ~2× traversal on flat documents and O(n·depth) on nested ones — the single largest avoidable cost in the parse path, which the profiler already identifies as the load bottleneck (`load-profiler.ts:218-219`, parse is super-linear in note size). Also: `note.blocks.some(...)` in the same loop is O(blocks²) (`:537`), and each own-line blockquote anchor re-splits the whole source (`:570`). **Proposal:** gate `getDirectText` on a cheap "does this node's source range contain `^`" check; replace the `some` with a `Set`; split the source into lines once per parse and share with the footnote scan (`:237`). **Effort:** S · **Breaking:** No · **Impact:** High — directly attacks #1689/#1375; expected double-digit-% parse-time reduction on typical vaults, verifiable in `markdown-parser.bench.ts`. ### 3.2 Parser cache hits still pay SHA-1 + full deserialize `cachedParser` (`markdown-parser.ts:275-301`) hashes the entire document (SHA-1, `utils/core.ts:49`) on every call, and a hit still runs `Resource.fromJSON` (`foam-vscode/src/vscode/services/cache.ts:201-210`). During typing this is the hot path, and the profiler reports it as a cheap "hit". **Proposal:** let the host pass a cheaper validity token (document version/mtime) so unchanged documents skip hashing entirely; collapse `cache.has` + `cache.get` into one call; consider memoizing the last deserialized resource per URI. **Effort:** M · **Breaking:** No (additive cache API) · **Impact:** Medium-High — removes per-keystroke work proportional to note size. ### 3.3 O(n·m) file matcher on the VS Code hot path `FileListBasedMatcher.match()` filters with `Array.includes` over a `string[]` (`datastore.ts:168-170`); `isMatch` is O(n) per call. This is the matcher VS Code selects in the common case (`editor.ts:495-502`) — on a 10k-file vault a single `match(allFiles)` is ~10⁸ comparisons. The class carries its own "to be refactored later" note (`:150`). **Proposal:** back it with a `Set`. While in there: its `include`/`exclude` fields are decorative (never consulted) — either wire or remove them. This is also the natural place to add **`.gitignore` support (#1388)**, the most-requested open datastore issue. **Effort:** S (Set) + M (gitignore) · **Breaking:** No · **Impact:** Medium-High — removes a quadratic on load and on every matcher refresh; #1388 has standing user demand. ### 3.4 `FoamTags` rebuilds the entire tag index on every file event `tags.update()` (`tags.ts:51-61`) is a full O(total tags) rebuild wired to all three workspace events (`:42-46`), unlike the graph which is incremental. Every panel listening to `tags.onDidUpdate` then refreshes wholesale. **Proposal:** incremental update using the `{old, new}` payload the workspace already provides (index tag locations by resource as well as label). **Effort:** M · **Breaking:** No · **Impact:** Medium — flattens per-edit cost in tag-heavy vaults; pairs with §2.4 and §4.6. ### 3.5 `link-integrity` clones the whole workspace per rename `buildFutureWorkspace` (`link-integrity.ts:13-26`) copies every resource into a fresh `FoamWorkspace` to answer one identifier question — a full second index per rename on large vaults. **Proposal:** an overlay resolver over the live workspace (consult the overlay first, fall through). **Effort:** M · **Breaking:** No · **Impact:** Medium — rename latency on large vaults. ### 3.6 Other measured/mechanical wins (batch) - `_unregisterDirectoryIndex` is O(workspace) on every delete of an index file (`workspace.ts:185-212`) → keep per-directory candidate lists. - `TextEdit.apply` builds a per-character array per edit (`text-edit.ts:22-50`) → offset-based slice concatenation. - Per-node plugin dispatch re-enters a try/catch and probes 6 optional methods per AST node (`markdown-parser.ts:183-189`) → precompute the visitor list per parser. - `getTagAtPosition` scans all tags × locations per call (`tag-edit.ts:265-283`) → per-URI index. - CLI gets neither parser cache nor profiler (`foam-cli/src/support/filesystem.ts:172`) → wire both; big cold-start win for CLI/MCP and export. - Profiler hygiene: no `reset()` (double-counts on second load), chars misreported as MiB (`load-profiler.ts:63-67`, `:147`, `:237`). **Effort:** S-M per item · **Breaking:** No · **Impact:** Medium in aggregate. ### 3.7 (Strategic) Replace remark-parse v8 / unified v9 with micromark The pinned parser stack is several majors behind. It is the root cause of: the regex-based footnote scan (`markdown-parser.ts:231-268`), the collapsed consecutive-footnote ASTs, likely the documented super-linear parse scaling, and the wikilink-in-math false positives (#1317). The bench file already ships an A/B harness for exactly this migration (`markdown-parser.bench.ts:97-101`). **Proposal:** migrate to `micromark`/`mdast-util-from-markdown` behind the existing `ParserPlugin` seam; prove parity with the golden-file tests and the A/B bench before switching. **Effort:** L · **Breaking:** Potentially (AST-shape-dependent plugins; parse edge cases change) · **Impact:** High long-term — removes a whole class of workarounds and the main super-linear cost; should be scheduled, not rushed. --- ## 4. Information model evolution ### 4.1 Make aliases participate in link resolution Aliases are parsed (`markdown-parser.ts:700-712`), stored on `Resource`, offered by **link completion** (`link-completion.ts:269`) and search — but `listByIdentifier` (`workspace.ts:266-291`) only ever consults paths. `[[my-alias]]` yields a placeholder even when a note declares `alias: my-alias`: the system suggests links it then fails to resolve. This is the single biggest semantic gap in the model. **Proposal:** index aliases alongside basenames with documented precedence (exact path > basename > alias), behind a config flag initially (matching the `directoryMode` precedent, `markdown-provider.ts:24`). **Effort:** M · **Breaking:** Behaviorally (previously-broken links start resolving — flag-gated) · **Impact:** High — closes a visible feature contradiction; frequently expected by users coming from Obsidian. ### 4.2 Normalize placeholder identity in the model `URI.placeholder(path)` does no normalization (`uri.ts:99-101`): `[[page-b]]` and `[../page-b.md]` denoting the same missing file become **two distinct graph nodes** (pinned in `graph.test.ts:225-260`), so the placeholders panel shows duplicates. Placeholder construction is scattered across four sites in `markdown-provider.ts` (`:120,132,152,167`), and "placeholder-ness" is modeled three different ways (URI scheme `uri.ts:201-203`; a phantom `Resource.type === 'placeholder'` that the workspace never stores; a template-trigger type). **Proposal:** a single model-owned placeholder factory that canonicalizes identity (workspace-resolved path where resolvable, raw text kept as label); remove the phantom resource type or promote it to a real variant. **Effort:** M · **Breaking:** Yes — placeholder paths are visible in `graph.placeholders`, the panel, and tests · **Impact:** Medium-High — correct placeholder dedup, simpler consumers, prerequisite for sane "create note from placeholder" flows. ### 4.3 Split `FoamWorkspace.find` and fix its inconsistencies `find(URI | string)` (`workspace.ts:367-415`) is three functions behind one signature (trie get / identifier resolution / path probing across roots), and it returns the **stored object** normally but a **fresh shallow copy** when the reference carries a `#fragment` (`:408-413`) — reference equality depends on argument syntax. Ambiguity resolution ("alphabetically first path wins") is encoded in a sort call (`:290`). **Proposal:** explicit `findByUri` / `findByIdentifier` / `findByPath`; fragment handling returns `{resource, section}` instead of a patched copy; document the ambiguity policy. Keep `find` as a deprecated shim for one release. **Effort:** M · **Breaking:** Yes (widely used in foam-vscode; mechanical migration) · **Impact:** Medium — the API's biggest ambiguity source; enables §1.2's identifier inversion cleanly. ### 4.4 Key the graph by full URI identity, not `uri.path` `links`/`backlinks`/`placeholders` are `Map` (`graph.ts:21-29, 247-258`): in a virtual workspace `file:///notes/a.md` and `vscode-vfs://github/notes/a.md` collide (multi-scheme resolution is explicitly supported — `workspace.test.ts:303-326`); fragments are silently ignored, so callers must remember `.asPlain()` (done in five places in `commands/links.ts`). The same path-keyed pattern recurs in the export context (`export/types.ts:179,184`) and embeddings (`ai/model/embeddings.ts:39`). **Proposal:** introduce a small `URIMap` (canonical `scheme://authority/path` keying, explicit fragment policy) in `model/uri.ts` and use it in graph, export, embeddings. Make `getLinks`/`getBacklinks` normalize their argument. **Effort:** M · **Breaking:** Yes for direct readers of `graph.links`/`graph.backlinks` (public mutable maps — see §4.5) · **Impact:** Medium — correctness on virtual/multi-root workspaces (web extension, remote repos), removes a caller ritual. ### 4.5 Encapsulate the graph/tags collections `graph.placeholders/links/backlinks` and `tags.tags` are `public readonly` Maps — the reference is readonly, the contents are not; any consumer can `foam.graph.links.clear()`. Stored `Resource`s are also held by reference with no copy (`workspace.ts:131`), so in-place mutation corrupts the index and defeats the `{old, new}` update diff. **Proposal:** accessor methods returning `ReadonlyMap`/iterators; document (or enforce via `Object.freeze` in dev builds) that `Resource` is immutable once stored. **Effort:** S-M · **Breaking:** Yes, mechanical · **Impact:** Medium — removes a foot-gun class; prerequisite for safely evolving internals (§4.4). ### 4.6 Batchable events with payloads `workspace.clear()` fires one delete per resource (`workspace.ts:149-158`) → N graph mutations + N full tag rebuilds + N panel refreshes; there is no batch/transaction primitive even though `PauseableEmitter`/`EventBufferer` already exist (`common/event.ts:749, 878`). `graph.onDidUpdate` and `tags.onDidUpdate` are `Event`, so all ~7 VS Code listeners can only blanket-refresh. Delivery is synchronous and re-entrant (`common/event.ts:706-733`). **Proposal:** additive first — `onDidChangeBatch: Event` on the workspace, used by `clear()` and bulk load; a debounced aggregate `Foam.onDidChangeWorkspace` (the preview feature currently hand-rolls this from three subscriptions, `preview/index.ts:20-30`). Later, upgrade `onDidUpdate` to carry a delta (breaking for listeners). **Effort:** M (additive) + S (listener migration) · **Breaking:** Additive now; delta payload later is breaking · **Impact:** Medium-High — turns O(N) panel refresh storms into O(1); foundation for scaling to large vaults. ### 4.7 Type-model tightening - `Resource.type: string` → union `'note' | 'attachment' | 'image'` (`note.ts:146`); `properties: any` → `Record` (`:147`). **Breaking**, mostly mechanical. - `ResourceLink.definition?: string | NoteLinkDefinition` encodes a three-state machine decoded by four predicates with order-sensitive call sites (`note.ts:5-44`; `markdown-provider.ts:94-138`) → discriminated union `{kind: 'inline'} | {kind: 'ref-unresolved'; label} | {kind: 'ref-resolved'; definition}`. **Breaking** (parser + tests construct it). - `Connection` (`graph.ts:8-12`) carries no resolution provenance → add `resolvedBy: 'path' | 'identifier' | 'directory-index' | 'placeholder'`; every consumer currently re-derives this. **Additive.** Also directly serves typed-links exploration (#1626). - URI derivations (`getDirectory`, `joinPath`, …) preserve `fragment`/`query` (`uri.ts:125-152`), yielding directories with section anchors; `asPlain()` exists solely to undo it → drop fragment/query on parent/derivation ops. **Non-breaking in practice** (all call sites strip or have none). - `asAbsoluteUri` (`uri.ts:465-493`) disagrees with `FoamWorkspace.resolveUri` on the primary case (`uri.test.ts:131-140` vs `workspace.test.ts:277-281`) and is publicly exported → redefine in terms of `resolveUri` or remove. **Breaking.** - Dead indirection: `pathToPlaceholderId` is the identity function (`graph.ts:14`); `wikilinkPlugin.onDidVisitTree` is an empty function (`markdown-parser.ts:798-801`); duplicate `CancellationToken` in `progress.ts:21-24`. Delete. **Non-breaking.** **Effort:** S-M per item · **Impact:** Medium — compile-time safety over runtime predicates; cheapest during the same release that takes §4.3/§4.4. ### 4.8 Parser instance isolation `sectionStack` is module-level mutable state shared by every parser instance (`markdown-parser.ts:416`), and `onDidInitializeParser` mutates the module-level `unified` processor (`:63, :105`) so `extraPlugins` from one `createMarkdownParser` call leak into all others. Safe today only because parsing is synchronous and single-instance. **Proposal:** per-instance processor; per-parse context object threaded through `ParserPlugin` (breaking for the plugin interface, which has few implementors). **Effort:** M · **Breaking:** Yes (plugin interface) · **Impact:** Medium — prerequisite for embedded-note parsing, parallel parse, and the §3.7 migration. --- ## 5. API & package architecture ### 5.1 Tier and split the public API surface `@foam/core` exposes a single 315-line barrel re-exporting **297 symbols**; cross-referencing all three in-repo consumers, **~102 are never imported by anyone**. Output is CJS-only, so importing `URI` drags in jexl, the export pipeline, and lint rules — the web bundle and MCP pay for subsystems they never call. **Proposal:** add subpath exports (`@foam/core/model`, `/export`, `/query`, `/lint`) and ESM output alongside CJS; split the barrel into a documented contract tier and an internal tier; add an API-report CI check (api-extractor or attw). Root barrel should delegate to per-subsystem `index.ts` curators — today `src/index.ts:194-239` hand-duplicates `export/index.ts`'s list and the two have already diverged. **Effort:** M-L · **Breaking:** Additive now; demoting unused symbols is breaking for hypothetical external users only · **Impact:** High — bundle size for web/MCP, and it establishes the semver contract *before* external consumers depend on accidental surface. ### 5.2 Move host concerns out of core - The App Insights connection string and envelope builder live in the platform-agnostic core (`telemetry.ts:158-159`, exported at `index.ts:180-184`). The string is deliberately a non-secret ingestion key, but a product's telemetry destination is deployment config, not library code — any fork/embedder silently inherits Foam's endpoint. - `IFoamConfig` (`config.ts:1-46`) carries ≥8 editor-UI getters (`getGraphOnStartup`, `getPreviewEmbedNoteType`, `getCompletionLabel`, …) that a headless CLI is forced to stub (`foam-cli/src/support/config.ts:60-65`). - `Config` is a mutable process-global singleton (`config.ts:149-166`) with exactly one core reader (`template-discovery.ts:15`) — a real hazard for `@foam/mcp`, which is meant to be embeddable (two workspaces in one process can't differ). **Proposal:** core keeps `ITelemetryReporter` + bucketing only; endpoint + consent copy move to hosts. Split `CoreConfig` (files, templates, daily notes) from host config. Thread config explicitly (`getTemplatesDir(rootUri, config)`), retire the global. **Effort:** M · **Breaking:** Yes — small, in-repo call-site count (≤5) · **Impact:** Medium-High — makes core genuinely embeddable and forkable; unblocks publishing `@foam/mcp`. ### 5.3 Retire the `foam-vscode` shim layer; repatriate stranded platform-agnostic code Four directories in `foam-vscode/src` have zero `vscode` imports: `src/core/` (a second `bootstrap` whose 8th positional parameter *diverges* from core's — `foam-vscode/src/core/model/foam.ts:23-32` vs `foam.ts:32-42`, an accident waiting to happen), `src/ai/model` + `src/ai/services` (382-line `FoamEmbeddings`, pure core), `src/lint/`, and `src/daily-note/`. The shim type also makes the feature registry contravariantly unsound — it only compiles because `strict: false`. The lint case is user-visible: the four wikilink rules (`rule-check-links.ts:22`) are only reachable by the editor, so **`foam lint` in CI cannot catch broken wikilinks** while the editor can (`foam-cli/src/commands/lint.ts:14-18`). Relatedly, `lintNote` hardcodes its rule list while `lintWorkspace` takes `rules[]` (`lint.ts:47-49, 86`) — two extensibility models in one file. **Proposal:** move embeddings/lint/daily-note logic into core (embeddings as an optional `Foam` member; Ollama provider stays host-side); make core's `bootstrap` take an options object (it has **nine positional parameters**); delete the shim. Align `lintNote`/`lintWorkspace` on injected rules + `defaultLintRules()`. **Effort:** M-L · **Breaking:** `bootstrap` and `lintNote` signatures (3 and 2 call sites); rest is internal moves · **Impact:** High — one `bootstrap`, CLI lint parity (CI catches broken wikilinks), and unlocks `strict: true` for the extension. ### 5.4 Unify the CLI/MCP wire format `foam-cli/src/support/serializers.ts` (148 lines) and `foam-mcp/src/serializers.ts` (203 lines) independently serialize the same nine core result types — and disagree: CLI emits absolute fs paths (`serializers.ts:45`), MCP emits workspace-relative POSIX paths with `placeholder:` handling (`serializers.ts:52-55`). Same note, two encodings; CLI has no placeholder story at all. **Proposal:** one `@foam/core/serialize` module owning the `Json*` types and URI encoding (option: `'fs' | 'workspace-relative'`); both hosts consume it. Prefer unifying on workspace-relative. **Effort:** M · **Breaking:** CLI JSON output changes if unified (recommended; flag the old encoding) · **Impact:** Medium — consistency for scripts/agents consuming both surfaces; halves maintenance. ### 5.5 Honor the `IDataStore` contract; make capabilities explicit The interface requires `list(pattern)` to filter (`datastore.ts:12-17`) but the VS Code implementation ignores the pattern entirely (`editor.ts:408` takes no parameter) — currently masked only because saved queries build their own store (`saved-store.ts:102-138`); any future `dataStore.list(glob)` call in the extension is a silent data bug. `GenericDataStore` also throws at runtime for the 4-of-6 optional operations while claiming the full interface (`datastore.ts:117-143`), and `read` conflates missing vs unreadable (both `null`, `:106-115`). None of the shipping implementations have direct tests. **Proposal:** fix the VS Code `listFiles` to honor the glob; split `IReadableDataStore`/`IWritableDataStore` (or a capabilities probe); distinguish not-found from error; add the missing tests. **Effort:** M · **Breaking:** Interface split is breaking (4 implementations, all in-repo) · **Impact:** Medium — closes a documented contract violation before it becomes a bug. ### 5.6 Packaging hygiene (batch) - `@foam/core/test` relative-imports `../src/*`, forcing a dual-instance-of-`URI` alias hack in **three** vitest configs (`foam-vscode/vitest.config.mts:41-48` documents it), while `instanceof URI` is used in production (`convert-links-format.ts:26`); `test-utils` also imports `micromatch`, which is not a declared dependency, and there's no `files` allowlist so npm ships `src/`, `test-data/`, etc. → import via the package entry, fix deps, add `files`. - `foam-vscode` duplicates 15 of core's dependencies as phantom runtime `dependencies` (nothing installs them; esbuild bundles) — version skew between the two `package.json`s would silently ship a different parser than tests run → move to `devDependencies`, single source of truth in core. - `@foam/mcp` declares `"@foam/core": "*"` as a runtime dep, but core publishes under the name `foam-core` (`release.js:29-31`) — the moment `@foam/mcp` is published it cannot resolve → bundle like cli/vscode, or publish under the real name. - Dead `cli` build target in `foam-vscode/esbuild.js:31,136-146,177-188` (the `src/cli/` it builds no longer exists) → delete. - Three field-identical graph-data types (`graph-data-builder.ts:5-16`, `export/types.ts:126-144`, `foam-graph/src/protocol.ts:16-25`), with `build-site-graph.ts:12` compiling only by structural coincidence → alias the two in-core copies; keep the protocol copy as a deliberate wire contract with a compile-time compatibility assertion. - `graph-data-builder.ts:75` ships the **entire raw frontmatter** into graph payloads consumed by the webview *and the published static site* — private frontmatter fields leak into published graph JSON → allowlist exported keys. **Effort:** S-M per item · **Breaking:** No (except the frontmatter allowlist, a behavior fix) · **Impact:** Medium — the frontmatter leak in particular is a privacy fix for publishing. --- ## 6. Platform integrity (web / CLI parity) ### 6.1 Mechanically enforce "no Node imports in foam-core" The invariant holds today by review only: core's `tsconfig` includes `"types": ["node"]`, so `process`/`Buffer` type-check fine. One lint rule (`no-restricted-imports` on `fs|path|os|node:*` in `packages/foam-core/src`) makes the repo's most important invariant enforceable. **Effort:** S · **Breaking:** No · **Impact:** High leverage for the cost — prevents an entire regression class. ### 6.2 `export-html-page` ships broken in the web extension It imports `fs/promises` directly (`export-html-page/index.ts:2,85,91`) and is registered unconditionally; the web build's `polyfillNode()` makes it *bundle* but not work. Two other fs-users get bespoke esbuild `onResolve` swaps (`esbuild.js:72-101`) — a substring-matching mechanism invisible from the source tree. **Proposal:** route file I/O through `foam.services.dataStore` (already works in both hosts); replace the regex swap mechanism with explicit `.web.ts` twins or `browser` field mapping; use §2.2's `supports` field to gate genuinely Node-only features. **Effort:** S (gate) + M (dataStore refactor) · **Breaking:** No · **Impact:** Medium — a visibly broken command in the web host today. ### 6.3 Path-string discipline cleanup Per the repo's own URI convention: `grouped-resources-tree-data-provider.ts:1,85-89` runs Node `path.parse` on a URI component; `export/types.ts:72` accepts `contentRoot?: string | URI` (the one both-typed field in core's config surface — a `vscode-vfs://` workspace will resolve incorrectly); `foam-cli/src/support/filesystem.ts:28-34` reimplements core's `isWithinPath` under the same name with a different signature. Also export `getBasename`/`getExtension`/`getDirectory` from core's barrel — CLAUDE.md tells contributors to use them, but they aren't currently exported (`index.ts:151-158`), which is part of why reimplementations happen. **Effort:** S · **Breaking:** `contentRoot: URI` only (2 in-repo call sites) · **Impact:** Low-Medium each; collectively keeps the convention honest. --- ## 7. Documentation ### 7.1 `CLAUDE.md` describes the pre-`foam-core` repository and actively misdirects It states core lives in `packages/foam-vscode/src/core/` (now a one-file shim), features in `src/features/` (now `src/vscode/features/`), claims a `tsconfig` `paths` mapping for `@foam/graph-view` that doesn't exist, and recommends path utilities core doesn't export. `CONTRIBUTING.md:58-62` is *correct*, so the two root docs contradict each other. Also: `docs/user/features/templates.md:284` links to a moved file (user-facing broken link), and `docs/dev/testing-conventions.md:25` is stale. **Proposal:** rewrite the structural sections of `CLAUDE.md` against the current tree and make it point to `CONTRIBUTING.md` for structure (the duplication is what drifted); fix the two stale doc links. **Effort:** S · **Breaking:** No · **Impact:** High for contributor/agent effectiveness — this file is loaded into every AI-assisted session and currently sends it to the wrong directories. --- ## Prioritized roadmap **Phase 1 — Correctness & leaks (all non-breaking; ~2 weeks)** 1.1 trie case collision · 1.2 incremental-add divergence · 1.3 edit corruption · 1.5 tag ranges · 1.6 small-fix batch · 2.1–2.4 lifecycle fixes · 5.6 frontmatter leak in published graphs · 6.1 core import lint · 7.1 CLAUDE.md rewrite **Phase 2 — Performance (non-breaking; ~1–2 weeks; verified by the existing perf gate)** 3.1 block-parser walk · 3.3 matcher Set (+#1388 gitignore) · 3.2 cache-hit cost · 3.6 mechanical batch · 3.4 incremental tags · 3.5 rename overlay **Phase 3 — Parity & packaging (mostly non-breaking; ~2 weeks)** 5.3 lint rules to core (CLI wikilink lint) · 1.4 CLI markdown-link rename · 6.2 web export fix + feature `supports` · 5.4 shared serializers · 5.6 packaging batch · 4.6 batch events (additive part) · 2.2 feature isolation + ids **Phase 4 — Model & API evolution (breaking; one coordinated minor/major)** 4.1 alias resolution (flagged) · 4.2 placeholder identity · 4.3 `find` split · 4.4 `URIMap` graph keying · 4.5 collection encapsulation · 4.7 type tightening · 4.8 parser isolation · 5.1 API tiering + subpaths · 5.2 config/telemetry out of core · 5.5 datastore contract · **then** 3.7 micromark migration behind the A/B bench **Issue cross-references:** #1375/#1689 (Phases 2, 4-parser), #1388 (3.3), #1240 (1.5/4.7 groundwork), #1317 + #1631 (3.7), #1626 (Connection provenance, 4.7), #1685 (safe to do alongside 3.2), #1303 (1.1 closes the remaining gap). --- ### Dev Design Improved Static Site Generation (`docs/dev/design/improved-static-site-generation.md`) # Improved Static Site Generation ## Summary Foam should adopt a two-layer publishing architecture: - a Foam-owned publishing layer in TypeScript that understands Foam semantics - a modern static site shell, with Astro and Starlight as the default implementation This keeps Foam aligned with the project's build-vs-assemble principle while still giving users a polished website for browsing their knowledge base. ## Problem Today, Foam has publishing documentation and community templates, but not a single modern architecture that: - preserves Foam semantics reliably - produces a high-quality static site - gives the project a durable TypeScript integration point - remains optional instead of locking Foam to one publishing target If Foam only chooses a website framework, the framework ends up becoming the architecture. That is too brittle. Foam needs a publishing pipeline of its own. ## Goals - Publish a Foam knowledge base as a static website - Preserve Foam-specific semantics where possible: - wikilinks - aliases - block anchors and section links - embeds - tags - backlinks - graph metadata - publish visibility rules - `foam-query` blocks, at least where they can be resolved safely at build time - Reuse Foam parsing and graph logic - Keep the publishing path framework-agnostic enough to support other site targets later - Make the default user experience modern and visually strong ## Non-Goals - Building a bespoke all-in-one site generator as the first step - Replacing ordinary Markdown authoring with a new required syntax - Requiring VS Code APIs during website generation - Solving every interactive publishing feature in the first iteration ## Recommended Stack ### Default Site Stack - Framework: Astro - Site shell: Starlight - Content input: generated Markdown plus derived JSON metadata - Optional richer authored pages: Markdoc or MDX where needed ### Why This Stack Astro and Starlight provide the polished site quickly. Foam's own publishing layer protects the project from tying note semantics directly to any one site framework. This means Foam can: - ship a good default website - keep the core publishing logic in TypeScript - preserve the option to support other renderers later ## Proposed Architecture ## 1. Foam Publishing Layer Add a publishing layer responsible for turning a Foam workspace into publishable artifacts. The logical module should not depend on VS Code. It should consume Foam core models and services. For implementation, this should be phased: - first iteration: `packages/foam-vscode/src/publish` - later extraction: `packages/foam-publish` The first iteration should be written as if it were already an extractable package. That means keeping it framework-agnostic, avoiding `vscode` imports, and giving it a clean entrypoint and module structure. Suggested responsibilities: - discover and load publishable notes from a workspace - resolve wikilinks, aliases, and anchors using Foam's own workspace and graph logic - evaluate publish visibility rules - rewrite links for the target site - expand or rewrite embeds - compute backlinks - compute graph/search metadata - render or precompute `foam-query` output when possible - emit a normalized set of output files for a site framework Suggested inputs: - workspace root - publish target configuration - output mode and path Suggested outputs: - transformed Markdown files for each published note - JSON indexes for search, backlinks, graph, and route metadata - copied static assets and attachments ## 2. Starlight Target Add a Starlight target inside the Foam publishing layer that materializes a runnable site directory. Responsibilities: - render the transformed notes into a Starlight-compatible content tree - write the site scaffold needed to run Astro and Starlight in the output directory - provide navigation, layout, SEO, and search UI through the generated Starlight app - keep Foam-specific semantics in the publish layer rather than in the site framework This target should stay thin. It is an implementation of the publishing output, not the source of truth for Foam semantics. ## 3. CLI and Automation Expose the pipeline through a CLI entry point, likely via Foam CLI or a dedicated command. Examples: - build a local static site - watch and rebuild during development - emit publishable artifacts for GitHub Pages, Vercel, or Netlify This matches the existing direction in the repository toward build-time transformations and automation. ## Data Flow The first version should follow this pipeline: 1. Read the Foam workspace using core services 2. Filter notes according to publish rules 3. Parse notes and resolve Foam constructs 4. Emit transformed Markdown for the site 5. Emit derived JSON indexes 6. Let the generated Astro and Starlight site build the final static HTML In shorthand: `Foam workspace -> foam-publish -> Markdown + JSON -> Astro/Starlight -> static HTML` ## Why Generated Markdown Plus JSON This is the most practical first output format. Advantages: - It keeps the content inspectable and portable - It works naturally with Starlight and Astro content collections - It avoids forcing the site layer to reimplement Foam parsing logic - It gives the site enough structured metadata for backlinks, graph views, and search-related UI Generating only HTML would make customization harder. Generating only a raw graph JSON model would push too much work into the site layer. Markdown plus derived JSON is the right balance. ## Treatment of Foam Features ## Wikilinks and Aliases Resolve them at build time to stable site routes. The site should not need to guess how Foam resolution works. ## Block Anchors and Section Links Emit stable heading and block IDs during transformation so links and popovers can target exact content. ## Embeds Handle note embeds at build time where possible. Preserve attachment embeds and image references as normal site assets. ## Backlinks Compute backlinks in `foam-publish` and expose them as page metadata or a site-wide index. ## Graph View Emit graph data as JSON derived from Foam's own graph model. Render it in the site layer with a dedicated component. ## `foam-query` Treat query blocks as build-time features when safe and deterministic. Where execution is unsafe or unsupported, fail clearly and leave a readable placeholder in output. ## Publish Visibility Rules Implement this in `foam-publish`, not in the site layer. The site should only receive already-filtered content. ## Why Not Make Markdoc the Core Markdoc is a good integration option, but not a good center of gravity for the first version. Reasons: - Foam notes should stay ordinary Markdown first - Foam already has its own semantics to preserve - switching the base representation to Markdoc would increase coupling and reduce portability Markdoc is still useful for richer authored documentation pages outside the imported note corpus. ## Why Not Start With Quartz Quartz is close enough to Foam that it is worth studying and possibly spiking against. However, starting directly from Quartz would blur the boundary between Foam semantics and site implementation. The project should instead: - borrow feature ideas from Quartz - compare experience against Quartz during prototyping - keep Foam's publishing logic separate from the chosen renderer ## Incremental Delivery Plan ### Phase 0: Internal Publish Spike - Implement the publishing layer in `packages/foam-vscode/src/publish` - Reuse existing Foam core and parser code where possible - Keep the module free of `vscode` imports - Prove the basic API and output shape before extracting a standalone package ### Phase 1: Minimal Viable Site - Publish filtered notes as routed pages - Rewrite wikilinks and attachments - Generate navigation from folders and titles - Support search through the default Starlight capabilities or a simple generated index ### Phase 2: Foam Semantics - Add backlinks - Add block anchors and section-deep links - Add note embeds - Add publish rules ### Phase 3: Knowledge-Base Experience - Add graph view - Add hover previews - Add richer query rendering - Add deployment presets and starter templates ## Open Questions - What exact publish-rule syntax should Foam support: public-by-default, private-by-default, or folder-based publishing? - Should `foam-query-js` be supported in published output at all, or only the declarative query language? - Should the first version generate files directly into a site workspace, or into an intermediate output folder consumed by the site package? - How much of the existing preview pipeline can be shared directly, and how much should move into framework-agnostic publish utilities? ## Proposed Decision Adopt Astro plus Starlight as the default website stack, and implement a framework-agnostic Foam publishing layer that emits transformed Markdown and derived JSON for the site to render. Start that implementation in `packages/foam-vscode/src/publish`, then extract it to `packages/foam-publish` once the API and boundaries have stabilized. That gives Foam the right default without collapsing publishing strategy into a single website framework. --- ### Dev Design Static Site Publishing Research (`docs/dev/design/static-site-publishing-research.md`) # Static Site Publishing Research Researched on April 17, 2026. ## Context Foam already has a publishing story, but it is spread across older templates and partial proposals rather than a single modern architecture. Relevant existing material in this repository: - [Publishing pages](../../user/publishing/publishing.md) says Foam should remain valid Markdown and be publishable by many tools, while leaving room for a more Foam-aware publishing path later. - Improved static-site generation, search in published workspaces, graph in published workspaces, and publishing permissions are all established goals. That gives a fairly clear constraint set: - Published output should preserve Foam semantics such as wikilinks, aliases, embeds, block anchors, backlinks, and queries where practical. - The publishing path should stay optional. A Foam workspace should still be usable as normal Markdown without requiring a bespoke site generator. - The implementation should fit a TypeScript-heavy codebase and reuse Foam's parsing and graph logic instead of reimplementing it in another stack. ## Evaluation Criteria The tools were evaluated against these criteria: - Quality of the generated site for documentation and knowledge-base content - Ease of integrating Foam-specific behavior - TypeScript support and extensibility - Static output and deployment simplicity - Suitability for a navigable knowledge base rather than only linear product docs ## What Obsidian Publish Gets Right Obsidian Publish is the product benchmark, not the implementation benchmark. Its public positioning emphasizes the reader experience for connected notes: hover previews, graph view, stacked navigation, backlinks, strong SEO, mobile support, and easy customization. Those are the right north-star features for Foam publishing even if Foam should not copy the hosted-product model. Source: - [Obsidian Publish](https://obsidian.md/publish) ## Option Review ## Astro Astro is a strong foundation layer for Foam publishing. Why it fits: - It is modern, fast, and static-first. - It has first-class TypeScript support. - It supports Markdown and MDX directly. - It has clear extension points through remark and rehype plugins. - It has typed content collections that work well for structured frontmatter and derived metadata. Most importantly, Astro is a good host for a Foam publishing adapter. It does not force Foam to adopt a new authoring model just to get a good site. Sources: - [Astro Markdown](https://docs.astro.build/en/guides/markdown-content/) - [Astro Content Collections](https://docs.astro.build/en/guides/content-collections/) ## Starlight Starlight is the strongest out-of-the-box shell among the options reviewed. Why it stands out: - It produces polished documentation sites quickly. - It includes site navigation, search, SEO, internationalization, readable typography, code highlighting, and dark mode out of the box. - It supports Markdown, Markdoc, and MDX. - It adds frontmatter validation with TypeScript type safety. - It keeps access to the wider Astro ecosystem instead of boxing the project into a narrow template. For Foam, this means the team can spend effort on Foam behavior instead of rebuilding the surrounding documentation-site basics. Source: - [Starlight](https://starlight.astro.build/) ## Markdoc Markdoc is powerful, but it should not be the center of Foam's publishing architecture. It is a good option for adding structured, component-rich authoring to specific parts of a site. However, using Markdoc as the canonical representation of Foam notes would move Foam away from portable Markdown and toward a richer custom syntax. That tradeoff does not look justified for the first version. Markdoc is best treated as an optional layer for advanced authored pages, not as the base representation of the knowledge base itself. Sources: - [Markdoc](https://markdoc.dev/) - [Astro Markdoc integration](https://docs.astro.build/en/guides/integrations-guide/markdoc/) ## Quartz Quartz is the closest match to Foam's use case and should be treated as the main reference implementation. Why it matters: - It is explicitly oriented toward note graphs and digital gardens. - It is configured in TypeScript. - It exposes a plugin pipeline with transformers, filters, and emitters. - It already supports popover previews, backlinks, graph view, explorer navigation, and full-text search. - It includes an `ObsidianFlavoredMarkdown` plugin, which shows direct alignment with the knowledge-base space. Quartz is compelling enough that it could be used for a fast proof of concept. The reason not to pick it as the primary foundation is not quality; it is control over architecture. Foam still needs a publishing layer for features like `foam-query`, publish permissions, and reuse of Foam core models. Once that layer exists, Astro and Starlight provide a cleaner long-term substrate for a broader website experience. Sources: - [Quartz Configuration](https://quartz.jzhao.xyz/configuration) - [Quartz Explorer](https://quartz.jzhao.xyz/features/explorer) - [Quartz Graph View](https://quartz.jzhao.xyz/features/graph-view) - [Quartz Backlinks](https://quartz.jzhao.xyz/features/backlinks) - [Quartz Popover Previews](https://quartz.jzhao.xyz/features/popover-previews) ## Docusaurus Docusaurus is a capable modern documentation platform, but it does not look like the best fit for Foam's first publishing path. It has strong support for search, versioning, internationalization, MDX, and theme customization. The issue is fit rather than capability: it is more naturally shaped for product documentation than for a wiki-like knowledge base with Foam-specific semantics. It remains a viable option for projects that want a more React-centric docs platform, but it is not the best default recommendation for Foam. Source: - [Docusaurus Documentation](https://docusaurus.io/docs) ## Recommendation The recommended direction is: 1. Use Astro as the web framework. 2. Use Starlight as the website shell. 3. Build a Foam-specific publishing layer in TypeScript. 4. Keep Markdoc optional. 5. Use Quartz as a reference point and comparison target, especially for graph, popover, backlinks, and navigation behavior. This direction gives Foam a modern, polished static site without forcing Foam to become a site generator. ## Main Architectural Takeaway The core design problem is not choosing a renderer. The core design problem is preserving Foam semantics on the web. That implies a separation of concerns: - Foam should own parsing, graph resolution, publish filtering, and content transformation. - The site framework should own rendering, navigation chrome, styling, and deployment ergonomics. That boundary is what the architecture note should lock down. --- ### User Features Backlinking (`docs/user/features/backlinking.md`) # Backlinks 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. _[📹 Watch: Understanding and using backlinks in Foam]_ ## 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]_ --- ### User Features Block Anchors (`docs/user/features/block-anchors.md`) # Block Anchors Block anchors let you link to a specific paragraph, list item, heading, or blockquote within a note — not just to the note as a whole or to a section heading. ## Adding a Block Anchor Place `^your-id` at the end of any block element. The ID can contain letters, numbers, and hyphens. The `^id` marker is hidden in the preview — it's metadata, not visible text. ### Paragraph ```markdown This is an important finding from the experiment. ^key-finding ``` Multi-line paragraphs work too — put the anchor at the end of the last line: ```markdown The first measurements were inconclusive. After repeating the experiment, results became clear. ^experiment-result ``` ### List item Place the anchor at the end of the item text. Foam anchors the entire item, including any sub-items: ```markdown - Mix dry ingredients thoroughly ^dry-step - 2 cups flour - 1 tsp salt - Add wet ingredients ^wet-step ``` To anchor an entire list, place `^id` on its own line immediately after the last item (no blank line): ```markdown - First item - Second item - Third item ^shopping-list ``` ### Heading ```markdown ## Methodology ^methodology ``` The anchor applies to the heading line itself, not the entire section below it. ### Blockquote Three placements are supported: **As the last line inside the blockquote:** ```markdown > The only way to do great work is to love what you do. > ^jobs-quote ``` **On its own line immediately after the blockquote:** ```markdown > We shall fight on the beaches, > we shall fight on the landing grounds. ^churchill-beaches ``` **After the blockquote with a blank line** (useful if your markdown formatter inserts one): ```markdown > We shall fight on the beaches, > we shall fight on the landing grounds. ^churchill-beaches ``` ### Code block Place `^id` on its own line after the closing fence. One blank line between the fence and `^id` is also accepted (useful if your markdown formatter adds one automatically): ````markdown ```python def greet(name): return f"Hello, {name}" ``` ^greet-function ```` ### Table Place `^id` on its own line after the table. One blank line is also accepted: ```markdown | Name | Score | | ----- | ----- | | Alice | 95 | | Bob | 87 | ^results-table ``` ## Linking to a Block Use `[[note-name#^blockid]]` to link directly to a block: ```markdown [[research-notes#^key-insight]] [[research-notes#^list-ref]] ``` Foam provides autocomplete for block IDs when you type `#^` inside a wikilink. You can also add display text: ```markdown [[research-notes#^key-insight|See the key insight]] ``` ## Embedding a Block Use `![[note-name#^blockid]]` to embed just that block inline: ```markdown ![[research-notes#^key-insight]] ``` Only the referenced block's content is shown — not the entire note. ## Renaming a Block ID Place your cursor on a `^blockid` anchor and press `F2` to rename it. Foam updates the anchor and all wikilinks that reference it across your workspace. ## Diagnostics Foam warns you when a block link points to a `^id` that doesn't exist in the target note. A quick-fix lets you pick from the available block IDs. If you accidentally use the same `^id` twice in one file, Foam flags the duplicate with a warning. A quick-fix replaces it with a freshly generated unique ID. ## Related - [[wikilinks]] - General linking - [[footnotes]] - Adding references and side notes - [[embeds]] - Embedding notes and blocks [wikilinks]: wikilinks.md "Wikilinks" [footnotes]: footnotes.md "Footnotes" [embeds]: embeds.md "Note Embeds" --- ### User Features Commands (`docs/user/features/commands.md`) # Foam Commands Foam has various commands that you can explore by calling the command palette and typing "Foam". In particular, some commands can be very customizable and can help with custom workflows and use cases. ## foam-vscode.create-note command This command creates a note. Although it works fine on its own, it can be customized to achieve various use cases. Here are the settings available for the command: - `notePath`: The path of the note to create. If relative it will be resolved against the workspace root. - `templatePath`: The path of the template to use. If relative it will be resolved against the workspace root. - `title`: The title of the note (that is, the `FOAM_TITLE` variable) - `text`: The text to use for the note. If also a template is provided, the template has precedence - `variables`: Variables to use in the text or template - `date`: The date used to resolve the FOAM*DATE*\* variables. in `YYYY-MM-DD` format - `onFileExists?: 'overwrite' | 'open' | 'ask' | 'cancel'`: What to do in case the target file already exists To customize a command and associate a key binding to it, open the key binding settings and add the appropriate configuration, here are some examples: - Create a note called `test note.md` with some text. If the note already exists, ask for a new name ``` { "key": "alt+f", "command": "foam-vscode.create-note", "args": { "text": "test note ${FOAM_DATE_YEAR}", "notePath": "test note.md", "onFileExists": "ask" } } ``` - Create a note following the `weekly-note.md` template. If the note already exists, open it ``` { "key": "alt+g", "command": "foam-vscode.create-note", "args": { "templatePath": ".foam/templates/weekly-note.md", "onFileExists": "open" } } ``` ## foam-vscode.open-resource command This command opens a resource. Normally it receives a `URI`, which identifies the resource to open. It is also possible to pass in a filter, which will be run against the workspace resources to find one or more matches. - If there is one match, it will be opened - If there is more than one match, a quick pick will show up allowing the user to select the desired resource Examples: ``` { "key": "alt+f", "command": "foam-vscode.open-resource", "args": { "filter": { "title": "Weekly Note*" } } } ``` ## Link Conversion Commands Foam provides commands to convert between wikilink and markdown link formats. ### foam-vscode.convert-wikilink-to-mdlink Converts a wikilink at the cursor position to markdown link format with a relative path. Example: `[[my-note]]` → `[My Note](../path/to/my-note.md)` ### foam-vscode.convert-mdlink-to-wikilink Converts a markdown link at the cursor position to wikilink format. Example: `[My Note](../path/to/my-note.md)` → `[[my-note]]` **Usage:** 1. Place your cursor inside a wikilink or markdown link 2. Open the command palette (`Ctrl+Shift+P` / `Cmd+Shift+P`) 3. Type "Foam: Convert" and select the desired conversion command --- ### User Features Custom Markdown Preview Styles (`docs/user/features/custom-markdown-preview-styles.md`) # Custom Markdown Preview Styles Visual Studio Code allows you to use your own CSS in the Markdown preview tab. ## Instructions Custom CSS for the Markdown preview can be implemented by using the `"markdown.styles": []` setting in `settings.json`. The stylesheets can either be https URLs or relative paths to local files in the current workspace. For example, to load a stylesheet called `Style.css`, we can update `settings.json` with the following line: ``` { "markdown.styles": ["Style.css"] } ``` ## Foam elements ### Foam note & placeholder links It is possible to custom style the links to a note or placeholder. The links are an `` tag. For notes use the class `foam-note-link`, for placeholders use `foam-placeholder-link`. ### Cyclic inclusion warnings Foams offers the functionality to include other notes in your note. This will be displayed in the preview tab. Foam recognises a cyclic inclusion of notes and will display a warning when detected. The following html is used and can be custom styled using the class `foam-cyclic-link-warning`. ```html

Cyclic link detected for wikilink: ${wikilink}