Foam
T
Foam

    Foam Local Plugins

    Foam can use workspace plugins to provide customization for users.

    ATTENTION

    This feature is experimental and its API subject to change. Local plugins can execute arbitrary code on your machine - ensure you trust the content of the repo.

    Goal

    Here are some of the things that we could enable with local plugins in Foam:

    • extend the document syntax to support roam style attributes (e.g. stage:: seedling)
    • automatically add tags to my notes based on the location in the repo (e.g. notes in /areas/finance will automatically get the #finance tag)
    • add a new CLI command to support some internal use case or automate import/export
    • extend the VSCode experience to support one's own workflow, e.g. weekly note, templates, extra panels, foam model derived TOC, ... all without having to write/deploy a VSCode extension

    How to enable local plugins

    Plugins can execute arbitrary code on the client's machine. For this reason this feature is disabled by default, and needs to be explicitly enabled.

    To enable the feature:

    • create a ~/.foam/config.json file
    • add the following content to the file
    {
 "experimental": {
  "localPlugins": {
   "enabled": true
  }
 }
}

    For security reasons this setting can only be defined in the user settings file. (otherwise a malicious repo could set it via its ./foam/config.json)

    • [[todo]] an additional security mechanism would involve having an explicit list of whitelisted repo paths where plugins are allowed. This would provide finer grain control over when to enable or disable the feature.

    Technical approach

    When Foam is loaded it will check whether the experimental local plugin feature is enabled, and in such case it will:

    • check .foam/plugins directory.
      • each directory in there is considered a plugin
      • the layout of each directory is
        • index.js contains the main info about the plugin, specifically it exports:
          • name: string the name of the plugin
          • description?: string the description of the plugin
          • parser?: ParserPlugin an object that interacts with the markdown parsing phase

    Currently for simplicity we keep everything in one file. We might in the future split the plugin by domain (e.g. vscode, cli, core, ...)

    Show Graph Visualisation