Skip to content

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
  • 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#