silverbullet/website/🔌 Plugs.md

Silver Bullet at its core is bare bones in terms of functionality, most of its
power it gains from **plugs**.

Plugs are an extension mechanism (implemented using a library called `plugos`
that runs plug code on the server in a sandboxed v8 node.js process, and in the
browser using web workers). Plugs can hook into SB in various ways: plugs can
extend the Markdown parser and its syntax, define new commands and keybindings,
respond to various events triggered either on the server or client side, as well
as run recurring and background tasks. Plugs can even define their own extension
mechanisms through custom events. Each plug runs in its own sandboxed
environment and communicates with SB via _syscalls_ that expose a vast range of
functionality. Plugs can be loaded, unloaded and updated without having to
restart SB itself.

## Directory

<!-- #query page where type = "plug" order by name render [[template/plug]] -->

- [[🔌 Backlinks]] by **Guillermo Vayá**
  ([repo](https://github.com/Willyfrog/silverbullet-backlinks))
- [[🔌 Ghost]] by **Zef Hemel**
  ([repo](https://github.com/silverbulletmd/silverbullet-ghost))
- [[🔌 Git]] by **Zef Hemel**
  ([repo](https://github.com/silverbulletmd/silverbullet-github))
- [[🔌 Github]] by **Zef Hemel**
  ([repo](https://github.com/silverbulletmd/silverbullet-github))
- [[🔌 Mattermost]] by **Zef Hemel**
  ([repo](https://github.com/silverbulletmd/silverbullet-mattermost))
- [[🔌 Mount]] by **Zef Hemel**
  ([repo](https://github.com/silverbulletmd/silverbullet-mount))
- [[🔌 Query]] by **Silver Bullet Authors**
  ([repo](https://github.com/silverbulletmd/silverbullet))

<!-- /query -->

## How to develop your own plug

At this stage, to get started, it’s probably easiest to fork one of the existing
plugs found in the [SilverBullet github org](https://github.com/silverbulletmd),
for instance the
[github one](https://github.com/silverbulletmd/silverbullet-github).

Generally, every plug consists of a YAML manifest file named
`yourplugname.plug.yml`. It’s convenient to have a `package.json` file in your
repo to add any dependencies. One dev dependency you will definitely need is
[@plugos/plugos](https://www.npmjs.com/package/@plugos/plugos) which will supply
you with the `plugos-bundle` command, which is used to “compile” your plug YAML
file into its bundled `.plug.json` form, which Silver Bullet will be able to
load and execute.

Generally, the way to invoke `plugos-bundle` is as follows:

    plugos-bundle yourplugname.plug.yaml

This will write out a `yourplugname.plug.json` file into the same folder. For
development it’s convenient to add a `-w` flag to automatically recompile when
changes to the YAML or source files are detected.

In order to keep bundles somewhat small, a few dependencies come prebundled with
SB. A the time of this writing:

- `yaml` (a YAML reader and stringifier library)
- `@lezer/lr` (a parser library)
- `handlebars`

If you use any of these, you can add e.g. `--exclude handlebars` to _not_ have
them be included in the bundle (they will be loaded from SB itself).

Once you have a compiled `.plug.json` file you can load it into SB in a few ways
by listing it in your space’s `PLUGS` page.

For development it’s easiest to use the `file:` prefix for this, by adding this
in the `yaml` block section there to your existing list of plugs:

    - file:/home/me/git/yourplugname/yourplugname.plug.json

Reload your list of plugs via the `Plugs: Update` command (`Cmd-Shift-p` on Mac,
`Ctrl-Shift-p` on Linux and Windows) to load the list of plugs from the various
sources on the server and your browser client. No need to reload the page, your
plugs are now active.

Once you’re happy with your plug, you can distribute it in various ways:

- You can put it on github by simply committing the resulting `.plug.json` file
  there and instructing users to point to by adding
  `- github:yourgithubuser/yourrepo/yourplugname.plug.json` to their `PLUGS`
  file
- Add a release in your github repo and instruct users to add the release as
  `- ghr:yourgithubuser/yourrepo` or if they need a spcecific release
  `- ghr:yourgithubuser/yourrepo/release-name`
- You can put it on any other web server, and tell people to load it via https,
  e.g. `- https://mydomain.com/mypugname.plug.json`.

### Recommended development workflow

I develop plugs as follows: in one terminal I have `plugos-bundle -w` running at
all times, constantly recompiling my code as I change it.

I also have SB open with a `file:` based link in my `PLUGS` file.

Whenever I want to test a change, I switch to SB, hit `Cmd-Shift-p` and test if
stuff works.

Often I also have the `Debug: Show Logs` command running to monitor both server
and client logs for any errors and debug information.