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

Remove duplicate markdown files, moved to /docs

Browse Source
This commit is contained in:
Jani Eväkallio
2020-07-04 20:36:34 +01:00
parent 7b796cb583
commit bc486625f6
68 changed files with 0 additions and 1470 deletions
Download Patch File Download Diff File Expand all files Collapse all files

0
license → LICENSE
View File

2
_config.yml
View File

@@ -1,2 +0,0 @@
title: Foam
google_analytics: "UA-171027939-1"

23
_layouts/home.html
View File

@@ -1,23 +0,0 @@
---
layout: default
---
<script async defer src="https://buttons.github.io/buttons.js"></script>
{{ content }}
<script type="text/javascript">
// Hack: Replace page-link with "Page Title"
document.querySelectorAll(".markdown-body a[title]").forEach((a) => {
a.innerText = a.title;
});
document.querySelectorAll(".github-only").forEach((el) => {
el.remove();
});
var duplicateHeading = document.querySelector("h1:not(#foam)");
if (duplicateHeading && duplicateHeading.remove) {
duplicateHeading.remove();
}
</script>

16
_layouts/page.html
View File

@@ -1,16 +0,0 @@
---
layout: default
---
{{ content }}
<script type="text/javascript">
// Hack: Replace page-link with "Page Title"
document.querySelectorAll(".markdown-body a[title]").forEach((a) => {
a.innerText = a.title;
});
document.querySelectorAll(".github-only").forEach((el) => {
el.remove();
});
</script>

57
assets/css/style.scss
View File

@@ -1,57 +0,0 @@
---
---
@import "{{ site.theme }}";
a {
color: #3300ff;
}
.markdown-body {
max-width: 800px;
font-size: 16px;
}
.markdown-body p {
font-size: 16px;
line-height: 1.9em;
margin-bottom: 1.2em;
}
.markdown-body li {
line-height: 1.9em;
}
input.task-list-item-checkbox {
margin-right: 4px;
}
img[src*="demo"] {
border: 1px #eee solid;
-webkit-box-shadow: 4px 4px 16px 0px rgba(50, 50, 50, 0.1);
-moz-box-shadow: 4px 4px 16px 0px rgba(50, 50, 50, 0.1);
box-shadow: 4px 4px 16px 0px rgba(50, 50, 50, 0.1);
}
@media only screen and (min-width: 1170px) {
img[src*="demo"] {
max-width: 130%;
margin-left: -15%;
margin-top: 20px;
margin-bottom: 20px;
}
}
h1,
h2,
h3,
h4,
h5,
blockquote {
font-family: Constantia, "Lucida Bright", Lucidabright, "Lucida Serif", Lucida,
"DejaVu Serif", "Bitstream Vera Serif", "Liberation Serif", Georgia, serif;
}
.github-only {
display: none;
}

BIN
assets/images/foam-features-dark-mode-demo.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 944 KiB

BIN
assets/images/foam-navigation-demo.gif
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 3.3 MiB

BIN
assets/images/readme-demo.gif
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 6.3 MiB

11
automatic-git-syncing.md
View File

