mirror of
https://github.com/foambubble/foam.git
synced 2026-04-24 03:01:01 -04:00
deb77328c0
* reorganized and updated foam docs * minor changes to vscode extension readme * added 404 page and minor changes Co-authored-by: Joe Previte <jjprevite@gmail.com>
108 lines
4.6 KiB
Markdown
108 lines
4.6 KiB
Markdown
# Foam Core
|
|
|
|
`foam-core` is a (future) package that powers the core functionality in Foam across all platforms:
|
|
|
|
- VS Code Extension
|
|
- [[workspace-janitor]]
|
|
- [[cli]]
|
|
- Future initiatives
|
|
- Visualizations
|
|
- Tag clouds
|
|
- Graph
|
|
- Should we have a package for visualisation?
|
|
- [[build-vs-assemble]]
|
|
- Not everything needs to live in the Foam repo
|
|
- Web based UI (Monaco)
|
|
|
|
`foam-core`'s primary responsibility is to build an API on top of a workspace of markdown files, which allows us to:
|
|
|
|
- Treat files as a graph, based on links
|
|
- Can be either [[wiki-links]] or relative `[markdown](links.md)` style
|
|
- We need to know about the edges (connections) as well as nodes
|
|
- What link points to what other file, etc.
|
|
- Needs to have the exact link text, e.g. even if `[[some-page]]` or `[[some-page.md]]` or `[[Some Page]]` point to the same document (`./some-page.md`), we need to know which format was used, so [[link-reference-definitions]] can be generated correctly
|
|
- Treat each file as semi-structured data
|
|
- Title, headings, lists, paragraphs, images, links, data, code
|
|
- Also, possible Foam-specific meta stuff, like "backlinks" or "block references".
|
|
- This can power advanced search features (e.g. showing entire context of paragraph in back links, find all documents)
|
|
|
|
Ideally, `foam-core` will be generic enough that in can be used by third parties to build their own tools that operate on markdown directories.
|
|
|
|
## Technical requirements
|
|
|
|
- The graph should be relatively inexpensive to compute (for running in CI, mobile etc)
|
|
- If necessary, we can implement caching inside a dot folder, but ideally not
|
|
- In memory cache already exist, can prime from disk if needed
|
|
- The graph should be mutable (or immutable but easy to deep clone) so that persistent processes (VS Code) can cheaply update it when
|
|
- Document content changes
|
|
- Links update -> Graph change
|
|
- Heading changes -> Metadata change
|
|
- Anything in the document changes, update AST for individual note
|
|
- Files are added
|
|
- Files are removed
|
|
- Files are renamed
|
|
- Aliasing, call the same thing by multiple names
|
|
- Doesn't exist yet, should we support?
|
|
- The graph should be observable (EventEmitter?) so changes can be applied
|
|
- EventEmitter w/ cross platform dependency
|
|
- Wonka (staltz's callbag)
|
|
- Can be a long term goal
|
|
- Short term fix: Just run the build fully on every change
|
|
- Ideally, the it should accept file/structure changes from the outside from some sort of event source, so we can decouple source of updates (VS Code Workspace events, file system events...)
|
|
- If this gets complicated, we can delay this for now
|
|
- We should not take on platform-specific dependencies
|
|
- Should work in any JS environment
|
|
- Written in TypeScript (preferably tsdx)
|
|
- Published to NPM
|
|
|
|
## Use cases
|
|
|
|
Here are some example use cases that the core should support. They don't need to be built into the core, but may help us design correct solutions:
|
|
|
|
- Adding and editing page content
|
|
- [[materialized-backlinks]]
|
|
- [[link-reference-definitions]] for [[wiki-links]]
|
|
- [Frontmatter](https://jekyllrb.com/docs/front-matter/)
|
|
- Finding all documents with `#tag`
|
|
- Finding all documents with instances of `[[link]]`
|
|
- Visualisations
|
|
- Full text search
|
|
|
|
- Or, if search is too expensive/complex, when given a list of file names and line/column positions from VS Code search API, can return the document context (e.g. full paragraph, preceding/following line etc)
|
|
|
|
## Collaboration
|
|
|
|
- This week
|
|
- List of things to work in order
|
|
- Provide more vision on future state
|
|
- Write about working and collaboration philosophy
|
|
- [[todo]] Prioritise roadmap
|
|
- Week of July 13
|
|
- Jani is available full time to work on this
|
|
- Janne: Write proposals, maybe more
|
|
- Riccardo: Available
|
|
|
|
## Configuration management
|
|
|
|
- Other tools may not be able to use vscode
|
|
- [[todo]] Discuss with Janne and Riccardo
|
|
|
|
## Feature comparison
|
|
|
|
Useful for knowing what needs to be supported. See [[feature-comparison]].
|
|
|
|
## Meeting notes
|
|
|
|
- [[foam-core-2020-07-11]]
|
|
|
|
[//begin]: # "Autogenerated link references for markdown compatibility"
|
|
[workspace-janitor]: ../features/workspace-janitor.md "Janitor"
|
|
[cli]: ../features/cli.md "Command Line Interface"
|
|
[build-vs-assemble]: build-vs-assemble.md "Build vs Assemble"
|
|
[wiki-links]: ../wiki-links.md "Wiki Links"
|
|
[link-reference-definitions]: ../features/link-reference-definitions.md "Link Reference Definitions"
|
|
[materialized-backlinks]: materialized-backlinks.md "Materialized Backlinks (stub)"
|
|
[todo]: todo.md "Todo"
|
|
[foam-core-2020-07-11]: ../meeting-notes/foam-core-2020-07-11.md "Foam Core 2020-07-11"
|
|
[//end]: # "Autogenerated link references"
|