github/foam
1
1
Fork 0
mirror of https://github.com/foambubble/foam.git synced 2026-01-10 06:28:12 -05:00
Code Issues Packages Projects Releases Wiki Activity

renamed references to branch master into main

Browse Source
This commit is contained in:
Riccardo Ferretti
2025-03-07 17:11:11 +01:00
parent 8a6551f281
commit c840070a3a
23 changed files with 107 additions and 232 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
docs/dev/contribution-guide.md
View File

@@ -1,6 +1,7 @@
---
tags: todo, good-first-task
---
# Contribution Guide
Foam is open to contributions of any kind, including but not limited to code, documentation, ideas, and feedback.
@@ -44,19 +45,19 @@ You should now be ready to start working!
Foam code and documentation live in the monorepo at [foambubble/foam](https://github.com/foambubble/foam/).
- [/docs](https://github.com/foambubble/foam/tree/master/docs): documentation and [[recipes]].
- [/docs](https://github.com/foambubble/foam/tree/main/docs): documentation and [[recipes]].
Exceptions to the monorepo are:
- The starter template at [foambubble/foam-template](https://github.com/foambubble/)
- All other [[recommended-extensions]] live in their respective GitHub repos
This project uses [Yarn workspaces](https://classic.yarnpkg.com/en/docs/workspaces/).
This project uses [Yarn workspaces](https://classic.yarnpkg.com/en/docs/workspaces/).
Originally Foam had:
- [/packages/foam-core](https://github.com/foambubble/foam/tree/ee7a8919761f168d3931079adf21c5ad4d63db59/packages/foam-core) - Powers the core functionality in Foam across all platforms.
- [/packages/foam-vscode](https://github.com/foambubble/foam/tree/master/packages/foam-vscode) - The core VS Code plugin.
- [/packages/foam-vscode](https://github.com/foambubble/foam/tree/main/packages/foam-vscode) - The core VS Code plugin.
To improve DX we have moved the `foam-core` module into `packages/foam-vscode/src/core`, but from a development point of view it's useful to think of the `foam-vscode/src/core` "submodule" as something that might be extracted in the future.
@@ -81,7 +82,7 @@ Tests live alongside the code in `src`.
This guide assumes you read the previous instructions and you're set up to work on Foam.
1. Now we'll use the launch configuration defined at [`.vscode/launch.json`](https://github.com/foambubble/foam/blob/master/.vscode/launch.json) to start a new extension host of VS Code. Open the "Run and Debug" Activity (the icon with the bug on the far left) and select "Run VSCode Extension" in the pop-up menu. Now hit F5 or click the green arrow "play" button to fire up a new copy of VS Code with your extension installed.
1. Now we'll use the launch configuration defined at [`.vscode/launch.json`](https://github.com/foambubble/foam/blob/main/.vscode/launch.json) to start a new extension host of VS Code. Open the "Run and Debug" Activity (the icon with the bug on the far left) and select "Run VSCode Extension" in the pop-up menu. Now hit F5 or click the green arrow "play" button to fire up a new copy of VS Code with your extension installed.
2. In the new extension host of VS Code that launched, open a Foam workspace (e.g. your personal one, or a test-specific one created from [foam-template](https://github.com/foambubble/foam-template)). This is strictly not necessary, but the extension won't auto-run unless it's in a workspace with a `.vscode/foam.json` file.

128
docs/dev/meeting-notes/foam-core-2020-07-11.md
View File

@@ -1,128 +0,0 @@
# Foam Core 2020-07-11
Present: @jevakallio, @riccardoferretti
### Tests
- How do we know this approach works?
- Supports renaming
- Supports searching with (attribute-x)
- Find dead links
### Getting started
- Land work to master
- Create a foam-core package
-
### Open questions
- How should writing to files work
- What if affected notes have unsaved changes
### Graph methods
- get all
- search by
- tag
- free text
- [[todo]]: how do vs code search editors work? are they pluggable? what do they need?
- find dead links
- for linters
- serialize/toJSON (for visualizers)
- subscribe to changes
- find if a link exists (and which link) in a given row / column position + return it's start and end position - this would probably be needed e.g. to CTRL-hovering to work properly
### Node methods
- rename node and all links to that node
- get links
- forward links (for link lists)
- backlinks (with surrounding context)
### Node definition
What do we need the node (and edge metadata) to contain:
- `id`: tbd
- should be unique, needs some kind of unique gen function
- should be reconstructable even if links are not updated every time
- what happens during rename? is reparenting the graph going to be hard?
- do id's need to be persistent, or can we create them per in-memory session, keep them stable despite renames, and then next session generate a new id?
- Ideally should be a path to file, so it's easy to look up from the graph by id for renaming
- `type`: Note | Image | etc
- `title`: can be read from markdown title or frontmatter metadata
- `path`: full path to file, relative to workspace (graph) root
- `links`:
- `id`: File to link to
- `text`: The link label
- `type` markdown | mediawiki | image | http
- `section`: : Anchor link to a heading in target note, if we want to add support for linking to sections
- `block` (ref)
- Positional data from AST?
- `tags`
### Markdown layer
- `source`: raw markdown (rename?)
- `ast`: raw markdown ast
- `checksum`: if we do caching
### Link text
// some-file.md
// # Some File
Write -> Store on disk
[[Some File]] -> [Some File](some-file.md)
Editing
[Some File](some-file.md)
On disk (could be solved by migration)
[[some-file]]
[[Some File]]
- docs/index.md -> Index
- notes/index.md -> Index
[[Index]]
[[Index | notes/index.md]]
[Index] docs/index.md
[Index | notes/index.md]: notes/index.md
[[Some File | path/to/some-file.md]]
Do we apply any constraints:
- `[[file-name-without-extension]]`
- `[[file-name-with-extension.md]]`
- `[[Title Cased File Name]]`
Not supported by Markdown Notes:
- `[[path/to/file-name.md]]` - Just use markdown links
- `[[Target Note Title]]`
Issues:
- Name clashes in directories
- Name clashes between extensions
- Renaming
- Change filename/title needs to reflect everywhere
- Orphaning
- If we can't rely on in-memory process to rename things correctly while changes happen (e.g. file is renamed, moved, deleted, or titled) <ref id="1" />
Solving this issue is necessarily heuristic. We could try to write smart solutions, plus a linter for orphans
How others solve this:
- Unique ids -- could support optionally as part of file name or front matter metadata. Should not be required.
[//begin]: # "Autogenerated link references for markdown compatibility"
[todo]: ../todo.md "Todo"
[Index]: ../../index.md "Foam"
[//end]: # "Autogenerated link references"

4
docs/dev/proposals/link-reference-definition-improvements.md
View File

@@ -66,8 +66,9 @@ The potential solution:
- For edit-time
- Make edit-time link reference definition generation optional via user settings. They should be on by default, and generating valid markdown links with a relative path to a `.md` file.
- Make format of the link reference definition configurable (whether to include '.md' or not)
- Out of recommended extensions, currently only "markdown links" doesn't support them (?). However even its [code](https://github.com/tchayen/markdown-links/blob/master/src/parsing.ts#L25) seems to include wikilink parser, so it might just be a bug?
- Out of recommended extensions, currently only "markdown links" doesn't support them (?). However even its [code](https://github.com/tchayen/markdown-links/blob/main/src/parsing.ts#L25) seems to include wikilink parser, so it might just be a bug?
- For build-time
- To satisfy mutually incompatible constraints between GitHub UI, VSCode UI, and GitHub Pages, we should add a pre-processing/build step for pushing to GitHub Pages.
- This would be a GitHub action (or a local script, ran via foam-cli) that outputs publish-friendly markdown format for static site generators and other publishing tools
- This build step should be pluggable, so that other transformations could be ran during it
@@ -125,6 +126,7 @@ The potential solution:
- With Foam repo, just use edit-time link reference definitions with '.md' extension - this makes the links work in the GitHub UI
- Have publish target defined for GitHub pages, that doesn't use '.md' extension, but still has the link reference definitions. Generate the output into gh-pages branch (or separate repo) with automation.
- This naturally requires first removing the existing link reference definitions during the build
- Other
- To clean up the search results, remove link reference definition section guards (assuming that these are not defined by the markdown spec). Use unifiedjs parse trees to identify if there's missing (or surplus) definitions (check if they are identified properly by the library), and just add the needed definitions to the bottom of the file (without guards) AND remove them if they are not needed (anywhere from the file).

2
docs/dev/proposals/roadmap.md
View File

@@ -16,7 +16,7 @@ If you want to pick up work in this category, you should have a plan on how long
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/tree/master/packages/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!_
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/tree/main/packages/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.**

6
docs/dev/releasing-foam.md
View File

@@ -1,16 +1,16 @@
# Releasing Foam
1. Get to the latest code
- `git checkout master && git fetch && git rebase`
- `git checkout main && git fetch && git rebase`
2. Sanity checks
- `yarn reset`
- `yarn test`
3. Update change log
3. Update change log
- `./packages/foam-vscode/CHANGELOG.md`
- `git add *`
- `git commit -m"Preparation for next release"`
4. Update version
- `$ yarn version-extension <version>` (where `version` is `patch/minor/major`)
- `$ yarn version-extension <version>` (where `version` is `patch/minor/major`)
5. Package extension
- `$ yarn package-extension`
6. Publish extension