SilverBullet pivot to become an offline-first PWA (#403)
This commit is contained in:
Zef Hemel
+27
-1
@@ -3,7 +3,33 @@ release.
|
||||
|
||||
---
|
||||
|
||||
## Next
|
||||
## 0.3.1
|
||||
This is a big one.
|
||||
|
||||
This is another big architectural shift warranting a major minor version bump 😉.
|
||||
|
||||
A detailed description of what happened [can be found in this PR](https://github.com/silverbulletmd/silverbullet/pull/403), the TL;DR is this:
|
||||
|
||||
* SilverBullet in this version is going **_all in_ on being an offline-capable [PWA](https://web.dev/progressive-web-apps/)**. This means the desktop and mobile applications will no longer be maintained. However, the value those applications brought (offline capability) has now been built right into the “regular web” version without the burden of having to maintain a desktop app for three platforms, and a mobile app for two.
|
||||
* Upon first launch in a modern browser, SilverBullet will now _sync a full copy of your entire space locally_ (into your browser’s IndexedDB database). When a network connection to the server is available, it will sync files with it. On the server, files are still kept as regular files, nothing changes here.
|
||||
* To avoid accidentally syncing ginormous (that’s a technical term) files to your browser, by default files > 20MB are not exposed. This puts an effective **file size limit of 20MB on files** in your space, this limit is configurable with the `--maxFileSize` flag (file a file size in MB) when running `silverbullet`.
|
||||
* After the first launch, you can disconnect from your network and your application should still be available: reload the page; restart the browser; reboot your machine, and everything still works. Note that while you’re offline, your title bar will appear in yellow to indicate this “offline” state.
|
||||
* All processing (all [[🔌 Plugs]] logic) is now running in the browser. Previously, some of this work was offloaded to the server. No more, the server is now a dumb file store. You can (and probably should) delete your `data.db` file, which was previously used to store state on the server side.
|
||||
* From a UI perspective little changes, except for a few things related to sync:
|
||||
* While SB is in an out-of-sync state, the title bar will appear yellow. This will also happen when it cannot reach the server. SB is still fully functional in this state. Once the connection is restored, all changes while offline are synced back to the server.
|
||||
* Upon initial load, a full sync will take place, which — depending on the size of your space — may take some time. Or even blow up completely, if you have a big amount of data there.
|
||||
* To reset your browser state (flush out your entire space, caches and data stores) visit the `/.client/reset.html` page, e.g. at http://localhost:3000/.client/reset.html and push the button. Note that any unsynced changes will be wiped.
|
||||
|
||||
Besides these architectural changes, a few other breaking changes were made to seize the moment:
|
||||
* **In plugs**:
|
||||
* Plugs are now distributed as `.plug.js` files instead of `.plug.json` files. This greatly improves debugability (when you compile with `--debug` you get source maps, and can even set breakpoints) and drastically decreases their file size. All existing plugs need to be recompiled using the `silverbullet plug:compile` command, and the resulting `.plug.js` file commited. Then update your [[PLUGS]] page to point to the resulting `.plug.js` files.
|
||||
* **Breaking change** in URLs (if you bookmarked them before): spaces in page names used to be replaced with `_` to look nicer, however, this was causing too many issues for people, so they’re no longer replaced and will appear as `%20` (regular URI encoding) now.
|
||||
* On mobile, you can now tap with two fingers on the editor to open the page picker, and with three fingers to open the command palette.
|
||||
* Internal note: to avoid page/file name clashes in URLs, various internal URLs have changed, FS requests are now served from `/.fs` instead of `/fs`, and all client static files from `/.client` (was root before).
|
||||
|
||||
---
|
||||
|
||||
## 0.2.14
|
||||
|
||||
* Added `Cmd-.` (Mac) and `Ctrl-.` (Linux/Windows) as an additional keyboard shortcut (to `Cmd-/`, `Ctrl-/`) for launching the command palette.
|
||||
* Improvements to dark mode by [Max Richter](https://github.com/silverbulletmd/silverbullet/pull/396)
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
You can access the “markdown web” through SilverBullet directly. The idea of the the markdown web (we really need a better name) is simple: the Internet is a messy place — tracking everywhere, tons of banners and other stuff — let’s bring it back to the basics. How about Markdown?
|
||||
|
||||
SilverBullet supports navigating this markdown web via cloud links, they’re simply wiki links that start with “💭 “. For instance: [[💭 silverbullet.md/SilverBullet]]. When you click one of these links, SilverBullet will simply pull in its content and present it to you in read-only mode (and do some clever internal link rewriting). What it does is simply fetch the link via HTTPs and postfixes the url with `.md`, so [[💭 silverbullet.md/SilverBullet]] will simply fetch [this page](https://silverbullet.md/Silver%20Bullet.md). You can access all of the SilverBullet website this way, for instance here’s the [[💭 silverbullet.md/CHANGELOG]].
|
||||
SilverBullet supports navigating this markdown web via cloud links, they’re simply wiki links that start with “💭 “. For instance: [[💭 silverbullet.md/SilverBullet]]. When you click one of these links, SilverBullet will simply pull in its content and present it to you in read-only mode (and do some clever internal link rewriting). What it does is simply fetch the link via HTTPs and postfix the url with `.md`, so [[💭 silverbullet.md/SilverBullet]] will fetch [this page](https://silverbullet.md/Silver%20Bullet.md). You can access all of the SilverBullet website this way, for instance here’s the [[💭 silverbullet.md/CHANGELOG]].
|
||||
|
||||
To publish your own content this way, simply create an `index.md` on your host (this will be fetched as the main page), and publish all the rest of your content as `.md` files along side it. That’s all there’s to it.
|
||||
To publish your own content this way, simply create an `index.md` on your host (this will be fetched as the main page), and publish all the rest of your content as `.md` files alongside it. That’s all there’s to it.
|
||||
@@ -1,26 +0,0 @@
|
||||
SilverBullet is [available as a desktop application](https://github.com/silverbulletmd/silverbullet/releases) for:
|
||||
|
||||
* macOS (Intel and ARM)
|
||||
* Windows (64bit)
|
||||
* Linux (64bit Intel)
|
||||
|
||||
Why would you want to install SilverBullet as a desktop application, as opposed to the more mature [[Server]] version?
|
||||
|
||||
1. It’s simpler to get started for most: you don’t need to install Deno, or docker or whatnot. Instead, just download a single package file, install it and _go_.
|
||||
2. It auto updates (at least on Mac and Windows), so you don’t have to worry about upgrades.
|
||||
3. It’s easier to open multiple spaces without having to fiddle manually with starting multiple [[Server]] instances on different ports.
|
||||
|
||||
Why would you _not_ want to use the Desktop version? You’re limited to only accessing your space on your desktop computer, whereas the [[Server]] simply exposes SilverBullet as a web server you can access from multiple devices. You can use [[Sync]] to work around this issue, however.
|
||||
|
||||
Convinced? [visit the releases page](https://github.com/silverbulletmd/silverbullet/releases) to go download it.
|
||||
|
||||
## How it works
|
||||
What the SilverBullet desktop app technically does is spin up a SilverBullet [[Server]] locally on a random port, and then simply point a fancy-looking window (with menus and stuff) at that local URL without all the usual browser chrome (hah, Chrome, funny).
|
||||
|
||||
What ships in the desktop package:
|
||||
|
||||
1. A copy of Deno for your operating system (this is just a single binary that’s included in the bundle).
|
||||
2. The current build of silverbullet.js (the everything-in-one bundle that you also download when you install the [[SilverBullet]] from get.silverbullet.md).
|
||||
3. [Electron](https://www.electronjs.org/)’s Chrome engine.
|
||||
|
||||
Functionally, both [[Server]] and [[Desktop]] are on par in terms of how they work and what runs on your computer (except that with the Desktop app you’re running yet another instance of Chrome — because that’s how Electron apps work).
|
||||
@@ -1,5 +0,0 @@
|
||||
You have three options to install and use SilverBullet. Pick your poison, as they say. Have a look at all three to decide what’s best for you:
|
||||
|
||||
1. [[Server]] — install SilverBullet as a web server on your local machine or network, and access it via any web browser. This is the best choice for nerds 🤓.
|
||||
2. [[Desktop]] — install SilverBullet as a desktop application, editing a local folder of files. This is the best option for casual users.
|
||||
3. [[Mobile]] — install SilverBullet as a “native” mobile application (native: as in — distributed via the app store, and with an icon on your home screen). This is the best option for people with phones. More specifically, people with phones that don’t want to access the [[Server]] via their mobile browser, or have anxiety around Internet connectivity.
|
||||
+12
-14
@@ -23,18 +23,18 @@ You will notice this whole page section is wrapped in a strange type of block. T
|
||||
Don’t believe me, check this out, here’s a list of (max 10) pages in your space ordered by last modified date, it updates (somewhat) dynamically 🤯. Create some new pages and come back here to see that it works:
|
||||
|
||||
<!-- #query page select name order by lastModified desc limit 10 -->
|
||||
|name |
|
||||
|---------------|
|
||||
|CHANGELOG |
|
||||
|Mobile |
|
||||
|Sync |
|
||||
|Getting Started|
|
||||
|SilverBullet |
|
||||
|PLUGS |
|
||||
|🔌 Plugs |
|
||||
|Desktop |
|
||||
|Server |
|
||||
|Download |
|
||||
|name |
|
||||
|-------------------------|
|
||||
|CHANGELOG |
|
||||
|🔨 Development |
|
||||
|Server |
|
||||
|Raspberry Pi Installation|
|
||||
|STYLES |
|
||||
|Getting Started |
|
||||
|Sandbox |
|
||||
|SETTINGS |
|
||||
|SilverBullet |
|
||||
|🔌 Core/Templates |
|
||||
<!-- /query -->
|
||||
|
||||
That said, the directive used wrapping this page section is `#use` which uses the content of another page as a template and inlines it. Directives recalculate their bodies in two scenarios:
|
||||
@@ -47,8 +47,6 @@ In the case of `#use` this means the body will again be replaced with the page i
|
||||
Feel free to completely remove all content on this page and make it your own, it’s just to get you started.
|
||||
|
||||
## What next?
|
||||
If you plan to use SilverBullet on multiple devices, specifically on a [[Mobile]] device. Have a look at [[Sync]].
|
||||
|
||||
If you are a visual learner, you may [enjoy this introduction video on Youtube](https://youtu.be/VemS-cqAD5k).
|
||||
|
||||
Beyond that, you can find more information about SilverBullet on its official website. You have two ways to access it:
|
||||
|
||||
@@ -0,0 +1,106 @@
|
||||
Installing SilverBullet as a (local) web server is pretty straightforward.
|
||||
|
||||
The idea is simple: you run the web server (instructions below), point your browser at it, and _go, go, go_! You can access the URL via your desktop browser but also a mobile one. You could even go _full-on YOLO_ (that’s a technical term), and install it on a public cloud server somewhere and access it that way (be sure to at least enable authentication and put SSL on top of it, though).
|
||||
|
||||
You have two options to install and run SilverBullet as a server:
|
||||
|
||||
1. Installation via Deno on your host system
|
||||
2. Running it with Docker
|
||||
|
||||
In either case, check the notes [[@tls|on using TLS]].
|
||||
|
||||
## Installation via Deno
|
||||
This consists of two steps (unless Deno is already installed — in which case we’re down to one):
|
||||
|
||||
1. [Install Deno](https://deno.land/manual/getting_started/installation) (if you’re using a Raspberry Pi, follow [[Raspberry Pi Installation]]-specific instructions)
|
||||
2. Installing SilverBullet itself (steps below)
|
||||
|
||||
### Install SilverBullet
|
||||
With Deno installed, run:
|
||||
|
||||
```shell
|
||||
deno install -f --name silverbullet -A https://silverbullet.md/silverbullet.js
|
||||
```
|
||||
|
||||
This will install `silverbullet` into your `~/.deno/bin` folder (which should already be in your `$PATH` if you followed the Deno install instructions).
|
||||
|
||||
To run SilverBullet, create a folder for your pages (it can be empty or be an existing folder with `.md` files) and run the following command in your terminal:
|
||||
|
||||
```shell
|
||||
silverbullet <pages-path>
|
||||
```
|
||||
|
||||
By default, SilverBullet will bind to port `3000`; to use a different port, use the `-p` flag.
|
||||
|
||||
For security reasons, by default, SilverBullet only allows connections via `localhost` (or `127.0.0.1`). To also allow connections from the network, pass a `-L 0.0.0.0` flag (0.0.0.0 for all connections, or insert a specific address to limit the host), ideally combined with `--user username:password` to add BasicAuth password protection. Credentials can also be specified with the `SB_USER` environment variable, `SB_USER=username:password`. If both are specified, the `--user` flag takes precedence.
|
||||
|
||||
Once downloaded and booted, SilverBullet will print out a URL to open SB in your browser. Please make note of [[@tls|the use of HTTPs]].
|
||||
|
||||
## Upgrading SilverBullet
|
||||
SilverBullet is regularly updated. To get the latest and greatest, simply run:
|
||||
|
||||
```shell
|
||||
silverbullet upgrade
|
||||
```
|
||||
|
||||
And restart SilverBullet. You should be good to go.
|
||||
|
||||
## Installing SilverBullet with Docker
|
||||
|
||||
There is a [docker image on docker hub](https://hub.docker.com/r/zefhemel/silverbullet). To use it, first create a volume to keep your space (markdown) files:
|
||||
|
||||
```shell
|
||||
docker volume create myspace
|
||||
```
|
||||
|
||||
Then, run the container, e.g., as follows:
|
||||
|
||||
```shell
|
||||
docker run -p 3000:3000 -v myspace:/space -d --name silverbullet zefhemel/silverbullet
|
||||
```
|
||||
|
||||
If you'd like to pass in additional command line arguments (e.g. `--user` to add authentication), you can just append those to the command, e.g.:
|
||||
|
||||
```shell
|
||||
docker run -p 3000:3000 -v myspace:/space -d --name silverbullet zefhemel/silverbullet --user me:letmein
|
||||
```
|
||||
|
||||
To build your own version of the docker image, run `./scripts/build_docker.sh`.
|
||||
|
||||
You can also use docker-compose if you prefer. From a silverbullet check-out run:
|
||||
|
||||
```shell
|
||||
PORT=3000 docker-compose up
|
||||
```
|
||||
|
||||
or similar.
|
||||
|
||||
To upgrade, simply pull the latest docker image (rebuilt and pushed after every commit to "main") and start the new container.
|
||||
|
||||
```shell
|
||||
docker pull zefhemel/silverbullet
|
||||
```
|
||||
|
||||
## Running SilverBullet on your network/Internet
|
||||
$tls
|
||||
For SilverBullet to be offline capable (loadable without a network connection) it needs to be accessed either via `localhost` or via TLS (a `https://`) URL. The most straightforward way to do this is by using [Caddy](https://caddyserver.com/). Caddy can automatically provision an SSL certificate for you.
|
||||
|
||||
When you’re deploying on a public server accessible to the Internet, you can do this as follows:
|
||||
|
||||
```shell
|
||||
$ sudo caddy reverse-proxy --to :3000 --from yourdomain.com:443
|
||||
```
|
||||
|
||||
If you’re deploying on a local network and access your server via a VPN, this is a bit more tricky. The recommended setup here is to use [Tailscale](https://tailscale.com/) which now [supports TLS certificates for your VPN servers](https://tailscale.com/kb/1153/enabling-https/). Once you have this enabled, get a certificate via:
|
||||
|
||||
```shell
|
||||
$ tailscale cert yourserver.yourtsdomain.ts.net
|
||||
```
|
||||
|
||||
Caddy can automatically find these certificates once provisioned, so you can just run:
|
||||
|
||||
```shell
|
||||
$ sudo caddy reverse-proxy --to :3000 --from yourserver.yourtsdomain.ts.net:443
|
||||
```
|
||||
|
||||
If you access SilverBullet via plain HTTP (outside of localhost) everything _should_ still mostly work, except offline mode.
|
||||
@@ -1,42 +0,0 @@
|
||||
The SilverBullet mobile app is an (almost) full version of SilverBullet running on your mobile device. It keeps its content (pages, attachments) locally, so you have access to it even without an Internet connection. You can install [[🔌 Plugs]], and they run locally as well.
|
||||
|
||||
The mobile app is still in beta and available via TestFlight, and initially only available for iOS. The [Android version is coming next](https://github.com/silverbulletmd/silverbullet/issues/310).
|
||||
|
||||
|
||||
[**Join the TestFlight iOS SilverBullet beta**](https://testflight.apple.com/join/QqYAVZcr)
|
||||
|
||||
## PWA vs “native” app
|
||||
On mobile you essentially have two ways to run SilverBullet:
|
||||
|
||||
1. Run the [[Server]] and access it via your mobile browser
|
||||
2. Run the [[Mobile]] app and either maintain a separate space there, or use [[Sync]] to synchronize your content with a [[Server]].
|
||||
|
||||
There are a few advantages to using the [[Server]] on a mobile browser:
|
||||
|
||||
1. No [[Sync]] required. Content is kept in one place (which you can backup separately).
|
||||
2. You can access one SilverBullet from any browser on any device, so Android too.
|
||||
3. Any “heavy lifting” (like indexing pages) happens on the server, not the device.
|
||||
|
||||
There are also disadvantages:
|
||||
|
||||
1. You need a network connection to the [[Server]] at all times.
|
||||
2. PWAs don’t always work fully reliably on all devices (specifically iOS)
|
||||
|
||||
|
||||
The advantages of using the “native” mobile app:
|
||||
|
||||
1. Fully offline capable: no need for an Internet connection, except for [[Sync]] or any [[🔌 Plugs]] that require one
|
||||
2. Faster, local performance
|
||||
|
||||
The disadvantages:
|
||||
|
||||
1. Likely you’ll need to use [[Sync]] to synchronize your content with other devices, this comes with any drawbacks of sync: conflicts, forgetting to sync content etc.
|
||||
|
||||
## Implementation
|
||||
The reason we’re quoting “native” app consistently, is that the mobile app is built using [CapacitorJS](https://capacitorjs.com/). A lightweight wrapper around a WebView exposing various native APIs, such as access to the local file system, SQLite database etc.
|
||||
|
||||
The mobile app keeps its files in the sandboxed file system of the SilverBullet app. These files are accessible via iOS file sharing capability (when you plug in your device via USB, you can see all files, copy new ones and remove them), and are included with the regular iOS backups.
|
||||
|
||||
## Caveats
|
||||
* Shell commands: on [[Server]] and [[Desktop]] [[🔌 Plugs]] have the ability to run shell commands, the [[🔌 Git]] plug uses this functionality for instance. This does not work on mobile.
|
||||
* Local file system access (outside the space): on [[Server]] and [[Desktop]], plugs can get access to your local file system _outside_ the location where your space content is stored. This is used, for instance for [[🔌 Markdown]] sharing as well as `file:` URLs in your [[PLUGS]] file. This is not supported on mobile.
|
||||
+2
-2
@@ -1,6 +1,6 @@
|
||||
This file lists all plugs that SilverBullet will load. Run the {[Plugs: Update]} command to update and reload this list of plugs.
|
||||
|
||||
```yaml
|
||||
- github:silverbulletmd/silverbullet-git/git.plug.json
|
||||
- github:silverbulletmd/silverbullet-mermaid/mermaid.plug.json
|
||||
- github:silverbulletmd/silverbullet-git/git.plug.js
|
||||
- github:silverbulletmd/silverbullet-mermaid/mermaid.plug.js
|
||||
```
|
||||
@@ -0,0 +1 @@
|
||||
SilverBullet is developed as a [Progressive Web App](https://web.dev/progressive-web-apps/), a web application that is offline capable: after your first load and sync, (practically) all functionality is available even without a network connection.
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
If you create a [[STYLES]] page in your project, SilverBullet will look for a CSS code block inside that page and load it upon boot (an example can be found below).
|
||||
|
||||
This can be used to achieve various things, such as overriding the default editor font, or setting wider page widths. What CSS styles you can override is not very well documented, you’ll have to reverse engineer things a bit for now, unfortunately.
|
||||
This can be used to achieve various things, such as overriding the default editor font or setting wider page widths. What CSS styles you can override is not very well documented, you’ll have to reverse-engineer things a bit for now, unfortunately.
|
||||
|
||||
```css
|
||||
#sb-root {
|
||||
|
||||
@@ -1,80 +0,0 @@
|
||||
Installing SilverBullet as a (local) web server is the most mature, and most flexible way to install SilverBullet. If mature and flexible is your thing, try this option!
|
||||
|
||||
The idea is simple: you run the web server (instructions below), point your browser at it and _go, go, go_! You can access the URL via your desktop browser, but also a mobile one. This makes it a great option to access your space from various devices without requiring any type of sync. You could even go _full-on YOLO_ (that’s a technical term), and install it on a public cloud server somewhere and access it that way (be sure to at least enable authentication and put SSL on top of it, though).
|
||||
|
||||
You have two options to install and run SilverBullet as a server:
|
||||
|
||||
1. Installation via Deno on your host system
|
||||
2. Running it with Docker
|
||||
|
||||
## Installation via Deno
|
||||
This consists of two steps (unless Deno is already installed — in which case we’re down to one):
|
||||
|
||||
1. [Install Deno](https://deno.land/manual/getting_started/installation) (if you’re using a Raspberry Pi, follow [[Raspberry Pi Installation]]-specific instructions)
|
||||
2. Installing SilverBullet itself
|
||||
|
||||
### Install SilverBullet
|
||||
With Deno installed, run:
|
||||
|
||||
```shell
|
||||
deno install -f --name silverbullet -A --unstable https://get.silverbullet.md
|
||||
```
|
||||
|
||||
This will install `silverbullet` into your `~/.deno/bin` folder (which should already be in your `$PATH` if you followed the Deno install instructions).
|
||||
|
||||
To run SilverBullet, create a folder for your pages (it can be empty, or be an existing folder with `.md` files) and run the following command in your terminal:
|
||||
|
||||
```shell
|
||||
silverbullet <pages-path>
|
||||
```
|
||||
|
||||
By default, SilverBullet will bind to port `3000`, to use a different port use the `--port` flag.
|
||||
|
||||
For security reasons, by default SilverBullet only allows connections via `localhost` (or `127.0.0.1`). To also allow connections from the network, pass a `--hostname 0.0.0.0` flag (0.0.0.0 for all connections, or insert a specific address to limit the host), ideally combined with `--user username:password` to add BasicAuth password protection. Credentials can also be specified with the `SB_USER` environment variable, `SB_USER=username:password`. If both are specified, the `--user` flag takes precedence.
|
||||
|
||||
Once downloaded and booted, SilverBullet will print out a URL to open SB in your browser.
|
||||
|
||||
## Upgrading SilverBullet
|
||||
SilverBullet is regularly updated. To get the latest and greatest, simply run:
|
||||
|
||||
```shell
|
||||
silverbullet upgrade
|
||||
```
|
||||
|
||||
And restart SilverBullet. You should be good to go.
|
||||
|
||||
## Installing SilverBullet with Docker
|
||||
|
||||
There is a [docker image on docker hub](https://hub.docker.com/r/zefhemel/silverbullet). To use it, first create a volume to keep your space (markdown) files:
|
||||
|
||||
```shell
|
||||
docker volume create myspace
|
||||
```
|
||||
|
||||
Then, run the container, e.g. as follows:
|
||||
|
||||
```shell
|
||||
docker run -p 3000:3000 -v myspace:/space -d --name silverbullet zefhemel/silverbullet
|
||||
```
|
||||
|
||||
If you'd like to pass in additional command line arguments (e.g. `--user` to add authentication) you can just append those to the command, e.g.:
|
||||
|
||||
```shell
|
||||
docker run -p 3000:3000 -v myspace:/space -d --name silverbullet zefhemel/silverbullet --user me:letmein
|
||||
```
|
||||
|
||||
To build your own version of the docker image, run `./scripts/build_docker.sh`.
|
||||
|
||||
You can also use docker-compose if you prefer. From a silverbullet check-out run:
|
||||
|
||||
```shell
|
||||
PORT=3000 docker-compose up
|
||||
```
|
||||
|
||||
or similar.
|
||||
|
||||
To upgrade, simply pull the latest docker image (rebuilt and pushed after every commit to "main") and start the new container.
|
||||
|
||||
```shell
|
||||
docker pull zefhemel/silverbullet
|
||||
```
|
||||
+6
-22
@@ -2,12 +2,12 @@ SilverBullet is an extensible, [open source](https://github.com/silverbulletmd/s
|
||||
|
||||
You’ve been told there is _no such thing_ as a [silver bullet](https://en.wikipedia.org/wiki/Silver_bullet). You were told wrong.
|
||||
|
||||
Before we get to the nitty gritty, some _quick links_ for the impatient reader: [[Download]], [[Sync]], [[CHANGELOG]], [Roadmap](https://github.com/orgs/silverbulletmd/projects/2/views/1), [Issues](https://github.com/silverbulletmd/silverbullet/issues), [Discussions](https://github.com/silverbulletmd/silverbullet/discussions), [Mastodon](https://hachyderm.io/@silverbullet), [Discord](https://discord.gg/EvXbFucTxn), [Docker Hub](https://hub.docker.com/r/zefhemel/silverbullet).
|
||||
Before we get to the nitty gritty, some _quick links_ for the impatient reader: [[Install]], [[CHANGELOG]], [Roadmap](https://github.com/orgs/silverbulletmd/projects/2/views/1), [Issues](https://github.com/silverbulletmd/silverbullet/issues), [Discussions](https://github.com/silverbulletmd/silverbullet/discussions), [Mastodon](https://hachyderm.io/@silverbullet), [Discord](https://discord.gg/EvXbFucTxn), [Docker Hub](https://hub.docker.com/r/zefhemel/silverbullet).
|
||||
|
||||
Now that we got that out of the way, let’s have a look at some of SilverBullet’s features.
|
||||
|
||||
## Features
|
||||
* Runs in any modern browser (including on mobile) when run as a [[Server]], but can also be run as a [[Desktop]] and [[Mobile]] app.
|
||||
* Runs in any modern browser (including on mobile) as an **offline-first [[PWA]],** keeping the primary copy of your content in the browser, syncing back to the server when a network connection is available.
|
||||
* Provides an enjoyable [[Markdown]] writing experience with a clean UI, rendering text using [[Live Preview|live preview]] further **reducing visual noise**, while still providing direct access to the underlying markdown syntax.
|
||||
* Supports wiki-style **page linking** using the `[[page link]]` syntax, even keeping links up-to-date when pages are renamed.
|
||||
* Optimized for **keyboard-based operation**:
|
||||
@@ -25,7 +25,6 @@ To get a good feel of what SilverBullet is capable of, have a look at this intro
|
||||
```embed
|
||||
url: https://youtu.be/VemS-cqAD5k
|
||||
```
|
||||
|
||||
## Try it
|
||||
Here’s the kicker:
|
||||
|
||||
@@ -33,7 +32,7 @@ Here’s the kicker:
|
||||
|
||||
That’s right, **this very website is powered by SilverBullet itself**. 🤯
|
||||
|
||||
On this site, everything is editable just none of it persists (the back-end is read-only). So, edit away, reload the page and everything resets.
|
||||
On this site, everything is editable, just none of it syncs back (successfully) to the server. You are editing a local copy of this website, so changes do persist locally.
|
||||
|
||||
Don’t just sit there, try it!
|
||||
|
||||
@@ -49,7 +48,7 @@ Don’t just sit there, try it!
|
||||
* Click this button {[Editor: Toggle Vim Mode]} to toggle Vim mode
|
||||
* Open this site on your phone or tablet and... it just works!
|
||||
* Are you using a browser with **PWA support** (e.g. any Chromium-based
|
||||
browser)? Click on that little icon to the right of your location bar that says “Install SilverBullet” to give SB its own window frame and desktop icon, like it is a stand-alone app (not particularly useful on silverbullet.md, but definitely do this once you install it yourself).
|
||||
browser)? Click on that little icon to the right of your location bar that says “Install SilverBullet” to give SB its own window frame and desktop icon, like it is a stand-alone app (not particularly useful on silverbullet.md, but definitely do this once you install it yourself). Now, unplug your network cable and reload the page. It still works!
|
||||
|
||||
Oh yeah, and you can use fancy things like tables:
|
||||
|
||||
@@ -73,23 +72,8 @@ name: SilverBullet
|
||||
rating: 5
|
||||
```
|
||||
|
||||
There are a few features you don’t get to fully experience in this environment, because they rely on a working back-end, such as:
|
||||
|
||||
* Any edits you make and pages you add aren’t saved (kind of useful).
|
||||
* [[🔌 Directive|Directives]] are disabled, although you will see them being used across this site (look for sections with subtle curved lines around them, if you move your cursor inside you’ll see where their content is generated from), they just don’t update their content dynamically.
|
||||
* **Full-text search**.
|
||||
* **Extending** and updating SB’s functionality by installing additional [[🔌 Plugs]] (SB parlance for plug-ins) and writing your own.
|
||||
|
||||
## Download SilverBullet
|
||||
Has your mind been sufficiently blown to commit to an install? Took you long enough, alright then.
|
||||
|
||||
<!-- #include [[Download]] -->
|
||||
You have three options to install and use SilverBullet. Pick your poison, as they say. Have a look at all three to decide what’s best for you:
|
||||
|
||||
1. [[Server]] — install SilverBullet as a web server on your local machine or network, and access it via any web browser. This is the best choice for nerds 🤓.
|
||||
2. [[Desktop]] — install SilverBullet as a desktop application, editing a local folder of files. This is the best option for casual users.
|
||||
3. [[Mobile]] — install SilverBullet as a “native” mobile application (native: as in — distributed via the app store, and with an icon on your home screen). This is the best option for people with phones. More specifically, people with phones that don’t want to access the [[Server]] via their mobile browser, or have anxiety around Internet connectivity.
|
||||
<!-- /include -->
|
||||
## Install SilverBullet
|
||||
Has your mind been sufficiently blown to commit to an install? Took you long enough, alright then. Please proceed to the [[Install]] and enjoy!
|
||||
|
||||
## Where to go from here
|
||||
Click on the links below to explore various aspects of SilverBullet more in-depth:
|
||||
|
||||
@@ -1,47 +0,0 @@
|
||||
SilverBullet now has a sync engine. It’s still early in its development, so somewhat experimental. If you decide to use it **make back-ups**.
|
||||
|
||||
The synchronization algorithm implemented is [pretty much the one described here](https://unterwaditzer.net/2016/sync-algorithm.html).
|
||||
|
||||
## Architecture
|
||||
To use SilverBullet sync, you’ll use a single SilverBullet [[Server]] as your central synchronization space, then connect any other instances of SilverBullet (likely primarily [[Mobile]] and [[Desktop]] apps, but could also be other [[Server]] instances) to it. Each “client” instance keeps track of sync snapshots that it uses to figure out what files have changed where.
|
||||
|
||||
Let’s put this information in a graph just because we can!
|
||||
|
||||
```mermaid
|
||||
graph TD;
|
||||
iPhone-->SB(SilverBullet Server);
|
||||
iPad-->SB;
|
||||
Desktop-->SB;
|
||||
OtherSB(Other Silver Bullet instance)-->SB;
|
||||
```
|
||||
|
||||
## Usage
|
||||
Here’s how to use SilverBullet’s sync functionality:
|
||||
|
||||
1. Set up a SilverBullet [[Server]] somewhere where all your other devices have access to it. This can be your local network, a VPN, or if you’re living the wild life — the public Internet (do put some SSL and authentication on it, please).
|
||||
2. Connect any other SilverBullet instance (likely the [[Desktop]] or [[Mobile]] app) to it via the {[Sync: Configure]} command. This will ask for:
|
||||
* A URL to connect to (the URL of the SB server configured under (1))
|
||||
* A username and password (optional) if you run the server with the `--user myuser:mypass` flag or the `SB_USER=myuser:mypass` environment variable (as you should)
|
||||
|
||||
3. Now you have two options:
|
||||
1. Perform a one-time “clean sync” _wiping all local content_ and syncing down content from the sync server. For this, use the {[Sync: Wipe Local Space and Sync]} command. This is likely what you want for e.g. an initial [[Mobile]] setup.
|
||||
2. Use {[Sync: Sync]} to perform a regular sync, comparing the local and remote space and generating conflicts where appropriate.
|
||||
3. Check {[Show Logs]} for sync logs.
|
||||
|
||||
Sync is triggered:
|
||||
* Continuously when changes are made to a page in a client set up with sync, immediately after the page persists (single file sync)
|
||||
* Automatically every minute (full space sync)
|
||||
* Manually using the {[Sync: Sync]} command (full space sync)
|
||||
|
||||
## The sync process
|
||||
1. The sync engine compares two file listings: the local one and the remote one, and figures out which files have been added, changed and removed on both ends. It uses timestamps to determine changes. Note this doesn’t make any assumptions about clocks being in sync, timezones etc.
|
||||
2. In most cases, based on this info (together with the snapshot from the last sync), it should be obvious what to do, and it will do just do it.
|
||||
3. In case of a conflict — which would happen if files on both ends have been changed since the last sync, it will first pull down both files and compare their content. If they’re the same, no issues. If they’re different: a conflicting copy will be created with a name of `page name.conflicted.timestamp`. You’ll see those appear in your page list.
|
||||
|
||||
## Caveats
|
||||
* This is new code and has not been extremely thoroughly tested. Make backups.
|
||||
* The sync engine doesn’t synchronize `_plugs` code, so to update the plug list based on your [[PLUGS]] you have to manually run {[Plugs: Update]}.
|
||||
|
||||
So, if you’re ready for this. Go try it. We do recommend: make regular backups in case the proverbial shit hits the fan, don’t say we didn’t warn you!
|
||||
|
||||
You can tweak some things in sync, such as excluding certain prefixes from sync. For this, see the [[SETTINGS]] documentation.
|
||||
+4
-6
@@ -1,8 +1,6 @@
|
||||
/fs/_plug/*
|
||||
Content-Type: application/json
|
||||
X-Last-Modified: 1
|
||||
/.fs/_plug/*
|
||||
X-Last-Modified: 12345
|
||||
X-Permission: ro
|
||||
/fs/*
|
||||
Content-Type: text/markdown
|
||||
X-Last-Modified: 1
|
||||
/.fs/*
|
||||
X-Last-Modified: 12345
|
||||
X-Permission: rw
|
||||
|
||||
+5
-3
@@ -1,3 +1,5 @@
|
||||
/fs /index.json 200
|
||||
/fs/* /empty.md 200
|
||||
/* /index.html 200
|
||||
/.fs /index.json 200
|
||||
/.fs/* /_fs/:splat 200!
|
||||
/.fs/* /empty.md 200
|
||||
/.client/* /_client/:splat 200!
|
||||
/* /_client/index.html 200
|
||||
@@ -1,4 +0,0 @@
|
||||
|
||||
---
|
||||
©️ [[SilverBullet]] authors.
|
||||
_Published with [SilverBullet Publish](https://github.com/silverbulletmd/silverbullet-publish)._
|
||||
@@ -1,27 +1,28 @@
|
||||
---
|
||||
type: plug
|
||||
uri: ghr:Willyfrog/silverbullet-backlinks
|
||||
repo: https://github.com/Willyfrog/silverbullet-backlinks
|
||||
uri: github:silverbulletmd/silverbullet-backlinks/backlinks.plug.js
|
||||
repo: https://github.com/silverbulletmd/silverbullet-backlinks
|
||||
author: Guillermo Vayá
|
||||
---
|
||||
|
||||
<!-- #include [[https://raw.githubusercontent.com/Willyfrog/silverbullet-backlinks/main/README.md]] -->
|
||||
<!-- #include [[https://raw.githubusercontent.com/silverbulletmd/silverbullet-backlinks/main/README.md]] -->
|
||||
# SilverBullet plug for Backlinks
|
||||
|
||||
Provides access to pages that link to the one currently being edited.
|
||||
|
||||
## Wait, SilverBullet?
|
||||
|
||||
If you don't know what it is, check its [webpage](https://silverbullet.md), but if
|
||||
you want me to spoil the fun: it is an extensible note taking app with markdown and plain files at its core
|
||||
(well... there is a bit of magic in there too, but what good it would be without a little magic?)
|
||||
If you don't know what it is, check its [webpage](https://silverbullet.md), but
|
||||
if you want me to spoil the fun: it is an extensible note-taking app with
|
||||
markdown and plain files at its core (well... there is a bit of magic in there
|
||||
too, but what good it would be without a little magic?)
|
||||
|
||||
## Installation
|
||||
|
||||
Open (`cmd+k`) your `PLUGS` note in SilverBullet and add this plug to the list:
|
||||
|
||||
```yaml
|
||||
- https://github.com/Willyfrog/silverbullet-backlinks/releases/download/v0.3/silverbullet-backlinks.plug.json
|
||||
- github:silverbulletmd/silverbullet-backlinks/backlinks.plug.js
|
||||
```
|
||||
|
||||
Then run the `Plugs: Update` command and off you go!
|
||||
|
||||
@@ -93,10 +93,10 @@ country: Germany
|
||||
|
||||
Example:
|
||||
<!-- #query data where age > 20 and country = "Italy" -->
|
||||
|name|age|city |country|page |pos|
|
||||
|----|--|-----|-----|------------------|-|
|
||||
|John|50|Milan|Italy|🔌 Directive/Query|0|
|
||||
|Jane|53|Rome |Italy|🔌 Directive/Query|1|
|
||||
|name|age|city |country|page |pos |
|
||||
|----|--|-----|-----|------------------|----|
|
||||
|John|50|Milan|Italy|🔌 Directive/Query|3279|
|
||||
|Jane|53|Rome |Italy|🔌 Directive/Query|3280|
|
||||
<!-- /query -->
|
||||
|
||||
#### 4.2 Plugs’ data sources
|
||||
@@ -163,11 +163,11 @@ For the sake of simplicity, we will use the `page` data source and limit the res
|
||||
**Result:** Look at the data. This is more than we need. The query even gives us template pages. Let's try to limit it in the next step.
|
||||
|
||||
<!-- #query page limit 3 -->
|
||||
|name |lastModified |contentType |size|perm|type|uri |repo |author |
|
||||
|--|--|--|--|--|--|--|--|--|
|
||||
|Markdown |1669534332564|text/markdown|1022|rw| | | | |
|
||||
|🔌 Graph View|1669388320673|text/markdown|1042|rw|plug|github:bbroeksema/silverbullet-graphview/graphview.plug.json|https://github.com/bbroeksema/silverbullet-graphview|Bertjan Broeksema|
|
||||
|SETTINGS |1671107145991|text/markdown|169 |rw| | | | |
|
||||
|name |lastModified |contentType |size |perm|tags|
|
||||
|-----------|-------------|-------------|-----|--|----|
|
||||
|CHANGELOG |1684497544505|text/markdown|23605|rw|tags|
|
||||
|Cloud Links|1676121406519|text/markdown|1177 |rw| |
|
||||
|Frontmatter|1676121406519|text/markdown|1090 |rw| |
|
||||
<!-- /query -->
|
||||
|
||||
|
||||
@@ -178,13 +178,13 @@ For the sake of simplicity, we will use the `page` data source and limit the res
|
||||
**Result:** Okay, this is what we wanted but there is also information such as `perm`, `type` and `lastModified` that we don't need.
|
||||
|
||||
<!-- #query page where type = "plug" order by lastModified desc limit 5 -->
|
||||
|name |lastModified |contentType |size|perm|type|uri |repo |author |share-support|
|
||||
|--|--|--|--|--|--|--|--|--|--|
|
||||
|🔌 KaTeX |1671723760117|text/markdown|1346|rw|plug|github:silverbulletmd/silverbullet-katex/katex.plug.json |https://github.com/silverbulletmd/silverbullet-katex |Zef Hemel| |
|
||||
|🔌 Mermaid |1671723720005|text/markdown|1501|rw|plug|github:silverbulletmd/silverbullet-mermaid/mermaid.plug.json |https://github.com/silverbulletmd/silverbullet-mermaid |Zef Hemel| |
|
||||
|🔌 Mattermost|1671205865185|text/markdown|3535|rw|plug|github:silverbulletmd/silverbullet-mattermost/mattermost.plug.json|https://github.com/silverbulletmd/silverbullet-mattermost|Zef Hemel|true|
|
||||
|🔌 Share |1671205498955|text/markdown|694 |rw|plug| |https://github.com/silverbulletmd/silverbullet | | |
|
||||
|🔌 Directive |1671044959953|text/markdown|2605|rw|plug| |https://github.com/silverbulletmd/silverbullet | | |
|
||||
|name |lastModified |contentType |size|perm|type|uri |repo |author |
|
||||
|--|--|--|--|--|--|--|--|--|
|
||||
|🔌 Git |1676639116714|text/markdown|943 |rw|plug|github:silverbulletmd/silverbullet-git/git.plug.json |https://github.com/silverbulletmd/silverbullet-git |Zef Hemel |
|
||||
|🔌 Share |1676121406530|text/markdown|711 |rw|plug| |https://github.com/silverbulletmd/silverbullet | |
|
||||
|🔌 Tasks |1676121406530|text/markdown|1229|rw|plug| |https://github.com/silverbulletmd/silverbullet | |
|
||||
|🔌 Twitter |1676121406530|text/markdown|1269|rw|plug|github:silverbulletmd/silverbullet-twitter/twitter.plug.json|https://github.com/silverbulletmd/silverbullet-twitter|SilverBullet Authors|
|
||||
|🔌 Graph View|1676121406529|text/markdown|1041|rw|plug|github:bbroeksema/silverbullet-graphview/graphview.plug.json|https://github.com/bbroeksema/silverbullet-graphview |Bertjan Broeksema |
|
||||
<!-- /query -->
|
||||
|
||||
#### 6.3 Query to select only certain fields
|
||||
@@ -195,14 +195,14 @@ and `repo` columns and then sort by last modified time.
|
||||
**Result:** Okay, this is much better. However, I believe this needs a touch
|
||||
from a visual perspective.
|
||||
|
||||
<!-- #query page select name author repo uririrririrririrririrririri where type = "plug" order by lastModified desc limit 5 -->
|
||||
|name |author |repo |ririrririrririri|
|
||||
<!-- #query page select name author repo uririrririrririrririrririrririrririri where type = "plug" order by lastModified desc limit 5 -->
|
||||
|name |author |repo |ririrririrririrririrririri|
|
||||
|--|--|--|--|
|
||||
|🔌 KaTeX |Zef Hemel|https://github.com/silverbulletmd/silverbullet-katex ||
|
||||
|🔌 Mermaid |Zef Hemel|https://github.com/silverbulletmd/silverbullet-mermaid ||
|
||||
|🔌 Mattermost|Zef Hemel|https://github.com/silverbulletmd/silverbullet-mattermost||
|
||||
|🔌 Share | |https://github.com/silverbulletmd/silverbullet ||
|
||||
|🔌 Directive | |https://github.com/silverbulletmd/silverbullet ||
|
||||
|🔌 Git |Zef Hemel |https://github.com/silverbulletmd/silverbullet-git ||
|
||||
|🔌 Share | |https://github.com/silverbulletmd/silverbullet ||
|
||||
|🔌 Tasks | |https://github.com/silverbulletmd/silverbullet ||
|
||||
|🔌 Twitter |SilverBullet Authors|https://github.com/silverbulletmd/silverbullet-twitter||
|
||||
|🔌 Graph View|Bertjan Broeksema |https://github.com/bbroeksema/silverbullet-graphview ||
|
||||
<!-- /query -->
|
||||
|
||||
#### 6.4 Display the data in a format defined by a template
|
||||
@@ -211,12 +211,12 @@ from a visual perspective.
|
||||
|
||||
**Result:** Here you go. This is the result we would like to achieve 🎉. Did you see how I used `render` and `template/plug` in a query? 🚀
|
||||
|
||||
<!-- #query page select name author repo uririrririrririrririrririri where type = "plug" order by lastModified desc limit 5 render [[template/plug]] -->
|
||||
* [[🔌 KaTeX]] by **Zef Hemel** ([repo](https://github.com/silverbulletmd/silverbullet-katex))
|
||||
* [[🔌 Mermaid]] by **Zef Hemel** ([repo](https://github.com/silverbulletmd/silverbullet-mermaid))
|
||||
* [[🔌 Mattermost]] by **Zef Hemel** ([repo](https://github.com/silverbulletmd/silverbullet-mattermost))
|
||||
<!-- #query page select name author repo uririrririrririrririrririrririrririri where type = "plug" order by lastModified desc limit 5 render [[template/plug]] -->
|
||||
* [[🔌 Git]] by **Zef Hemel** ([repo](https://github.com/silverbulletmd/silverbullet-git))
|
||||
* [[🔌 Share]]
|
||||
* [[🔌 Directive]]
|
||||
* [[🔌 Tasks]]
|
||||
* [[🔌 Twitter]] by **SilverBullet Authors** ([repo](https://github.com/silverbulletmd/silverbullet-twitter))
|
||||
* [[🔌 Graph View]] by **Bertjan Broeksema** ([repo](https://github.com/bbroeksema/silverbullet-graphview))
|
||||
<!-- /query -->
|
||||
|
||||
PS: You don't need to select only certain fields to use templates. Templates are
|
||||
|
||||
+3
-3
@@ -1,13 +1,13 @@
|
||||
---
|
||||
type: plug
|
||||
uri: github:silverbulletmd/silverbullet-ghost/ghost.plug.json
|
||||
uri: github:silverbulletmd/silverbullet-ghost/ghost.plug.js
|
||||
repo: https://github.com/silverbulletmd/silverbullet-ghost
|
||||
author: Zef Hemel
|
||||
share-support: true
|
||||
---
|
||||
|
||||
<!-- #include [[https://raw.githubusercontent.com/silverbulletmd/silverbullet-ghost/main/README.md]] -->
|
||||
# Ghost plug for SilverBullet
|
||||
# Ghost plug for Silver Bullet
|
||||
|
||||
This allows you to publish your pages as [Ghost](https://ghost.org/) pages or posts. I use it to publish [Zef+](https://zef.plus).
|
||||
|
||||
@@ -28,7 +28,7 @@ Then, create a Custom Integration (in your Ghost control panel under Settings >
|
||||
```
|
||||
|
||||
## Usage
|
||||
The plugin hooks into SilverBullet's [Share infrastructure](https://silverbullet.md/%F0%9F%94%8C_Share). Therefore to share a page as either a Ghost page or post, add a `$share` front matter key. For posts this should take the shape of:
|
||||
The plugin hooks into Silver Bullet's [Share infrastructure](https://silverbullet.md/%F0%9F%94%8C_Share). Therefore to share a page as either a Ghost page or post, add a `$share` front matter key. For posts, this should take the shape of:
|
||||
|
||||
---
|
||||
$share:
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
---
|
||||
type: plug
|
||||
uri: github:silverbulletmd/silverbullet-git/git.plug.json
|
||||
uri: github:silverbulletmd/silverbullet-git/git.plug.js
|
||||
repo: https://github.com/silverbulletmd/silverbullet-git
|
||||
author: Zef Hemel
|
||||
---
|
||||
|
||||
+4
-4
@@ -1,6 +1,6 @@
|
||||
---
|
||||
type: plug
|
||||
uri: github:silverbulletmd/silverbullet-github/github.plug.json
|
||||
uri: github:silverbulletmd/silverbullet-github/github.plug.js
|
||||
repo: https://github.com/silverbulletmd/silverbullet-github
|
||||
author: Zef Hemel
|
||||
share-support: true
|
||||
@@ -25,9 +25,9 @@ Then run the `Plugs: Update` command and off you go!
|
||||
## Configuration
|
||||
To configure, add a `githubToken` key to your `SECRETS` page, this should be a [personal access token](https://github.com/settings/tokens):
|
||||
|
||||
```yaml
|
||||
githubToken: your-github-token
|
||||
```
|
||||
```yaml
|
||||
githubToken: your-github-token
|
||||
```
|
||||
|
||||
## Query sources
|
||||
|
||||
|
||||
@@ -8,8 +8,7 @@ author: Bertjan Broeksema
|
||||
<!-- #include [[https://raw.githubusercontent.com/bbroeksema/silverbullet-graphview/main/README.md]] -->
|
||||
# SilverBullet plug for showing a graph view of the documents
|
||||
|
||||
This plug aims to bring similar functionality as the Obsidian Graph view to
|
||||
SilverBullet.
|
||||
This plug aims to bring functionality similar to the Obsidian Graph view to SilverBullet.
|
||||
|
||||
## Installation
|
||||
|
||||
@@ -23,13 +22,11 @@ Then run the `Plugs: Update` command and off you go!
|
||||
|
||||
## Usage
|
||||
|
||||
Run the `Show Graph` command to open up the graph view. Zoom and pan is
|
||||
supported by scroll and pinch gestures with the mouse(pad).
|
||||
Run the `Show Graph` command to open up the graph view. Zoom and pan are supported by scroll and pinch gestures with the mouse(pad).
|
||||
|
||||
## For offline development
|
||||
|
||||
To ease development of the visual part, the offline folder contains a copy of
|
||||
the html and custom javascritpt. As well as a simple graph model.
|
||||
To ease the development of the visual part, the offline folder contains a copy of the HTML and custom JavaScript, as well as a simple graph model.
|
||||
|
||||
```bash
|
||||
$ cd offline
|
||||
|
||||
+5
-5
@@ -1,12 +1,12 @@
|
||||
---
|
||||
type: plug
|
||||
uri: github:silverbulletmd/silverbullet-katex/katex.plug.json
|
||||
uri: github:silverbulletmd/silverbullet-katex/katex.plug.js
|
||||
repo: https://github.com/silverbulletmd/silverbullet-katex
|
||||
author: Zef Hemel
|
||||
---
|
||||
|
||||
<!-- #include [[https://raw.githubusercontent.com/silverbulletmd/silverbullet-katex/main/README.md]] -->
|
||||
# SilverBullet KaTeX plug
|
||||
# Silver Bullet KaTeX plug
|
||||
|
||||
## Installation
|
||||
Run the {[Plugs: Add]} command and paste in: `github:silverbulletmd/silverbullet-katex/katex.plug.json`
|
||||
@@ -23,10 +23,10 @@ Put a latex block in your markdown:
|
||||
|
||||
And move your cursor outside of the block to live preview it!
|
||||
|
||||
**Note:** [KaTeX](https://katex.org) itself is not bundled with this plug, it pulls the JavaScript, CSS and fonts from the JSDelivr CDN. This means _this plug will not work without an Internet connection_. The reason for this limitation is that it is not yet possible to distribute font files via plugs, and KaTeX depends on specific web fonts.
|
||||
**Note:** [KaTeX](https://katex.org) itself is not bundled with this plug; it pulls the JavaScript, CSS and fonts from the JSDelivr CDN. This means _this plug will not work without an Internet connection_. This limitation is because it is not yet possible to distribute font files via plugs, and KaTeX depends on specific web fonts.
|
||||
|
||||
## Build
|
||||
Assuming you have Deno and SilverBullet installed, simply build using:
|
||||
Assuming you have Deno and Silver Bullet installed, simply build using:
|
||||
|
||||
```shell
|
||||
deno task build
|
||||
@@ -38,7 +38,7 @@ Or to watch for changes and rebuild automatically
|
||||
deno task watch
|
||||
```
|
||||
|
||||
Then, load the locally built plug, add it to your `PLUGS` note with an absolute path, for instance:
|
||||
Then, load the locally built plug and add it to your `PLUGS` note with an absolute path, for instance:
|
||||
|
||||
```
|
||||
- file:/Users/you/path/to/katex.plug.json
|
||||
|
||||
@@ -46,7 +46,7 @@ In `SECRETS` provide a Mattermost personal access token (or hijack one from your
|
||||
|
||||
* `mm-saved` fetches (by default 15) saved posts in Mattermost, you need to add a `where server = "community"` (with server name) clause to your query to select the mattermost server to query.
|
||||
|
||||
To make the `mm-saved` query results look good, it's recommended you render your query results a template. Here is one to start with, you can keep it in e.g. `templates/mm-saved`:
|
||||
To make the `mm-saved` query results look good, it's recommended you render your query results with a template. Here is one to start with: you can keep it in e.g., `templates/mm-saved`:
|
||||
|
||||
[{{username}}]({{url}}) in {{#if channelName}}**{{channelName}}**{{else}}a DM{{/if}} at _{{updatedAt}}_ {[Unsave]}:
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
type: plug
|
||||
uri: github:silverbulletmd/silverbullet-mermaid/mermaid.plug.json
|
||||
uri: github:silverbulletmd/silverbullet-mermaid/mermaid.plug.js
|
||||
repo: https://github.com/silverbulletmd/silverbullet-mermaid
|
||||
author: Zef Hemel
|
||||
---
|
||||
@@ -40,7 +40,7 @@ Or to watch for changes and rebuild automatically
|
||||
deno task watch
|
||||
```
|
||||
|
||||
Then, load the locally built plug, add it to your `PLUGS` note with an absolute path, for instance:
|
||||
Then, load the locally built plug and add it to your `PLUGS` note with an absolute path, for instance:
|
||||
|
||||
```
|
||||
- file:/Users/you/path/to/mermaid.plug.json
|
||||
|
||||
+27
-22
@@ -1,6 +1,6 @@
|
||||
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 on the server in Deno web workers ([with severely locked down permissions](https://deno.land/manual@v1.28.2/runtime/workers#instantiation-permissions)), and in the browser using web workers.
|
||||
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:
|
||||
|
||||
@@ -12,7 +12,7 @@ Plugs can hook into SB in various ways:
|
||||
|
||||
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 JSON files (ending with `.plug.json`). 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]].
|
||||
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:
|
||||
@@ -25,20 +25,22 @@ These plugs are distributed with SilverBullet and are automatically enabled:
|
||||
* [[🔌 Share]]
|
||||
* [[🔌 Tasks]]
|
||||
<!-- /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/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))
|
||||
* [[🔌 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/bbroeksema/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 **Silver Bullet Authors** ([repo](https://github.com/silverbulletmd/silverbullet-twitter))
|
||||
* [[🔌 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.
|
||||
|
||||
@@ -50,7 +52,13 @@ Generally, the way to do this is to run `silverbullet plug:compile` as follows:
|
||||
silverbullet plug:compile yourplugname.plug.yaml
|
||||
```
|
||||
|
||||
However, if you use the plug template, this command is wrapped in your `deno.jsonc` file, so you can just run either:
|
||||
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
|
||||
@@ -62,30 +70,27 @@ to build it once, or
|
||||
deno task watch
|
||||
```
|
||||
|
||||
to build it and rebuild when files are changed. This will write a `yourplugname.plug.json` file into the same folder.
|
||||
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.json` file you can load it into SB in a few ways by listing it in your space’s `PLUGS` page.
|
||||
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 use the `file:` prefix for this, by adding this in the `yaml` block section there to your existing list of plugs:
|
||||
For development it’s easiest to simply copy the `.plug.js` file into your space’s `_plug/` folder:
|
||||
|
||||
```yaml
|
||||
- file:/home/me/git/yourplugname/yourplugname.plug.json
|
||||
```shell
|
||||
cp myplug.plug.js ~/myspace/_plug/
|
||||
```
|
||||
|
||||
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.
|
||||
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.json` file there and instructing users to point to by adding
|
||||
`- github:yourgithubuser/yourrepo/yourplugname.plug.json` to their `PLUGS` file
|
||||
- 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.json`.
|
||||
- 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`.
|
||||
|
||||
### Recommended development workflow
|
||||
I develop plugs as follows: in one terminal I have `deno task watch` 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.
|
||||
|
||||
+2
-2
@@ -13,13 +13,13 @@ Tasks can also be annotated with [[🔌 Core/Tags]]:
|
||||
|
||||
* [ ] This is a tagged task #my-tag
|
||||
|
||||
You can _toggle_ a task state either by putting in an `x` or `X` inside the box, or by simply clicking/tapping on the box, alternatively you can use the {[Task: Toggle]} command to toggle the task you’re currently in.
|
||||
You can _toggle_ a task state either by putting in an `x` or `X` inside the box or by simply clicking/tapping on the box. Alternatively, you can use the {[Task: Toggle]} command to toggle the task you’re currently in.
|
||||
|
||||
Tasks can specify deadlines:
|
||||
|
||||
* [ ] This is due 📅 2022-11-26
|
||||
|
||||
When the cursor is positioned inside of a due date, the {[Task: Postpone]} command can be used to postpone the task for a certain period of time.
|
||||
When the cursor is positioned inside of a due date, the {[Task: Postpone]} command can be used to postpone the task for a certain period.
|
||||
|
||||
This metadata is extracted and available via the `task` query source to [[🔌 Directive/Query]]:
|
||||
|
||||
|
||||
@@ -1,20 +1,20 @@
|
||||
---
|
||||
type: plug
|
||||
uri: github:silverbulletmd/silverbullet-twitter/twitter.plug.json
|
||||
uri: github:silverbulletmd/silverbullet-twitter/twitter.plug.js
|
||||
repo: https://github.com/silverbulletmd/silverbullet-twitter
|
||||
author: SilverBullet Authors
|
||||
---
|
||||
|
||||
<!-- #include [[https://raw.githubusercontent.com/silverbulletmd/silverbullet-twitter/main/README.md]] -->
|
||||
# SilverBullet for Twitter
|
||||
Currently the only thing this plug offers is unfurling links to tweets. To use, paste in a link to a Tweet like `https://twitter.com/zef/status/1547943418403295232`, then run the `Link: Unfurl` command and select `Tweet content` to "enrich" the tweet URL with the content of the linked tweet, e.g.
|
||||
Currently, the only thing this plug offers is unfurling links to tweets. To use, paste in a link to a Tweet like `https://twitter.com/zef/status/1547943418403295232`, then run the `Link: Unfurl` command and select `Tweet content` to "enrich" the tweet URL with the content of the linked tweet, e.g.
|
||||
|
||||
https://twitter.com/zef/status/1547687321679511552
|
||||
|
||||
Turns into:
|
||||
|
||||
[Zef Hemel](https://twitter.com/zef/status/1547687321679511552):
|
||||
> For those who missed my earlier posts on SilverBullet: it’s my new powerful note taking/PKM app. Demo video from a user’s perspective: https://t.co/MKauSTcUG3 How it works technically (plugins all the way down): https://t.co/sqCkAa0pem Repo: https://t.co/rrxQdyxze1
|
||||
> For those who missed my earlier posts on Silver Bullet: it’s my new powerful note taking/PKM app. Demo video from a user’s perspective: https://t.co/MKauSTcUG3 How it works technically (plugins all the way down): https://t.co/sqCkAa0pem Repo: https://t.co/rrxQdyxze1
|
||||
|
||||
## Installation
|
||||
|
||||
@@ -24,5 +24,5 @@ Open (`cmd+k`) your `PLUGS` note in SilverBullet and add this plug to the list:
|
||||
- github:silverbulletmd/silverbullet-twitter/twitter.plug.json
|
||||
```
|
||||
|
||||
Then run the `Plugs: Update` command and off you go!
|
||||
Then run the `Plugs: Update` command, and off you go!
|
||||
<!-- /include -->
|
||||
|
||||
@@ -1,10 +1,10 @@
|
||||
## Stack
|
||||
SilverBullet is written in [TypeScript](https://www.typescriptlang.org/) and built on top of the excellent [CodeMirror 6](https://codemirror.net/) editor component. Additional UI is built using [Preact](https://preactjs.com/). [ES Build](https://esbuild.github.io) is used to build both the front-end and back-end bundles. The server backend runs as a HTTP server on [Deno](https://deno.land/) using [Oak](https://oakserver.github.io/oak/).
|
||||
SilverBullet is written in [TypeScript](https://www.typescriptlang.org/) and built on top of the excellent [CodeMirror 6](https://codemirror.net/) editor component. Additional UI is built using [Preact](https://preactjs.com/). [ES Build](https://esbuild.github.io) is used to build both the front-end and back-end bundles. The server backend runs as an HTTP server on [Deno](https://deno.land/) using [Oak](https://oakserver.github.io/oak/).
|
||||
|
||||
## Development
|
||||
Requirements: [Deno](https://deno.land/) 1.28 or newer. If you are running SilverBullet, you will already have Deno installed.
|
||||
Requirements: [Deno](https://deno.land/) 1.33 or newer. If you are running SilverBullet, you will already have Deno installed.
|
||||
|
||||
Clone the repository from Github:
|
||||
Clone the repository from GitHub:
|
||||
|
||||
```shell
|
||||
git clone git@github.com:silverbulletmd/silverbullet.git
|
||||
|
||||
@@ -1,3 +1 @@
|
||||
This is very much in progress, have a look at our
|
||||
[Github Issues](https://github.com/silverbulletmd/silverbullet/issues) page if
|
||||
you’d like to help out!
|
||||
This is very much in progress, have a look at our [Github Issues](https://github.com/silverbulletmd/silverbullet/issues) page if you’d like to help out!
|
||||
|
||||
Reference in New Issue
Block a user