When you want to build a second brain, but you also want to own your own brain.
Foam is a personal knowledge management and sharing system inspired by Roam Research, built on Visual Studio Code and GitHub.
You can use Foam for organising research, taking notes, writing long-form content and publishing it to the web (or keeping it private, if you prefer).
Foam is free, open source, and extremely extensible to suit your personal workflow. You own the information you create with Foam, and you're free to share it and collaborate on it with anyone you want.
Fun fact: This documentation was researched, written and published using Foam.
Foam is a tool that supports creating relationships between thoughts and information to help you think better.
.
Whether you want to build a Second Brain or a Zettelkasten, or you want to GTD or just go with the flow, Foam can help you organise your thoughts if you follow these simple rules:
- Create a single Foam workspace for all your knowledge and research.
- Write your thoughts in markdown documents (I like to call them Bubbles, but that might be more than a little twee). These documents should be atomic: Put things that belong together into a single document, and limit its content to that single topic. (source)
- Use Foam's shortcuts and autocompletions to link your thoughts together with Markdown links, and navigate between to explore your knowledge graph.
Foam is a like a bathtub: What you get out of it depends on what you put into it.
Like the soapy suds it's named after, Foam is mostly air. The current version of Foam was created with zero lines of code, built instead on the shoulders of giants.
The core of Foam are VS Code workspace settings that glue together recommended Code Extensions, custom settings and key bindings, optimised for writing and navigating information.
Foam helps you to:
- Focus on writing
- Create links between documents with the help of auto-complete
- Navigate between linked documents with a single click
- Generate tables of content and update them automatically
- Easily create and manage lists and check lists
- Easily push code to a git repository
To back up, collaborate on and share your content between devices, Foam pairs well with GitHub.
To publish your content, you can set it up to publish to GitHub pages with a single click, or any website hosting platform like Netlify or Vercel.
I've been using Roam Research for a while, and I've been impressed by its ability to improve the quality and productivity of my thinking.
However, Roam comes with a few downsides:
- You don't own your own data (unless you keep backups).
- Roam is an early-stage startup, and I don't want to build my knowledge-gathering practices on something that may not be around in a few years.
- You're locked to paying $15/month for a tool that you're ideally using for the rest of your life.
- As slick as it is, it can't compete with the customisability of VS Code.
- As of June 2020, the app is still slow, buggy and sometimes loses information when editing offline.
I built, and want to continue developing, Foam because I wanted to manage my personal knowledge repository using tools I feel the most comfortable with, while keeping the ownership of my own data.
Foam implements many (but not all) of Roam's features inside VS Code, providing access to:
- Full power of VS Code, such as
- Ability to customise everything about your environment (colors, fonts, keyboard shortcuts, etc.)
- Free, low lock-in hosting in any Git repository
- Keep history or the evolution of your thoughts
- Store any type of file to your knowledge base
- Host entire websites and web apps inside of your published Foam site!
- Easy publishing workflow for sharing your knowledge with others.
Foam doesn't have features in the traditional sense. Out of the box, you have access to all features of VS Code and all the recommended extensions you choose to install, but it's up to you to discover what you can do with it!
Head over to Recipes for some useful patterns and ideas, and contribute your own tips!
These instructions assume you have a GitHub account, and you have Visual Studio Code installed.
- Create a GitHub repository from foam-template
- Clone the repository and open it in VS Code
- When prompted to install recommended extensions, click Install all (or Show Recommendations if you want to review and install them one by one)
After setting up the repository, open .vscode/settings.json and edit, add or remove any settings you'd like for your Foam workspace.
After making changes, sync the back to your git repository either:
- Using the GitLens UI
- Using GitAutomator commands
Cmd+Shift+Zto stage the current file and commit it, orCmd+Shift+Ato stage all edited files and commit them, and finallyCmd+Shift+Xto push all commits
- Whatever way you prefer. It's your Foam!
To learn more about Foam, read the Recipes.
The current version of Foam is essentially a functional prototype. I am using it as my personal thinking tool in order to learn how to best use it, and I hope others will too.
However, it doesn't yet fully support the Zettelkasten method. In order to support further features such as back links between Bubbles, it may be necessary to implement our own VS Code extension, syntax and language server.
Read our Contibuting guide for how to help improve Foam, and open GitHub issues to give us feedback and ideas for new features.
Foam is built by Jani Eväkallio (@jevakallio) and all contributors.
Foam was inspired by Roam Research and the Zettelkasten methodology
Foam wouldn't be possible without Visual Studio Code and GitHub, and relies heavily on these fantastic open source extensions and all their contributors:
Foam is licensed under the MIT license.