mirror of https://github.com/foambubble/foam.git synced 2026-04-24 03:01:01 -04:00

Files

Riccardo 32e443bbae Refactor core workspace model (#467 )

* added workspace WIP

* workspace supports resources

* uri check more lenient (was causing bug by not recognizing some objects)

* added placeholder resource type

* consolidated code in FoamWorkspace and added more tests

* updated all modules to use FoamWorkspace

* fixed FoamWorkspace.getConnections function
when links or backlinks are not present it no longer adds `undefined` to the connection list

* fix in workspace handling of direct links

* consolidated id/name generation functions

* added test for wikilink resolution when several notes have same filename

* removed reference to graphMiddleware in foam-local-plugins doc
graph middleware won't be supported with the `FoamWorkspace`. Support for the markdown provider remains

* removed support for graph middleware, graphlib dependency, and old note-graph implementation

2021-02-17 21:36:29 +01:00

2.4 KiB

Raw Blame History

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

2.4 KiB Raw Blame History