Foam
T
Foam

    Foam Core

    foam-core is a (future) package that powers the core functionality in Foam across all platforms:

    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

    • 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

    Show Graph Visualisation