@@ -1,11 +0,0 @@
# Automatic Git Syncing (stub)
**[[todo]] This [[roadmap]] item needs more specification work.**
If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
[//begin]: # "Autogenerated link references for markdown compatibility"
[todo]: todo "Todo"
[roadmap]: roadmap "Roadmap"
[//end]: # "Autogenerated link references"

14
backlinking.md
View File

@@ -1,14 +0,0 @@
# Backlinking
When using [[wiki-links]], you can find all notes that link to a specific note in the [VS Code Markdown Notes](https://marketplace.visualstudio.com/items?itemName=kortina.vscode-markdown-notes) **Backlinks Explorer**
- Run `Cmd` + `Shift` + `P` (`Ctrl` + `Shift` + `P` for Windows), type "backlinks" and run the **Explorer: Focus on Backlinks** view.
- Keep this pane always visible to discover relationships between your thoughts
- You can drag the backlinks pane to a different section in VS Code if you prefer.
- Finding backlinks in published Foam workspaces via [[materialized-backlinks]] is on the [[roadmap]] but not yet implemented.
[//begin]: # "Autogenerated link references for markdown compatibility"
[wiki-links]: wiki-links "Wiki Links"
[materialized-backlinks]: materialized-backlinks "Materialized Backlinks"
[roadmap]: roadmap "Roadmap"
[//end]: # "Autogenerated link references"

10
block-references.md
View File

@@ -1,10 +0,0 @@
# Block References (stub)
**[[todo]] This [[roadmap]] item needs more specification work.**
If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
[//begin]: # "Autogenerated link references for markdown compatibility"
[todo]: todo "Todo"
[roadmap]: roadmap "Roadmap"
[//end]: # "Autogenerated link references"

16
build-vs-assemble.md
View File

@@ -1,16 +0,0 @@
# Build vs Assemble
The Foam prototype is built by assembling third-party extensions, which seems like a good strategy because
- It supports picking and mixing of tools and workflows
- Less code to write an maintain
But there's also a bunch of roadmap items that are hard to implement this way, as the third party plugins don't do exactly what we want them to do (e.g. Markdown All In One is not compatible with [[referencing-notes-by-title]].
Overall, we should strive to build big things from small things. Focused, interoperable modules are better, because they allow users to pick and mix which features work for them. A good example of why this matters is the Markdown All In One extension we rely on: While it provides many of the things we need, a few of its features are incompatible with how I would like to work, and therefore it becomes a limiter of how well I can improve my own workflow.
However, there becomes a point where we may benefit from implementing a centralised solution, e.g. a syntax, an extension or perhaps a VSCode language server. As much as possible, we should allow users to operate in a decentralised manner.
[//begin]: # "Autogenerated link references for markdown compatibility"
[referencing-notes-by-title]: referencing-notes-by-title "Referencing notes by title"
[//end]: # "Autogenerated link references"

11
cli.md
View File

@@ -1,11 +0,0 @@
# Command Line Interface (stub)
**[[todo]] This [[roadmap]] item needs more specification work.**
If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
[//begin]: # "Autogenerated link references for markdown compatibility"
[todo]: todo "Todo"
[roadmap]: roadmap "Roadmap"
[//end]: # "Autogenerated link references"

134
code-of-conduct.md
View File

@@ -1,134 +0,0 @@
# 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 `jani.evakallio+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
https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
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
https://www.contributor-covenant.org/faq. Translations are available at
https://www.contributor-covenant.org/translations.
[//begin]: # "Autogenerated link references for markdown compatibility"
[todo]: todo "Todo"
[//end]: # "Autogenerated link references"

7
contributing.md
View File

@@ -1,7 +0,0 @@
# Contributing
Head over to the [[contribution-guide]]. `CONTRIBUTING.md` file name is blocklisted on GitHub pages, and doesn't appear in the [rendered output](https://foambubble.github.io/foam).
[//begin]: # "Autogenerated link references for markdown compatibility"
[contribution-guide]: contribution-guide "Contribution Guide"
[//end]: # "Autogenerated link references"

27
contribution-guide.md
View File

@@ -1,27 +0,0 @@
# Contribution Guide
> [[todo]] [[good-first-task]] This contribution guide itself could be improved 😅
Foam is open to contributions of any kind, including but not limited to code, documentation, ideas and feedback. Here's how to get started on contributing to Foam:
- Use Foam for yourself, figure out what could be improved.
- Check out [[roadmap]] to see what's already in the plans. I have thoughts about how to implement some of these, but open to ideas and code contributions!
- Read about our [[principles]] to understand Foam's philosophy and direction
- Read and act in accordance of our [[code-of-conduct]].
- Feel free to open [GitHub issues](https://github.com/foambubble/foam/issues) to give me feedback and ideas for new features.
- Submit improvements as pull requests in the following repositories:
- Documentation and [[recipes]] at [foambubble/foam](https://github.com/foambubble/foam)
- To the starter template at [foambubble/foam-template](https://github.com/foambubble/foam-template)
- To the core VSCode plugin at [foambubble/foam-vscode](https://github.com/foambubble/foam-vscode)
- To future Foam automations at [foambubble/foam-workspace-manager](https://github.com/foambubble/foam-workspace-manager) (though at the moment this is probably too early to contribute to, as there's no architecture in place)
- Any other of the [[recommended-extensions]] in their respective GitHub repos.
[//begin]: # "Autogenerated link references for markdown compatibility"
[todo]: todo "Todo"
[good-first-task]: good-first-task "Good First Task"
[roadmap]: roadmap "Roadmap"
[principles]: principles "Principles"
[code-of-conduct]: code-of-conduct "Code of Conduct"
[recipes]: recipes "Recipes"
[recommended-extensions]: recommended-extensions "Recommended Extensions"
[//end]: # "Autogenerated link references"

11
creating-a-new-language.md
View File

@@ -1,11 +0,0 @@
## Creating a new language
What if we created a new language that made it more ergonomic to use VS Code as a Foam workspace
- Based on markdown
- Could leverage mdx?
- Shortcuts, like links between pages
- Downside: Not markdown compatible, not so good for other tools
- Could it be a markdown superset?
- Or a language that transpiles to markdown and back, so it can be edited in "Foam" format and committed in MD so it's viewable on GH as markdown
- How imporant is it that links are navigable on GH? I guess it is

11
creating-new-notes.md
View File

@@ -1,11 +0,0 @@
# Creating New Notes
- Write out a new `[[wiki-link]]` and `Cmd` + `Click` to create a new file.
- `Cmd` + `Shift` + `P` (`Ctrl` + `Shift` + `P` for Windows), execute `New Note` from [VS Code Markdown Notes](<(https://marketplace.visualstudio.com/items?itemName=kortina.vscode-markdown-notes)>) and enter a **Title Case Name** to create `title-case-name.md`
- Add a keyboard binding to make creating new notes easier.
- You shouldn't worry too much about categorising your notes. You can always [[search-for-notes]], and explore them using the [[graph-visualisation]].
[//begin]: # "Autogenerated link references for markdown compatibility"
[search-for-notes]: search-for-notes "Search for Notes"
[graph-visualisation]: graph-visualisation "Graph visualisation"
[//end]: # "Autogenerated link references"

10
customising-styles.md
View File

@@ -1,10 +0,0 @@
# Customising Styles
You can edit `assets/css/style.scss` to change how published pages look.
[[todo]] [[good-first-task]]
[//begin]: # "Autogenerated link references for markdown compatibility"
[todo]: todo "Todo"
[good-first-task]: good-first-task "Good First Task"
[//end]: # "Autogenerated link references"

21
daily-notes.md
View File

@@ -1,21 +0,0 @@
# Daily notes (stub)
**[[todo]] This [[roadmap]] item needs more specification work.**
If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
## Notes
Daily notes is a Zettelkasten methodology for journaling your thoughts and keeping track of the evolution of your thoughts. We should support it.
## Ideas
- Hotkey for creating daily note instead of auto creating? I don't like how Roam creates empty notes.
- Browsing daily notes could be tricky. Maybe we could do it with just back links and creating a daily file with a reference to a "Journal page" that then links to all the daily entries.
- If files were named in alphabetic sortable order, and back links would display in reverse order, newest would always come on top
- Is this a use case for a directory?
[//begin]: # "Autogenerated link references for markdown compatibility"
[todo]: todo "Todo"
[roadmap]: roadmap "Roadmap"
[//end]: # "Autogenerated link references"

18
diagrams-in-markdown.md
View File

@@ -1,18 +0,0 @@
# Diagrams in Markdown
You can use VS Code plugins such as [Mermaid](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-mermaid) to draw and preview diagrams in your content.
⚠️ Be aware that Mermaid diagrams don't automatically get rendered in published Foams in [[github-pages]], and would require you to eject to another static site generation approach that supports Mermaid plugins.
---
[[todo]] [[good-first-task]] **Help improve this recipe!**
[[todo]] [[good-first-task]] Suggestions for alternative diagramming approaches welcome
[//begin]: # "Autogenerated link references for markdown compatibility"
[github-pages]: github-pages "Github Pages"
[good-first-task]: good-first-task "Good First Task"
[todo]: todo "Todo"
[contribution-guide]: contribution-guide "Contribution Guide"
[//end]: # "Autogenerated link references"

38
foam-file-format.md
View File

@@ -1,38 +0,0 @@
# Foam File Format
This file is an example of a valid Foam file. Essentially it's just a markdown file with a bit of additional support for mediawiki-style `[[wiki-links]]`.
Here are a few specific constraints, mainly because our tooling is a bit fragmented. Most of these should be eventually lifted, and our requirement should just be "Markdown with `[[wiki-links]]`:
- **It needs to have a single top level `# Heading`.**
- This will be used as document title.
- **File name should not contain spaces,** e.g. `foam-file-format.md` is a valid name, but `Foam File Format.md` is not.
- This is a temporary limitation and will be lifted in future versions.
- Technically this actually works already, but may have some edge cases you don't want to deal with if you can avoid it.
- **File name should have extension `.md` or `.markdown`**
- This is a temporary limitation and will be lifted in future versions.
- At least `.mdx` will be supported, but ideally we'll support any file that you can map to `Markdown` language mode in VS Code
- **In addition to normal Markdown Links syntax you can use `[[media-wiki]]` links.**
- When you do, the [foam-vscode](https://github.com/foambubble/foam-vscode) extension will automatically generate [Markdown Link Reference Definitions](https://spec.commonmark.org/0.29/#link-reference-definitions) at the bottom of the file.
- Here's an example:
- [[wiki-links]]
- [[github-pages]]
- This will generate the following references:
```md
[wiki-links]: wiki-links "Wiki Links"
[github-pages]: github-pages "Github Pages"
```
- The three components are `[link-label]: link-target "Link Title"
- **link label:** The link text to match in the surrounding markdown document. This matches the inner bracket of the double-bracketed `[[wiki-link]]` notation
- **link destination** The target of the matched link
- Right now we generate link destinations without file extension. This is a choice, see [discussion here](https://foambubble.github.io/foam/wiki-links#why-dont-wiki-links-work-on-github).
- **"Link Title"** Optional title for link (The Foam template has a snippet of JavaScript to replace this on the website at runtime)
- Open the [raw markdown](https://raw.githubusercontent.com/foambubble/foam/master/foam-file-format.md) to see them at the bottom of this file
- In the near future, these can be batch generated for all workspace files (WIP)
- For the time being, if you want to get [[wiki-links]] support across all files, you'll need to generate the link reference definitions yourself.
- If you end up writing a batch job for this, please share your solution, as this is something we'll need to implement soon!
[//begin]: # "Autogenerated link references for markdown compatibility"
[wiki-links]: wiki-links "Wiki Links"
[github-pages]: github-pages "Github Pages"
[//end]: # "Autogenerated link references"

11
foam-linter.md
View File

@@ -1,11 +0,0 @@
# Foam Linter (stub)
**[[todo]] This [[roadmap]] item needs more specification work.**
If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
[//begin]: # "Autogenerated link references for markdown compatibility"
[todo]: todo "Todo"
[roadmap]: roadmap "Roadmap"
[//end]: # "Autogenerated link references"

10
git-flows-for-teams.md
View File

@@ -1,10 +0,0 @@
# Git Flows for Teams (stub)
**[[todo]] This [[roadmap]] item needs more specification work.**
If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
[//begin]: # "Autogenerated link references for markdown compatibility"
[todo]: todo "Todo"
[roadmap]: roadmap "Roadmap"
[//end]: # "Autogenerated link references"

18
git-integration.md
View File

@@ -1,18 +0,0 @@
# Git integration
There are (too) many ways to commit your changes to source control:
- Using VS Code's own git integration
- Using GitLens (included in Foam for inline blame)
- Whatever way you like to do it (CLI?)
The quick and easy way is to use the Git: Commit All command after editing files. The default Foam workspace settings will stage & sync all of your changes to the remote:
- `Cmd` + `Shift` + `P` (`Ctrl` + `Shift` + `P` for Windows), execute `Git: Commit All`
This could be improved. [[todo]] [[good-first-task]]
[//begin]: # "Autogenerated link references for markdown compatibility"
[todo]: todo "Todo"
[good-first-task]: good-first-task "Good First Task"
[//end]: # "Autogenerated link references"

12
github-pages.md
View File

@@ -1,12 +0,0 @@
# Github Pages
- The [Foam template](https://github.com/foambubble/foam-template) is **GitHub Pages** ready, all you have to do is [turn it on in your repository settings](<(https://guides.github.com/features/pages/)>).
- The default GitHub Pages template is called [Primer](https://github.com/pages-themes/primer). See Primer docs for how to customise html layouts and templates.
- GitHub Pages is built on [Jekyll](https://jekyllrb.com/), so it supports things like permalinks, front matter metadata etc.
[[todo]] [[good-first-task]] Improve this documentation
[//begin]: # "Autogenerated link references for markdown compatibility"
[todo]: todo "Todo"
[good-first-task]: good-first-task "Good First Task"
[//end]: # "Autogenerated link references"

9
good-first-task.md
View File

@@ -1,9 +0,0 @@
# Good First Task
See the backlinks of this page for good first contribution opportunities.
[[materialized-backlinks]] would help here.
[//begin]: # "Autogenerated link references for markdown compatibility"
[materialized-backlinks]: materialized-backlinks "Materialized Backlinks"
[//end]: # "Autogenerated link references"

10
graph-in-published-workspace.md
View File

@@ -1,10 +0,0 @@
# Graph in Published Workspace (stub)
**[[todo]] This [[roadmap]] item needs more specification work.**
If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
[//begin]: # "Autogenerated link references for markdown compatibility"
[todo]: todo "Todo"
[roadmap]: roadmap "Roadmap"
[//end]: # "Autogenerated link references"

12
graph-visualisation.md
View File

@@ -1,12 +0,0 @@
# Graph visualisation
`Cmd` + `Shift` + `P` (`Ctrl` + `Shift` + `P` for Windows), type `Show graph`.
(Depends on [Markdown Links](https://marketplace.visualstudio.com/items?itemName=tchayen.markdown-links).)
![Demo of graph visualiser](assets/images/foam-navigation-demo.gif)
[//begin]: # "Autogenerated link references for markdown compatibility"
[wiki-links]: wiki-links "Wiki Links"
[todo]: todo "Todo"
[//end]: # "Autogenerated link references"

42
how-to-write-recipes.md
View File

@@ -1,42 +0,0 @@
# 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.
![Demo](assets/images/foam-navigation-demo.gif)
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]].
[//begin]: # "Autogenerated link references for markdown compatibility"
[recommended-extensions]: recommended-extensions "Recommended Extensions"
[recipes]: recipes "Recipes"
[contribution-guide]: contribution-guide "Contribution Guide"
[//end]: # "Autogenerated link references"

10
improve-default-workspace-settings.md
View File

@@ -1,10 +0,0 @@
# Improve Default Workspace Settings (stub)
**[[todo]] This [[roadmap]] item needs more specification work.**
If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
[//begin]: # "Autogenerated link references for markdown compatibility"
[todo]: todo "Todo"
[roadmap]: roadmap "Roadmap"
[//end]: # "Autogenerated link references"

11
improved-backlinking.md
View File

@@ -1,11 +0,0 @@
# Improved Backlinking (stub)
**[[todo]] This [[roadmap]] item needs more specification work.**
If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
[//begin]: # "Autogenerated link references for markdown compatibility"
[todo]: todo "Todo"
[roadmap]: roadmap "Roadmap"
[//end]: # "Autogenerated link references"

15
improved-static-site-generation.md
View File

@@ -1,15 +0,0 @@
# Improved Static Site Generation (stub)
**[[todo]] This [[roadmap]] item needs more specification work.**
If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
## Notes
- We should consider moving to gatsby, similar to [Foam Gatsby Template](https://mathieudutour.github.io/foam-gatsby-template/)
[//begin]: # "Autogenerated link references for markdown compatibility"
[todo]: todo "Todo"
[roadmap]: roadmap "Roadmap"
[//end]: # "Autogenerated link references"

35
inbox.md
View File

@@ -1,35 +0,0 @@
# Inbox
Uncategorised thoughts
- Release notes
- Automatic updates
- Foam as a (VS Code) language
- Syntax highlighting
- Autocompletion
- Get rid of mediawiki links in favor of write time tooling
- Snippets
- 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 visualisation?
- Write about the history and process of Foam
- In ways, Wallet was the first iteration of Foam-like environment
- Should we support directories?
- Some tools might get more complicated to build
- The pressure to categorize and create hierachies can become distracting
- Is there value in folderizing?
- Use case: Writing docs in a codebase
[//begin]: # "Autogenerated link references for markdown compatibility"
[roadmap]: roadmap "Roadmap"
[//end]: # "Autogenerated link references"

118
index.md
View File

@@ -1,118 +0,0 @@
# Foam
**Foam** is a personal knowledge management and sharing system inspired by [Roam Research](https://roamresearch.com/), built on [Visual Studio Code](https://code.visualstudio.com/) and [GitHub](https://github.com/).
You can use **Foam** for organising your research, keeping re-discoverable notes, writing long-form content and, optionally, publishing it to the web.
**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.
<div class="website-only">
<a class="github-button" href="https://github.com/foambubble/foam" data-icon="octicon-star" data-size="large" data-show-count="true" aria-label="Star foambubble/foam on GitHub">Star</a>
<a class="github-button" href="https://github.com/foambubble/foam-template" data-icon="octicon-repo-template" data-size="large" aria-label="Use this template foambubble/foam-template on GitHub">Use this template</a>
</div>
## Table of Contents
- [Foam](#foam)
- [Table of Contents](#table-of-contents)
- [How do I use Foam?](#how-do-i-use-foam)
- [What's in a Foam?](#whats-in-a-foam)
- [Getting started](#getting-started)
- [Features](#features)
- [Call To Adventure](#call-to-adventure)
- [Thanks and attribution](#thanks-and-attribution)
- [License](#license)
## How do I use Foam?
**Foam** is a tool that supports creating relationships between thoughts and information to help you think better.
![Foam kitchen sink, showing a few of the key features](assets/images/foam-features-dark-mode-demo.png)
Whether you want to build a [Second Brain](https://www.buildingasecondbrain.com/) or a [Zettelkasten](https://zettelkasten.de/posts/overview/), write a book, or just get better at long-term learning, **Foam** can help you organise your thoughts if you follow these simple rules:
1. Create a single **Foam** workspace for all your knowledge and research following the [Getting started](#getting-started) guide.
2. Write your thoughts in markdown documents (I like to call them **Bubbles**, but that might be more than a little twee). These documents should be atomic: Put things that belong together into a single document, and limit its content to that single topic. ([source](https://zettelkasten.de/posts/overview/#principles))
3. Use Foam's shortcuts and autocompletions to link your thoughts together with `[[wiki-links]]`, and navigate between them to explore your knowledge graph.
4. Get an overview of your **Foam** workspace using a [[graph-visualisation]] (⚠️ WIP), and discover relationships between your thoughts with the use of [[backlinking]].
Foam is a like a bathtub: _What you get out of it depends on what you put into it._
## What's in a Foam?
Like the soapy suds it's named after, **Foam** is mostly air.
1. The editing experience of **Foam** is powered by VS Code, enhanced by workspace settings that glue together [[recommended-extensions]] and preferences optimised for writing and navigating information.
2. To back up, collaborate on and share your content between devices, Foam pairs well with [GitHub](http://github.com/).
3. To publish your content, you can set it up to publish to [GitHub Pages](https://pages.github.com/) with zero code and zero config, or to any website hosting platform like [Netlify](http://netlify.com/) or [Vercel](https://vercel.com).
> **Fun fact**: This documentation was researched, written and published using **Foam**.
## Getting started
> ⚠️ Foam is still in preview. Expect the experience to be a little rough.
These instructions assume you have a GitHub account, and you have Visual Studio Code installed.
1. Use the [foam-template project](https://github.com/foambubble/foam-template) to generate a new repository. If you're logged into GitHub, you can just hit this button:
<a class="github-button" href="https://github.com/foambubble/foam-template/generate" data-icon="octicon-repo-template" data-size="large" aria-label="Use this template foambubble/foam-template on GitHub">Use this template</a>
(If you want to keep your thoughts to yourself, remember to set the repository private, or if you don't want to use GitHub to host your workspace at all, choose **Download as ZIP** instead of **Use this template**.)
2. [Clone the repository locally](https://help.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository) and open it in VS Code.
3. When prompted to install recommended extensions, click **Install all** (or **Show Recommendations** if you want to review and install them one by one)
After setting up the repository, open `.vscode/settings.json` and edit, add or remove any settings you'd like for your Foam workspace.
To learn more about how to use **Foam**, read the [[recipes]].
There are [[known-issues]], and I'm sure, many unknown issues! Please [report them on GitHub](http://github.com/foambubble/foam/issues)!
## Features
**Foam** doesn't have features in the traditional sense. Out of the box, you have access to all features of VS Code and all the [[recommended-extensions]] you choose to install, but it's up to you to discover what you can do with it!
![Short video of Foam in use](assets/images/foam-navigation-demo.gif)
Head over to [[recipes]] for some useful patterns and ideas!
## Call To Adventure
The goal of **Foam** is to be your personal companion on your quest for knowledge.
It's is currently about "10% ready" relative to all the features I've thought of, but I've only thought of ~1% of the features it could have, and I'm excited to learn from others.
I am using it as my personal thinking tool. By making it public, I hope to learn from others not only how to improve Foam, but also to improve how I learn and manage information.
If that sounds like something you're interested in, I'd love to have you along on the journey.
- Check out [[roadmap]] to see what's in the plans
- Read about our [[principles]] to understand Foam's philosophy and direction
- Read the [[contribution-guide]] guide to learn how to participate.
- Feel free to open [GitHub issues](https://github.com/foambubble/foam/issues) to give me feedback and ideas for new features.
## Thanks and attribution
**Foam** is built by [Jani Eväkallio](https://github.com/jevakallio) ([@jevakallio](https://twitter.com/jevakallio)).
**Foam** was inspired by [Roam Research](https://roamresearch.com/) and the [Zettelkasten methodology](https://zettelkasten.de/posts/overview)
**Foam** wouldn't be possible without [Visual Studio Code](https://code.visualstudio.com/) and [GitHub](https://github.com/), and relies heavily on our fantastic open source [[recommended-extensions]] and all their contributors:
## License
Foam is licensed under the [MIT license](license).
[//begin]: # "Autogenerated link references for markdown compatibility"
[wiki-links]: wiki-links "Wiki Links"
[graph-visualisation]: graph-visualisation "Graph visualisation"
[backlinking]: backlinking "Backlinking"
[recommended-extensions]: recommended-extensions "Recommended Extensions"
[recipes]: recipes "Recipes"
[known-issues]: known-issues "Known Issues"
[roadmap]: roadmap "Roadmap"
[principles]: principles "Principles"
[contribution-guide]: contribution-guide "Contribution Guide"
[//end]: # "Autogenerated link references"

11
key-bindings.md
View File

@@ -1,11 +0,0 @@
# Key Bindings
## [[todo]]
- [ ] Document [supported key bindings](#supported-key-bindings)
- [ ] Currently we rely on various key bindings provided by VS Code plugins. Would be nice to harmonise these
- [ ]
[//begin]: # "Autogenerated link references for markdown compatibility"
[todo]: todo "Todo"
[//end]: # "Autogenerated link references"

15
known-issues.md
View File

@@ -1,15 +0,0 @@
# Known Issues
- [ ] Aggressive autocompletion in Markdown files. You can turn `editor.quickSuggestions` off in [.vscode/settings.json].
- [ ] Reference link lists have multiple issues ([Foam for VSCode](https://marketplace.visualstudio.com/items?itemName=foam.foam-vscode))
- [ ] Reference lists don't update in the background when other files are changed
- [ ] Notes don't get removed from reference lists when notes are deleted/renamed
- [ ] Workaround: Restart VS Code
- [ ] Links are case-sensitive (should not be)
- [x] ~~[[graph-visualisation]] does not detect with wiki-links ([Markdown Links](https://marketplace.visualstudio.com/items?itemName=tchayen.markdown-links))~~
- [x] ~~wiki-links aren't searchable on website~~
- [x] ~~This is because the link styling hack in `assets/css/style.scss`~~
[//begin]: # "Autogenerated link references for markdown compatibility"
[graph-visualisation]: graph-visualisation "Graph visualisation"
[//end]: # "Autogenerated link references"

10
linking-between-published-workspaces.md
View File

@@ -1,10 +0,0 @@
# Linking between Published Workspaces (stub)
**[[todo]] This [[roadmap]] item needs more specification work.**
If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
[//begin]: # "Autogenerated link references for markdown compatibility"
[todo]: todo "Todo"
[roadmap]: roadmap "Roadmap"
[//end]: # "Autogenerated link references"

17
materialized-backlinks.md
View File

@@ -1,17 +0,0 @@
# Materialized Backlinks (stub)
**[[todo]] This [[roadmap]] item needs more specification work.**
If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
## Notes
The idea would be to automatically generate lists of backlinks (and optionally, also forward links) into the bottom of every markdown document to
- Make every link two-way navigable in published sites
- Make Foam notes more portable to different apps and long-term storage
[//begin]: # "Autogenerated link references for markdown compatibility"
[todo]: todo "Todo"
[roadmap]: roadmap "Roadmap"
[//end]: # "Autogenerated link references"

10
mdx-by-default.md
View File

@@ -1,10 +0,0 @@
# MDX by Default(stub)
**[[todo]] This [[roadmap]] item needs more specification work.**
If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
[//begin]: # "Autogenerated link references for markdown compatibility"
[todo]: todo "Todo"
[roadmap]: roadmap "Roadmap"
[//end]: # "Autogenerated link references"

11
migrating-from-obsidian.md
View File

@@ -1,11 +0,0 @@
# Migrating from Obsidian (stub)
**[[todo]] This [[roadmap]] item needs more specification work.**
If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
[//begin]: # "Autogenerated link references for markdown compatibility"
[todo]: todo "Todo"
[roadmap]: roadmap "Roadmap"
[//end]: # "Autogenerated link references"

10
migrating-from-roam.md
View File

@@ -1,10 +0,0 @@
# Migrating from Roam (stub)
**[[todo]] This [[roadmap]] item needs more specification work.**
If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
[//begin]: # "Autogenerated link references for markdown compatibility"
[todo]: todo "Todo"
[roadmap]: roadmap "Roadmap"
[//end]: # "Autogenerated link references"

11
mobile-apps.md
View File

@@ -1,11 +0,0 @@
# Mobile Apps (stub)
**[[todo]] This [[roadmap]] item needs more specification work.**
If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
[//begin]: # "Autogenerated link references for markdown compatibility"
[todo]: todo "Todo"
[roadmap]: roadmap "Roadmap"
[//end]: # "Autogenerated link references"

4
new-note-for-testing.md
View File

@@ -1,4 +0,0 @@
[//begin]: # "Autogenerated link references for markdown compatibility"
[unrelated]: unrelated "Unrelated"
[//end]: # "Autogenerated link references"

13
officially-support-alternative-templates.md
View File

@@ -1,13 +0,0 @@
# Officially Support Alternative Templates (stub)
**[[todo]] This [[roadmap]] item needs more specification work.**
If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
## Notes
[//begin]: # "Autogenerated link references for markdown compatibility"
[todo]: todo "Todo"
[roadmap]: roadmap "Roadmap"
[//end]: # "Autogenerated link references"

11
packaged-desktop-app.md
View File

@@ -1,11 +0,0 @@
# Packaged Desktop App (stub)
**[[todo]] This [[roadmap]] item needs more specification work.**
If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
[//begin]: # "Autogenerated link references for markdown compatibility"
[todo]: todo "Todo"
[roadmap]: roadmap "Roadmap"
[//end]: # "Autogenerated link references"

57
principles.md
View File

@@ -1,57 +0,0 @@
# 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. _(Work in progress, see [[roadmap]]_.
- **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. _(Work in progress, see [[roadmap]]_.
## 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](httpsL//github,com/foambubble/foam). See also: [[roadmap]] and [[contribution-guide]].
- **Foam is open source.** Feel free to fork it, improve it and remix it. Just don't sell it, as per our [license](license).
- **Foam is not Roam.** This project was inspired by Roam Research, but we're not limited by what Roam does. No idea is too big (though 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.**
[//begin]: # "Autogenerated link references for markdown compatibility"
[roadmap]: roadmap "Roadmap"
[recipes]: recipes "Recipes"
[recommended-extensions]: recommended-extensions "Recommended Extensions"
[contribution-guide]: contribution-guide "Contribution Guide"
[code-of-conduct]: code-of-conduct "Code of Conduct"
[//end]: # "Autogenerated link references"

27
publishing-pages.md
View File

@@ -1,27 +0,0 @@
# Publishing pages
Foam pages can be published.
##
## Foam site generator?
Another case of the [[build-vs-assemble]] dilemma. We could provide a better publishing experience by building a bespoke static site generator (or a gatsby plugin) that's aware of Foam conventions (backlinks etc.)
Eventually we should probably do it, as that would unlock a huge amount of power, but we should always strive to keep it optional.
At a bare minimum, Foam repos should remain valid markdown, and should be publishable by any sufficiently complete markdown to html generation tools.
Would be cool if Foam pages could be published. Some ideas here.
- [x] Easymode: Make your GitHub public
- [x] Static site generator integration, publish from GH actions to GitHub pages / Netlify etc!!!
- [ ] Add annotations to pages for setting visibility (many ways to do this)
- [ ] Public by default, and `@private` annotations
- [ ] Private by default, and `@public` annotations
- [ ] Only public `/public` folder, just move a document there, no annotation needed
- [ ] More granular access control? Email someone a link with a hash? [Testing](testing.md)
[//begin]: # "Autogenerated link references for markdown compatibility"
[build-vs-assemble]: build-vs-assemble "Build vs Assemble"
[//end]: # "Autogenerated link references"

15
publishing-permissions.md
View File

@@ -1,15 +0,0 @@
# Publishing Permissions(stub)
**[[todo]] This [[roadmap]] item needs more specification work.**
If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
## Notes
- Public and private pages
- Share specific page (with private hash)
[//begin]: # "Autogenerated link references for markdown compatibility"
[todo]: todo "Todo"
[roadmap]: roadmap "Roadmap"
[//end]: # "Autogenerated link references"

1
random-thoughts.md
View File

@@ -1 +0,0 @@
# Random thoughts

8
reading-list.md
View File

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

3
real-time-collaboration.md
View File

@@ -1,3 +0,0 @@
# Real-time Collaboration
- Can already use VS Code live share for this

97
recipes.md
View File

@@ -1,97 +0,0 @@
<!-- omit in toc -->
# Recipes
Guides, tips and strategies for getting the most out of your Foam workspace!
- [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 [[contribution-guide]]
- If you discover features not listed here, we'd love to have them! [[how-to-write-recipes]].
## Take smart notes
- Introduction to Zettelkasten [[todo]]
## Discover
- Explore your notes using [[graph-visualisation]]
- Discover relationships with [[backlinking]]
- Simulating [[unlinked-references]]
## Organise
- Using [[backlinking]] for [[reference-lists]].
## Write
- Link documents with [[wiki-links]]
- Use shortcuts for [[creating-new-notes]]
- Draw [[diagrams-in-markdown]]
- [Markdown All-in-One](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one) features [[todo]] [[good-first-task]]
- Manage checklists
- Automatic Table of Contents
- Live preview markdown
- _More..._
- VS Code Advanced Features [[todo]] [[good-first-task]]
- Focus with Zen Mode
## Version control
- Quick commits with [[git-integration]]
- Sync your GitHub repo automatically [[todo]].
## Publish
- Publish to [[github-pages]]
- Make the site your own by [[customising-styles]].
- Host your own website [[todo]]
## Collaborate
- Give your team push access to your GitHub repo [[todo]]
- Real-time collaboration via VS Code Live Share [[todo]]
- Accept patches via GitHub PRs [[todo]]
## Workflow
Workflow recipes wanted!
_See [[contribution-guide]] and [[how-to-write-recipes]]._
## Creative ideas
Creative ideas welcome!
_See [[contribution-guide]] and [[how-to-write-recipes]]._
## 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 [[contribution-guide]] and [[how-to-write-recipes]]._
[//begin]: # "Autogenerated link references for markdown compatibility"
[contribution-guide]: contribution-guide "Contribution Guide"
[wiki-links]: wiki-links "Wiki Links"
[creating-new-notes]: creating-new-notes "Creating New Notes"
[graph-visualisation]: graph-visualisation "Graph visualisation"
[backlinking]: backlinking "Backlinking"
[reference-lists]: reference-lists "Reference Lists"
[unlinked-references]: unlinked-references "Unlinked references"
[todo]: todo "Todo"
[diagrams-in-markdown]: diagrams-in-markdown "Diagrams in Markdown"
[github-pages]: github-pages "Github Pages"
[customising-styles]: customising-styles "Customising Styles"
[git-integration]: git-integration "Git integration"
[how-to-write-recipes]: how-to-write-recipes "How to Write Recipes"
[good-first-task]: good-first-task "Good First Task"
[//end]: # "Autogenerated link references"

12
recommended-extensions.md
View File

@@ -1,12 +0,0 @@
# Recommended Extensions
These extensions defined in `.vscode/extensions.json` are automatically installed when you accept the workspace's recommended extensions.
This list is subject to change. Especially the Git ones.
- [Foam for VSCode](https://marketplace.visualstudio.com/items?itemName=foam.foam-vscode) (alpha)
- [Markdown Notes](https://marketplace.visualstudio.com/items?itemName=kortina.vscode-markdown-notes)
- [Markdown Links](https://marketplace.visualstudio.com/items?itemName=tchayen.markdown-links)
- [Markdown All In One](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one)
- [Git Lens](https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens)

10
refactoring-via-language-server-protocol.md
View File

@@ -1,10 +0,0 @@
# Refactoring via Language Server Protocol (stub)
**[[todo]] This [[roadmap]] item needs more specification work.**
If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
[//begin]: # "Autogenerated link references for markdown compatibility"
[todo]: todo "Todo"
[roadmap]: roadmap "Roadmap"
[//end]: # "Autogenerated link references"

16
reference-lists.md
View File

@@ -1,16 +0,0 @@
# Reference Lists
> This Recipe is a stub.
Use [[backlinking]] for handy reference lists:
- Add links like [[recommendation]], [[book]] etc.
- Create a page by that name and use its back links to see all todo's, recommendations, etc.
- Alternatively, higlight the `[[link]]` and `Cmd`+`Shift`+`F` to find all references without creating a page.
- [[todo]]: [[materialized-backlinks]] would be very useful here.
[//begin]: # "Autogenerated link references for markdown compatibility"
[backlinking]: backlinking "Backlinking"
[todo]: todo "Todo"
[materialized-backlinks]: materialized-backlinks "Materialized Backlinks"
[//end]: # "Autogenerated link references"s"s"

34
referencing-notes-by-title.md
View File

@@ -1,34 +0,0 @@
# Referencing notes by title
- Currently we reference notes with `[Description](desription.md)` syntax.
- Pros
- Supported by all static site generators
- Supported by Markdown All in One
- Cons
- Unergonomic to write
- Knowing file name should not be important
- Makes [[unlinked-references]] harder
- Makes [[renaming-files]] harder
- Possible syntaxes
- `[Title of page]`
- Pro: Already supported by Markdown and GH Pages publishing
- Con: Possibly syntactically ambiguous
- `[[Title of page]]`
- Pros: Roam format, syntactically more specific
- Cons: Not valid Markdown?
- Trialling [VS Code Markdown Notes](https://marketplace.visualstudio.com/items?itemName=kortina.vscode-markdown-notes)
- Read also: https://kortina.nyc/essays/suping-up-vs-code-as-a-markdown-notebook/
- This works, also supports backlinks
- Breaks GitHub page generation
- `[[title_of_page.md]]
- Keep current syntax, but automate linking, e.g. a snippet/shortcut to:
- Insert `[]()` (opens file autocompletion)
- Once file is chosen in `()`, populate the description in `[]` automatically from page tite
- Pros: Compatible with Markdown All in One
- Cons: Not as sleek as other options
- Can [MDX](https://github.com/mdx-js/mdx) help us here?
[//begin]: # "Autogenerated link references for markdown compatibility"
[unlinked-references]: unlinked-references "Unlinked references"
[renaming-files]: renaming-files "Renaming files"
[//end]: # "Autogenerated link references"

10
renaming-files.md
View File

@@ -1,10 +0,0 @@
# Renaming files (stub)
**[[todo]] This [[roadmap]] item needs more specification work.**
If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
[//begin]: # "Autogenerated link references for markdown compatibility"
[todo]: todo "Todo"
[roadmap]: roadmap "Roadmap"
[//end]: # "Autogenerated link references"

6
requirements.md
View File

@@ -1,6 +0,0 @@
# Requirements
Foam tries to impose as few requirements as possible, but some constraints are necessary to build interoperable tools.
- Documents must be written in markdown (or a markdown superset like MDX, or an as-yet-unspecified hypothetical Foam format).
- Documents must start with Level 1 `# Heading`, and the content of the heading is the title of the page.

108
roadmap.md
View File

@@ -1,108 +0,0 @@
# Roadmap
Some of these items can be achieved by combining existing tools, but others may require us to build bespoke software solutions. See [[build-vs-assemble]] to understand trade-offs between these approaches. If a feature can be implemented by contributing to [[recipes]], it should.
## In progress
Items that are already being worked on. Roadmap items in this stage should have an owner.
- (Empty list)
## High priority
Items we plan on working next. Items in this stage don't need to have an owner, but before we start working on them should have enough specification that they can be picked up and worked on without having to seek consensus.
If you want to pick up work in this category, you should have a plan on how long the implementation will approximately take so we don't block progress by sitting on high priority issues.
- [[workspace-janitor]]
## Backlog
Everything else, categorised into themes. Just because something is on this list doesn't mean it'll get done. If you're interested in working on items in this category, check the [[contribution-guide]] for how to get started.
If a roadmap item is a stub, **consider** opening a [GitHub issue](https://github.com/foambubble/foam/issues) to start a conversation to avoid situations where the implementation does not fit long term vision and roadmap. _Note that this is optional. The only centralised governance in Foam is to decide what ends up in the official [template](https://github.com/foambubble/foam-template), [documentation](https://github.com/foambubble/foam) and [extension](https://github.com/foambubble/foam-vscode). You are free to build whatever you want for yourself, and we'd love if you shared it with us, but you are by no means obligated to do so!_
**When creating GitHub issues to discuss roadmap items, link them here.**
### Known issues
- [[improve-default-workspace-settings]]
- Improve [[git-integration]]
- Fix [[wiki-links]] compatibility issues
- Simplify [[foam-file-format]]
### Core features
- [[renaming-files]]
- [[unlinked-references]]
- [[daily-notes]]
- [[block-references]]
- [[improved-backlinking]]
- [[materialized-backlinks]]
- [[automatic-git-syncing]]
- [[git-flows-for-teams]]
### Publishing
- [[officially-support-alternative-templates]]
- [[improved-static-site-generation]]
- [[mdx-by-default]]
- [[search-in-published-workspace]]
- [[graph-in-published-workspace]]
- [[linking-between-published-workspaces]]
- [[publishing-permissions]]
### Platforms
- [[cli]]
- [[mobile-apps]]
- [[packaged-desktop-app]]
- [[web-editor]]
### Migration
- [[migrating-from-roam]]
- [[migrating-from-obsidian]]
- _Migration from other tools..._
### integration
- _Integrations to third party tools_...
### Wild ideas
- [[foam-linter]]
- [[refactoring-via-language-server-protocol]]
[//begin]: # "Autogenerated link references for markdown compatibility"
[build-vs-assemble]: build-vs-assemble "Build vs Assemble"
[contribution-guide]: contribution-guide "Contribution Guide"
[improve-default-workspace-settings]: improve-default-workspace-settings "Improve Default Workspace Settings (stub)"
[git-integration]: git-integration "Git integration"
[wiki-links]: wiki-links "Wiki Links"
[foam-file-format]: foam-file-format "Foam File Format"
[workspace-janitor]: workspace-janitor "Workspace Janitor (stub)"
[renaming-files]: renaming-files "Renaming files (stub)"
[unlinked-references]: unlinked-references "Unlinked references (stub)"
[daily-notes]: daily-notes "Daily notes (stub)"
[block-references]: block-references "Block References (stub)"
[improved-backlinking]: improved-backlinking "Improved Backlinking (stub)"
[materialized-backlinks]: materialized-backlinks "Materialized Backlinks (stub)"
[automatic-git-syncing]: automatic-git-syncing "Automatic Git Syncing (stub)"
[git-flows-for-teams]: git-flows-for-teams "Git Flows for Teams (stub)"
[officially-support-alternative-templates]: officially-support-alternative-templates "Officially Support Alternative Templates (stub)"
[improved-static-site-generation]: improved-static-site-generation "Improved Static Site Generation (stub)"
[mdx-by-default]: mdx-by-default "MDX by Default(stub)"
[search-in-published-workspace]: search-in-published-workspace "Search in Published Workspace (stub)"
[graph-in-published-workspace]: graph-in-published-workspace "Graph in Published Workspace (stub)"
[linking-between-published-workspaces]: linking-between-published-workspaces "Linking between Published Workspaces (stub)"
[publishing-permissions]: publishing-permissions "Publishing Permissions(stub)"
[cli]: cli "Command Line Interface (stub)"
[mobile-apps]: mobile-apps "Mobile Apps (stub)"
[packaged-desktop-app]: packaged-desktop-app "Packaged Desktop App (stub)"
[web-editor]: web-editor "Web Editor (stub)"
[migrating-from-roam]: migrating-from-roam "Migrating from Roam (stub)"
[migrating-from-obsidian]: migrating-from-obsidian "Migrating from Obsidian (stub)"
[foam-linter]: foam-linter "Foam Linter (stub)"
[refactoring-via-language-server-protocol]: refactoring-via-language-server-protocol "Refactoring via Language Server Protocol (stub)"
[recipes]: recipes "Recipes"
[//end]: # "Autogenerated link references"

7
search-for-notes.md
View File

@@ -1,7 +0,0 @@
# Search for Notes
[[todo]] VS Code search power user tips here
[//begin]: # "Autogenerated link references for markdown compatibility"
[todo]: todo "Todo"
[//end]: # "Autogenerated link references"

13
search-in-published-workspace.md
View File

@@ -1,13 +0,0 @@
# Search in Published Workspace (stub)
**[[todo]] This [[roadmap]] item needs more specification work.**
If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
## Notes
[//begin]: # "Autogenerated link references for markdown compatibility"
[todo]: todo "Todo"
[roadmap]: roadmap "Roadmap"
[//end]: # "Autogenerated link references"

23
terminology.md
View File

@@ -1,23 +0,0 @@
# Terminology
It would be good to have some shared terminology to talk about Foam concepts. Some in-group terminology is acceptable, but we shouldn't be obtuse just to be exclusive.
Here's some ideas, these are open for discussion.
## Foam (project)
The set of tools and ideas collected in this organisation.
## Foam workspace
The directory/repository where you keep all your documents.
## Bubble
Individual Foam document, written in Markdown.
## Foam blog
When you use Foam to publish content to an audience.
_Better ideas welcome._

19
todo.md
View File

@@ -1,19 +0,0 @@
# Todo
Features belong on the [[roadmap]].
- [ ] Write out Roadmap
- [ ] Isolate tasks for MLH fellows
- [ ] Create better structure for Recipes
- [ ] Connect to folks at GitHub
- [ ] Learn more about VS Code Extension APIs
- [ ] Workspace fs/events
- [ ] Reloading changes from outside vscode
- [ ] Expanding, editable snippets
For more things to do, check backlinks for Pages that annotate [[todo]].
[//begin]: # "Autogenerated link references for markdown compatibility"
[roadmap]: roadmap "Roadmap"
[todo]: todo "Todo"
[//end]: # "Autogenerated link references"

20
unlinked-references.md
View File

@@ -1,20 +0,0 @@
# Unlinked references (stub)
**[[todo]] This [[roadmap]] item needs more specification work.**
If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
## Notes
One of Roam's big features is the ability to find all instances of a reference, create a page for it and update all the references to link to the new page.
Implementing this is on the [[roadmap]], but for the time being you can achieve similar things by:
- `Cmd` + `Shift` + `F` to find all the references, e.g. "Cat food"
- `Cmd` + `Shift` + `H` to replace them with [[cat-food]].
- Click any of the references to create a new note.
[//begin]: # "Autogenerated link references for markdown compatibility"
[todo]: todo "Todo"
[roadmap]: roadmap "Roadmap"
[//end]: # "Autogenerated link references"

10
web-editor.md
View File

@@ -1,10 +0,0 @@
# Web Editor (stub)
**[[todo]] This [[roadmap]] item needs more specification work.**
If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
[//begin]: # "Autogenerated link references for markdown compatibility"
[todo]: todo "Todo"
[roadmap]: roadmap "Roadmap"
[//end]: # "Autogenerated link references"

87
wiki-links.md
View File

@@ -1,87 +0,0 @@
# Wiki Links
Foam enables you to Link pages together using `[[file-name]]` annotations.
- Both `[[file-name]]` and `[[file-name.md]]` work
- Type `[[` and start typing a file name for autocompletion.
- `Cmd` + `Click` on file name to navigate to file (`F12` also works while your cursor is on the file name)
- `Cmd` + `Click` on non-existent file to create that file in the workspace.
> If the `F12` shortcut feels unnatural you can rebind it at File > Preferences > Keyboard Shortcuts by searching for `editor.action.revealDefinition`.
## Required extensions
- [Markdown Notes](https://marketplace.visualstudio.com/items?itemName=kortina.vscode-markdown-notes) (core functionality)
- [Foam for VSCode](https://marketplace.visualstudio.com/items?itemName=foam.foam-vscode) (for Markdown compatibility)
## Markdown compatibility
The [Foam for VSCode](https://marketplace.visualstudio.com/items?itemName=foam.foam-vscode) extension automatically generates [markdown link reference definitions](https://spec.commonmark.org/0.29/#link-reference-definitions) at the bottom of the file to make wiki-links compatible with Markdown tools and parsers.
If you look at link references the bottom of any Foam workspace file that uses wiki-links, you should see an automatically generated list of references that look as follows:
```markdown
[wiki-links]: wiki-links "Wiki Links"
[other-page]: other-page "Other Page"
```
These exist to make `[[wiki-links]]` compatible with Markdown-consuming tools such as static site generators, VS Code plugins etc.
## Why don't `[[wiki-links]]` work on GitHub
> **TL;DR;** [workaround](#workaround) in the end.
If you click any of the wiki-links on GitHub web UI (such as the `README.md` of a project), you'll notice that the links break with a 404 error.
At the time of writing (June 28 2020) this is a known, but unsolved error. To understand why this is the case, we need to understand what we are trading off.
So, why don't they work on GitHub?
The three components of a [link reference definitions](https://spec.commonmark.org/0.29/#link-reference-definitions) are:
- **link label:** The link text to match in the surrounding markdown document. This matches the inner bracket of the double-bracketed `[[wiki-link]]` notation
- **link destination** The target of the matched link
- **"Link Title"** Optional title for link (The Foam template has a snippet of JavaScript to replace this on the website at runtime)
The issue is the middle **link destination** component. It's configured to point to the file name **without file extension**, i.e. "file-name" instead of "file-name.md". This is to make the GitHub Pages rendering work, because if we generated the links to `file-name.md`, the links would point to the raw markdown files instead of their generated HTML versions.
| Environment | `file-name` | `file-name.md` |
| ---------------- | ----------- | -------------- |
| **VS Code** | Works | Works |
| **GitHub pages** | Works | Breaks |
| **GitHub UI** | Breaks | Works |
So as you can see, we've prioritised GitHub Pages over GitHub Web U for the time being.
Ideally, we'd like a solution that works with both, but I haven't thought of it yet. Ideas include:
- **Writing a better static side generator that works with `file-name.md` link targets.** This is on the [[roadmap]], but for the time being GitHub Pages support is as must-have.
- **Adding a configuration setting to generate `file-name.md` link targets.** This is fine and I would accept this contribution to [foam-vscode](https://github.com/foambubble/foam-vscode), but it doesn't solve the core problem.
An acceptable solution may include one where we don't generate link reference definitions at all, but if we do, ideally, we'd like to generate `file-name.md` links since those are more standards compatible for different markdown tools.
I'm sure there's an elegant-ish solution out there. Ideas and suggestions welcome that the [tracking issue on GitHub](https://github.com/foambubble/foam/issues/16)
### Workaround
For the time being, you can use relative `[markdown links](markdown-link.md)` syntax.
**Pros:**
- This will work on all platforms.
**Cons:**
- It will break the Markdown Notes [[backlinking]] support
- Less convenient to write
## Read more
- [[foam-file-format]]
[//begin]: # "Autogenerated link references for markdown compatibility"
[wiki-links]: wiki-links "Wiki Links"
[roadmap]: roadmap "Roadmap"
[backlinking]: backlinking "Backlinking"
[foam-file-format]: foam-file-format "Foam File Format"
[//end]: # "Autogenerated link references"

14
workspace-janitor.md
View File

@@ -1,14 +0,0 @@
# Workspace Janitor (stub)
**[[todo]] This [[roadmap]] item needs more specification work.**
If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
## Notes
Implement background janitor that ensures all files are correctly linked and updated using the [VS Code Tasks](https://code.visualstudio.com/docs/editor/tasks), exposing it from foam-vscode with a [TaskProvider](https://code.visualstudio.com/api/extension-guides/task-provider)
[//begin]: # "Autogenerated link references for markdown compatibility"
[todo]: todo "Todo"
[roadmap]: roadmap "Roadmap"
[//end]: # "Autogenerated link references"