# 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, ...)

[//begin]: # 'Autogenerated link references for markdown compatibility'
[todo]: ../dev/todo.md 'Todo'
[//end]: # 'Autogenerated link references'
