79 lines
3.9 KiB
Markdown
79 lines
3.9 KiB
Markdown
SilverBullet 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’s part of the silverbullet repo) that runs “plug” code in the browser using [web workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers).
|
||
|
||
Plugs can hook into SB in various ways:
|
||
|
||
* Extend the Markdown parser and its syntax
|
||
* Define new commands and keybindings
|
||
* Respond to various events triggered either on the server or client-side
|
||
* Run recurring and background tasks.
|
||
* 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.
|
||
|
||
Plugs are distributed as self-contained JavaScript bundles (ending with `.plug.js`). Upon boot, SB will load all core plugs bundled with SB itself (listed below), as well as any additional plugs stored in the `_plug` folder in your space. Typically, management of plugs in the `_plug` folder is done using [[🔌 Core/Plug Management]].
|
||
|
||
## Core plugs
|
||
These plugs are distributed with SilverBullet and are automatically enabled:
|
||
```query
|
||
plug where uri = null order by name render [[template/plug]]
|
||
```
|
||
## Third-party plugs
|
||
These plugs are written either by third parties or distributed separately from the main SB distribution:
|
||
```query
|
||
plug where uri != null order by name render [[template/plug]]
|
||
```
|
||
|
||
## How to develop your own plug
|
||
The easiest way to get started is to click the “Use this template” on the [silverbullet-plug-template](https://github.com/silverbulletmd/silverbullet-plug-template) repo.
|
||
|
||
Generally, every plug consists of a YAML manifest file named `yourplugname.plug.yml`. This file defines all functions that form your plug. To be loadable by SilverBullet (or any PlugOS-based system for that matter), it needs to be compiled into a JSON bundle (ending with `.plug.json`).
|
||
|
||
Generally, the way to do this is to run `silverbullet plug:compile` as follows:
|
||
|
||
```shell
|
||
silverbullet plug:compile yourplugname.plug.yaml
|
||
```
|
||
|
||
During development, you may want to compile plugs in debug mode, which will not minify them and generate source maps:
|
||
|
||
```shell
|
||
silverbullet plug:compile --debug yourplugname.plug.yaml
|
||
```
|
||
|
||
If you use the plug template, this command is wrapped in your `deno.jsonc` file, so you can just run either:
|
||
|
||
```shell
|
||
deno task build
|
||
```
|
||
|
||
to build it once, or
|
||
|
||
```shell
|
||
deno task watch
|
||
```
|
||
|
||
to build it and rebuild it when files are changed. This will write a `yourplugname.plug.js` file into the same folder.
|
||
|
||
Once you have a compiled `.plug.js` 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 simply copy the `.plug.js` file into your space’s `_plug/` folder:
|
||
|
||
```shell
|
||
cp myplug.plug.js ~/myspace/_plug/
|
||
```
|
||
|
||
Within seconds (watch your browser’s JavaScript console), your plug should be picked up, synced to your browser and loaded. No need to even reload the page.
|
||
|
||
## Debugging
|
||
Since plugs run in your browser, you can use the usual browser debugging tools. When you console.log things, these logs will appear in your browser’s JavaScript console.
|
||
|
||
## Distribution
|
||
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.js` file there and instructing users to point to by adding
|
||
`- github:yourgithubuser/yourrepo/yourplugname.plug.js` 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 specific 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.js`.
|