1
0
silverbullet/website/🔌 Plugs.md
2023-08-29 21:17:29 +02:00

96 lines
5.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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]] thats 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 page where type = "plug" and uri = null order by name render [[template/plug]] -->
* [[🔌 Directive]]
* [[🔌 Editor]]
* [[🔌 Emoji]]
* [[🔌 Index]]
* [[🔌 Markdown]]
* [[🔌 Share]]
* [[🔌 Tasks]]
* [[🔌 Template]]
<!-- /query -->
## Third-party plugs
These plugs are written either by third parties or distributed separately from the main SB distribution:
<!-- #query page where type = "plug" and uri != null order by name render [[template/plug]] -->
* [[🔌 Backlinks]] by **Guillermo Vayá** ([repo](https://github.com/silverbulletmd/silverbullet-backlinks))
* [[🔌 Ghost]] by **Zef Hemel** ([repo](https://github.com/silverbulletmd/silverbullet-ghost))
* [[🔌 Git]] by **Zef Hemel** ([repo](https://github.com/silverbulletmd/silverbullet-git))
* [[🔌 Github]] by **Zef Hemel** ([repo](https://github.com/silverbulletmd/silverbullet-github))
* [[🔌 Graph View]] by **Bertjan Broeksema** ([repo](https://github.com/silverbulletmd/silverbullet-graphview))
* [[🔌 KaTeX]] by **Zef Hemel** ([repo](https://github.com/silverbulletmd/silverbullet-katex))
* [[🔌 Mattermost]] by **Zef Hemel** ([repo](https://github.com/silverbulletmd/silverbullet-mattermost))
* [[🔌 Mermaid]] by **Zef Hemel** ([repo](https://github.com/silverbulletmd/silverbullet-mermaid))
* [[🔌 Serendipity]] by **Pantelis Vratsalis** ([repo](https://github.com/m1lt0n/silverbullet-serendipity))
* [[🔌 Twitter]] by **SilverBullet Authors** ([repo](https://github.com/silverbulletmd/silverbullet-twitter))
<!-- /query -->
## 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 spaces `PLUGS` page.
For development its easiest to simply copy the `.plug.js` file into your spaces `_plug/` folder:
```shell
cp myplug.plug.js ~/myspace/_plug/
```
Within seconds (watch your browsers 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 browsers JavaScript console.
## Distribution
Once youre 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`.