WIP manual work
This commit is contained in:
Zef Hemel
parent
8c14087a2c
commit
307ba0a01c
13
website/Attachments.md
Normal file
13
website/Attachments.md
Normal file
@ -0,0 +1,13 @@
|
||||
While SilverBullet for sure is aimed at primarily text-based content, life can not fully be represented in text always. Therefore, SilverBullet supports attachments. Attachments, like [[Pages]] ultimately are — once again — just files on disk.
|
||||
|
||||
# Uploading
|
||||
To create an attachment, you have a few options:
|
||||
|
||||
* Use the {[Upload: File]} command (especially useful on mobile devices)
|
||||
* Drag & drop files or images onto a page
|
||||
* Copy & paste files or images onto a page
|
||||
|
||||
All options will prompt you for a file name to use to store the attachment, and then include the attachment as an embedded image (if it was an image) or link to the file.
|
||||
|
||||
# Management
|
||||
SilverBullet [does not currently support](https://github.com/silverbulletmd/silverbullet/issues/72) any operations like renaming or deleting of attachments. You’ll have to do this outside of SilverBullet somehow.
|
||||
@ -8,7 +8,7 @@ silverbullet --user pete:1234 .
|
||||
|
||||
Will let `pete` authenticate with password `1234`.
|
||||
|
||||
Alternative, the same information can be passed in via the `SB_USER` environment variable, e.g.
|
||||
Alternatively, the same information can be passed in via the `SB_USER` environment variable, e.g.
|
||||
|
||||
```shell
|
||||
SB_USER=pete:1234 silverbullet .
|
||||
|
||||
@ -10,7 +10,7 @@ Generally this setup involves a few steps:
|
||||
|
||||
It is **absolutely key** to enable [[Authentication]] on SilverBullet, otherwise anybody who can guess the URL ngrok gives you, and view and edit your files at will (or worse).
|
||||
|
||||
So generally the steps are to run SilverBullet (e.g. via Deno) (see [[Install]] for more options) — note the port here (`3000`):
|
||||
Generally the steps are to run SilverBullet (e.g. via Deno) (see [[Install]] for more options) — note the port here (`3000`):
|
||||
|
||||
```bash
|
||||
$ silverbullet -p 3000 --user mysuser:mypassword path/to/space
|
||||
|
||||
12
website/End-User Programming.md
Normal file
12
website/End-User Programming.md
Normal file
@ -0,0 +1,12 @@
|
||||
An excellent [essay from Ink & Switch](https://www.inkandswitch.com/end-user-programming/) introduces **end-user programming** as follows:
|
||||
|
||||
> Today’s software apps are like appliances: we can only use the capabilities exactly as programmed by the developer. What if we, and all computer users, could reach in and modify our favorite apps? Or even create new apps on the fly according to our needs in the moment?
|
||||
>
|
||||
> This is end-user programming, a vision for empowered computing pursued by bright-eyed computer science visionaries. Its rich history reaches back to the 1960s with programming environments like Smalltalk and Logo. Notable successes since then include Unix, the spreadsheet, Hypercard, and HTML. And today, newcomers like Zapier, Coda, and Siri Shortcuts are trying their own approaches to automation and dynamic modeling.
|
||||
|
||||
SilverBullet is working towards supporting more end-user programming features. Some of them currently available include:
|
||||
|
||||
* [[Objects]]
|
||||
* [[Metadata]]
|
||||
* [[Live Queries]]
|
||||
* [[Live Templates]]
|
||||
5
website/Folders.md
Normal file
5
website/Folders.md
Normal file
@ -0,0 +1,5 @@
|
||||
While folders technically exist in SilverBullet, they’re not necessarily the key organizational tool that they are in other tools. SilverBullet doesn’t have a file and folder tree as part of its UI, for instance.
|
||||
|
||||
There’s no explicit way to create a folder, but you can do so by simply putting slashes `/` in your page name (also on Windows). SilverBullet will automatically create the folder hierarchy on disk, if necessary.
|
||||
|
||||
What are some alternatives to using folders for organization? [[Tags]], primarily.
|
||||
@ -1,6 +1,17 @@
|
||||
There’s a progressive path in how people tend to install and deploy SilverBullet. Generally, it’s best to try it out on your local machine first. Play around a bit, see if it’s for you. Once you’re hooked, you may want to spend a little bit more time and host SilverBullet on a server in your local network or on the public Internet. SilverBullet is not currently available as a SaaS product, so you’ll have to install and run it yourself.
|
||||
There’s a progressive path in how people tend to install and deploy SilverBullet. Generally, it’s best to try it out on your local machine first. Play around a bit, see if it’s for you.
|
||||
|
||||
Instructions:
|
||||
* [[Install/Local]]: how to set up SilverBullet on your local machine
|
||||
* [[Install/Network and Internet]]: how to set up SilverBullet and expose it to your network or via the Internet
|
||||
* [[Install/Configuration]] of your instance
|
||||
Once you’re hooked, you may want to spend a little bit more time and host SilverBullet on a server in your local network or on the public Internet. SilverBullet is not currently available as a SaaS product, so you’ll have to install and run it yourself.
|
||||
|
||||
# Installation options
|
||||
Installing SilverBullet as a (local) web server is pretty straightforward if you’re technically inclined enough to be able to use a terminal.
|
||||
|
||||
The basic setup is simple: you run the SilverBullet server process on your machine, then connect to it locally from your browser via `localhost`.
|
||||
|
||||
You have a few options here:
|
||||
|
||||
1. Installation via [[Install/Deno]] (the awesome JavaScript runtime)
|
||||
2. Installation via [[Install/Docker]] (the awesome container runtime)
|
||||
3. More advanced: deploy directly to the cloud via [[Install/Deno Deploy]]
|
||||
|
||||
# Non-local access
|
||||
Once you got a comfortable set running locally, you may want to look at options to expose your setup to your [[Install/Network and Internet]].
|
||||
|
||||
@ -1,23 +1,12 @@
|
||||
SilverBullet is primarily configured via environment variables. This page gives a comprehensive overview of all configuration options. You can set these ad-hoc when running the SilverBullet server, or e.g. in your [[Install/Local$docker|docker-compose file]].
|
||||
SilverBullet is primarily configured via environment variables. This page gives a comprehensive overview of all configuration options. You can set these ad-hoc when running the SilverBullet server, or e.g. in your [[Install/Docker|docker-compose file]].
|
||||
|
||||
# Network
|
||||
$network
|
||||
Note: these options are primarily useful for [[Install/Deno]] deployments, not so much for [[Install/Docker]].
|
||||
|
||||
* `SB_HOSTNAME`: Set to the hostname to bind to (defaults to `127.0.0.0`, set to `0.0.0.0` to accept outside connections for the local deno setup, defaults to `0.0.0.0` for docker)
|
||||
* `SB_PORT`: Sets the port to listen to, e.g. `SB_PORT=1234`, default is `3000`
|
||||
|
||||
# Run mode
|
||||
$runmode
|
||||
|
||||
* `SB_SYNC_ONLY`: If you want to run SilverBullet in a mode where the server purely functions as a simple file store and doesn’t index or process content on the server, you can do so by setting this environment variable to `true`. As a result, the client will always run in the Sync [[Client Modes|client mode]].
|
||||
|
||||
# Security
|
||||
$security
|
||||
|
||||
SilverBullet enables plugs to run shell commands. This is used by e.g. the [[🔌 Git]] plug to perform git commands. This is potentially unsafe. If you don’t need this, you can disable this functionality:
|
||||
|
||||
* `SB_SHELL_BACKEND`: Enable/disable running of shell commands from plugs, defaults to `local` (enabled), set to `off` to disable. It is only enabled when using a local folder for [[$storage]].
|
||||
|
||||
# Authentication
|
||||
$authentication
|
||||
SilverBullet supports basic authentication for a single user.
|
||||
@ -27,7 +16,7 @@ SilverBullet supports basic authentication for a single user.
|
||||
|
||||
# Storage
|
||||
$storage
|
||||
SilverBullet supports multiple storage backends for keeping your [[Space]] content.
|
||||
SilverBullet supports multiple storage backends for keeping your [[Spaces]] content.
|
||||
|
||||
## Disk storage
|
||||
This is the default and simplest backend to use: a folder on disk. It is configured as follows:
|
||||
@ -90,6 +79,19 @@ The in-memory database is only useful for testing.
|
||||
|
||||
* `SB_DB_BACKEND`: `memory`
|
||||
|
||||
# Run mode
|
||||
$runmode
|
||||
|
||||
* `SB_SYNC_ONLY`: If you want to run SilverBullet in a mode where the server purely functions as a simple file store and doesn’t index or process content on the server, you can do so by setting this environment variable to `true`. As a result, the client will always run in the Sync [[Client Modes|client mode]].
|
||||
|
||||
# Security
|
||||
$security
|
||||
|
||||
SilverBullet enables plugs to run shell commands. This is used by e.g. the [[🔌 Git]] plug to perform git commands. This is potentially unsafe. If you don’t need this, you can disable this functionality:
|
||||
|
||||
* `SB_SHELL_BACKEND`: Enable/disable running of shell commands from plugs, defaults to `local` (enabled), set to `off` to disable. It is only enabled when using a local folder for [[$storage]].
|
||||
|
||||
|
||||
# Docker
|
||||
Configuration only relevant to docker deployments:
|
||||
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
> **warning** Experimental
|
||||
> This setup is not battle-tested, use it at your own risk
|
||||
|
||||
You can deploy SilverBullet to [Deno Deploy](https://deno.com/deploy) for free, and store space content in [Deno KV](https://deno.com/kv).
|
||||
You can deploy SilverBullet to [Deno Deploy](https://deno.com/deploy) for free, and store space content in [Deno KV](https://deno.com/kv). This is a convenient option to deploy SilverBullet in the cloud, without having to run or pay for a server.
|
||||
|
||||
# Steps
|
||||
Sign up for a (free) [Deno Deploy account](https://dash.deno.com/projects) and “Create an empty project” there.
|
||||
@ -25,10 +25,12 @@ $ deno install -Arf https://deno.land/x/deploy/deployctl.ts
|
||||
To deploy, run:
|
||||
|
||||
```shell
|
||||
deployctl deploy -p=your-project --entrypoint=https://silverbullet.md/silverbullet.js --include= --prod
|
||||
$ deployctl deploy -p=your-project --entrypoint=https://silverbullet.md/silverbullet.js --include= --prod
|
||||
```
|
||||
|
||||
# Migrating and backing up content
|
||||
If you want to migrate content _from_ or _to_ your new Deploy-based space, you can use [[Sync]]. For this be sure to also configure a `SB_AUTH_TOKEN` variable.
|
||||
This will ask you to authenticate with your Deno Deploy account, and then deploy SilverBullet.
|
||||
|
||||
For backup purposes, it may be wise to synchronize your content regularly this way.
|
||||
# Migrating and backing up content
|
||||
This setup stores you [[Spaces]] content in Deno’s KV database, which is still a beta feature and not specifically designed for this purpose. Therefore it’s recommended to use something like [[Sync]] to make backups elsewhere.
|
||||
|
||||
For this, be sure to also configure a `SB_AUTH_TOKEN` variable.
|
||||
48
website/Install/Deno.md
Normal file
48
website/Install/Deno.md
Normal file
@ -0,0 +1,48 @@
|
||||
The SilverBullet is implemented using a JavaScript runtime called [Deno](https://deno.com/) which is a lot like node.js, just... you know, better. And we like better.
|
||||
|
||||
To run SilverBullet directly on your host system (so not in a [[Install/Docker]] container), you need to install Deno [first following these instructions](https://deno.land/manual/getting_started/installation).
|
||||
|
||||
After having installed Deno, run:
|
||||
|
||||
```shell
|
||||
$ deno install -f --name silverbullet --unstable -A https://get.silverbullet.md
|
||||
```
|
||||
|
||||
You only have to do this once. This will download the currently _released_ version of SilverBullet onto your machine.
|
||||
|
||||
If you prefer to live on the _bleeding edge_, you can install using the following command instead:
|
||||
|
||||
```shell
|
||||
$ deno install -f --name silverbullet --unstable -A https://silverbullet.md/silverbullet.js
|
||||
```
|
||||
|
||||
Either command will install `silverbullet` into your `~/.deno/bin` folder (which should already be in your `$PATH` if you followed the Deno install instructions).
|
||||
|
||||
While you have [[Install/Configuration|options as to where and how to store your content]], the most straightforward way is to simply use a folder on disk.
|
||||
|
||||
After creating a folder, 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 (e.g. `-p8080`).
|
||||
|
||||
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 `-L0.0.0.0` flag (0.0.0.0 for all connections, or insert a specific address to limit the host), combined with `--user username:password` to add simple [[Authentication]].
|
||||
|
||||
Once downloaded and booted, SilverBullet will print out a URL to open in your browser.
|
||||
|
||||
# Upgrading
|
||||
SilverBullet is regularly updated. To get the latest and greatest, simply run:
|
||||
|
||||
```shell
|
||||
$ silverbullet upgrade
|
||||
```
|
||||
|
||||
And restart SilverBullet. You should be good to go.
|
||||
|
||||
Deno itself is also updated regularly, so be sure to let that self-upgrade as well:
|
||||
|
||||
```shell
|
||||
$ deno upgrade
|
||||
```
|
||||
94
website/Install/Docker.md
Normal file
94
website/Install/Docker.md
Normal file
@ -0,0 +1,94 @@
|
||||
# Introduction
|
||||
[Docker](https://www.docker.com/) is a convenient and secure way to install server applications either locally or on a server you control. If you don’t have docker already running on your machine and are macOS user, consider giving [OrbStack](https://orbstack.dev/) a try — it’s a super nice docker experience.
|
||||
|
||||
Conveniently, SilverBullet is published as a [docker image on docker hub](https://hub.docker.com/r/zefhemel/silverbullet). The image comes in two flavors:
|
||||
|
||||
* 64-bit Intel
|
||||
* 64-bit ARM (e.g. for Raspberry Pis and Apple Silicon macs)
|
||||
|
||||
There is no 32-bit version of Deno, and therefore we cannot offer a 32-bit version of SilverBullet either. Most people run 64-bit OSes these days, an exception may be Raspberry Pis. Recent (RPI 3 and later) can run 64-bit Linux as well, you may have to re-image, though.
|
||||
|
||||
A few key things to know about the SilverBullet container image:
|
||||
* The container binds to port `3000`, so be sure to port-map that, e.g. via `-p 3000:3000` (note: the first `3000` is the external port)
|
||||
* The container uses whatever is volume-mapped to `/space` as the space root folder. You can connect a docker volume, or a host folder to this, e.g. `-v /home/myuser/space:/space`
|
||||
* SilverBullet will detect the UNIX owner (UID and GID) of the folder mapped into `/space` and run the server process with the same UID and GID so that permissions will just magically work. If you’d like to override this UID, set the `PUID` and `PGID` environment variables (see [[Install/Configuration]] for details).
|
||||
|
||||
# Setup
|
||||
For your first run, you can run the following:
|
||||
|
||||
```shell
|
||||
# Create a local folder "space" to keep files in
|
||||
$ mkdir -p space
|
||||
# Run the SilverBullet docker container in the foreground
|
||||
$ docker run -it -p 3000:3000 -v ./space:/space zefhemel/silverbullet
|
||||
```
|
||||
|
||||
This will run SilverBullet in the foreground, interactively, so you can see the logs and instructions.
|
||||
|
||||
If this all works fine, just kill the thing with `Ctrl-c` (don’t worry, it’s ok).
|
||||
|
||||
Now you probably want to run the container in daemon (background) mode, give it a name, and automatically have it restart after you e.g. reboot your machine:
|
||||
|
||||
```shell
|
||||
$ docker run -d --restart unless-stopped --name silverbullet -p 3000:3000 -v ./space:/space zefhemel/silverbullet
|
||||
```
|
||||
|
||||
There you go!
|
||||
|
||||
# Versions
|
||||
The `zefhemel/silverbullet` image will give you the latest released version. This is equivalent to `zefhemel/silverbullet:latest`. If you prefer, you can also pin to a specific release, e.g. `zefhemel/silverbullet:0.5.5`. If you prefer to live on the bleeding edge, you can use the `zefhemel/silverbullet:edge` image, which is updated on every commit to the `main` brain. This is the YOLO option.
|
||||
|
||||
## Upgrade
|
||||
You can upgrade SilverBullet as follows:
|
||||
|
||||
```shell
|
||||
# Pull the latest version of the image
|
||||
$ docker pull zefhemel/silverbullet
|
||||
# Kill the running container
|
||||
$ docker kill silverbullet
|
||||
# Remove the old container
|
||||
$ docker rm silverbullet
|
||||
# Start a fresh one (same command as before)
|
||||
$ docker run -d --restart unless-stopped --name silverbullet -p 3000:3000 -v ./space:/space zefhemel/silverbullet
|
||||
```
|
||||
|
||||
Since this is somewhat burdensome, it is recommended you use a tool like [watchtower](https://github.com/containrrr/watchtower) to automatically update your docker images and restart them. However, if we go there — we may as well use a tool like _docker compose_ to manage your containers, no?
|
||||
|
||||
# Docker compose
|
||||
[Docker compose](https://docs.docker.com/compose/) is a simple tool to manage running of multiple containers on a server you control. It’s like Kubernetes, but you know, not insanely complex.
|
||||
|
||||
Here is a simple `compose.yml` that runs SilverBullet as well as [watchtower](https://github.com/containrrr/watchtower), which will check for new SilverBullet upgrades daily (the default) and upgrade automatically.
|
||||
|
||||
Instructions:
|
||||
* Please replace the password defined in `SB_USER` with something sensible such as `admin:b3stp4ssword3vah`
|
||||
* This volume uses the `./space` directory (that presumably exists) in the same directory as the `compose.yml` file as the place where SB will keep its space.
|
||||
* Check out [[Install/Configuration]] for more interesting `environment` variables you can set.
|
||||
|
||||
```yaml
|
||||
services:
|
||||
silverbullet:
|
||||
image: zefhemel/silverbullet
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
- SB_USER="admin:admin"
|
||||
volumes:
|
||||
- ./space:/space
|
||||
ports:
|
||||
- 3000:3000
|
||||
watchtower:
|
||||
image: containrrr/watchtower
|
||||
volumes:
|
||||
- /var/run/docker.sock:/var/run/docker.sock
|
||||
```
|
||||
|
||||
Boot this up via:
|
||||
|
||||
```shell
|
||||
$ docker-compose up -d
|
||||
```
|
||||
|
||||
And watch for logs with:
|
||||
|
||||
```shell
|
||||
$ docker-compose logs -f
|
||||
```
|
||||
@ -1,6 +1,6 @@
|
||||
Installing SilverBullet as a (local) web server is pretty straightforward, if you’re comfortable with the terminal, at least.
|
||||
Installing SilverBullet as a (local) web server is pretty straightforward if you’re technically inclined enough to be able to use a terminal.
|
||||
|
||||
The basic setup is simple: in a terminal, run the silverbullet server process on your machine, then connect to it locally from your browser via localhost.
|
||||
The basic setup is simple: in a terminal, run the silverbullet server process on your machine, then connect to it locally from your browser via `localhost`.
|
||||
|
||||
You have two options here:
|
||||
|
||||
@ -9,122 +9,3 @@ You have two options here:
|
||||
|
||||
After choose either, be sure to checkout all [[Install/Configuration]] options as well.
|
||||
|
||||
# Installing using Deno
|
||||
$deno
|
||||
This consists of two steps (unless [Deno](https://deno.com/) is already installed — in which case we’re down to one):
|
||||
|
||||
1. [Install Deno](https://deno.land/manual/getting_started/installation)
|
||||
2. Install SilverBullet itself (steps below)
|
||||
|
||||
After having installed Deno ([instructions on its website](https://docs.deno.com/runtime/manual/getting_started/installation)) run:
|
||||
|
||||
```shell
|
||||
deno install -f --name silverbullet --unstable -A https://get.silverbullet.md
|
||||
```
|
||||
|
||||
You only have to do this once.
|
||||
|
||||
This will give you (and when you use `silverbullet upgrade`) the latest stable release. If you prefer to live on the bleeding edge, you can install using the following command instead:
|
||||
|
||||
```shell
|
||||
deno install -f --name silverbullet --unstable -A https://silverbullet.md/silverbullet.js
|
||||
```
|
||||
|
||||
Either command 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 `-L0.0.0.0` flag (0.0.0.0 for all connections, or insert a specific address to limit the host), combined with `--user username:password` to add simple [[Authentication]].
|
||||
|
||||
Once downloaded and booted, SilverBullet will print out a URL to open 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. Also run
|
||||
|
||||
```shell
|
||||
deno upgrade
|
||||
```
|
||||
|
||||
Regularly, to get the latest and greatest deno.
|
||||
|
||||
# Installing using Docker
|
||||
$docker
|
||||
There is a [docker image on docker hub](https://hub.docker.com/r/zefhemel/silverbullet). The image comes in two flavors:
|
||||
|
||||
* 64-bit Intel
|
||||
* 64-bit ARM (e.g. for Raspberry Pis and Macs)
|
||||
|
||||
There is no 32-bit version of Deno, and therefore we cannot offer a 32-bit version of SilverBullet either. Most people run 64-bit OSes these days, an exception may be Raspberry Pis. Recent (RPI 3 and later) can run 64-bit Linux as well, you may have to re-image, though.
|
||||
|
||||
A few key things to note on the SilverBullet container:
|
||||
* The container binds to port `3000`, so be sure to export that, e.g. via `-p 3000:3000` (note: the first `3000` is the external port)
|
||||
* The container uses whatever is volume-mapped to `/space` as the space root folder. You can connect a docker volume, or a host folder to this, e.g. `-v /home/myuser/space:/space`
|
||||
* SilverBullet will, conveniently, detect the UNIX owner (UID and GID) of the folder mapped into `/space` and run the server process with the same UID and GID so that permissions will just magically work. If you’d like to override this UID, set the `PUID` and `PGID` environment variables.
|
||||
|
||||
To boot up the container:
|
||||
|
||||
```shell
|
||||
docker run -p 3000:3000 -v /path/to/space/folder:/space -d zefhemel/silverbullet
|
||||
```
|
||||
|
||||
The `zefhemel/silverbullet` image will give you the latest released version. This is equivalent to `zefhemel/silverbullet:latest`. If you prefer, you can also pin to a specific release, e.g. `zefhemel/silverbullet:0.5.5`. If you prefer to live on the bleeding edge, you can use the `zefhemel/silverbullet:edge` image, which is updated on every commit to the `main` brain.
|
||||
|
||||
To configure various things such as authentication, use [[@env|environment variables]], e.g. to enable single-user auth:
|
||||
|
||||
```shell
|
||||
docker run -p 3000:3000 -v myspace:/space -d -e SB_USER=me:letmein zefhemel/silverbullet
|
||||
```
|
||||
|
||||
## Upgrade
|
||||
You can upgrade your image simply by pulling a new version of the image using `docker pull zefhemel/silverbullet`. However, it is recommended you use a tool like [watchtower](https://github.com/containrrr/watchtower) to automatically update your docker images and restart them.
|
||||
|
||||
## Docker compose
|
||||
Here is a simple `compose.yml` that runs SilverBullet as well as [watchtower](https://github.com/containrrr/watchtower), which will check for new SilverBullet upgrades daily (the default) and upgrade automatically.
|
||||
|
||||
Instructions:
|
||||
* Please replace the password defined in `SB_USER` with something sensible such as `admin:b3stp4ssword3vah`
|
||||
* This volume uses the `notes` directory (that presumably exists) in the same directory as the `compose.yml` file as the place where SB will keep its space.
|
||||
|
||||
```yaml
|
||||
services:
|
||||
silverbullet:
|
||||
image: zefhemel/silverbullet:edge
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
- SB_USER="admin:admin"
|
||||
volumes:
|
||||
- ./notes:/space
|
||||
ports:
|
||||
- 3000:3000
|
||||
watchtower:
|
||||
image: containrrr/watchtower
|
||||
volumes:
|
||||
- /var/run/docker.sock:/var/run/docker.sock
|
||||
```
|
||||
|
||||
Boot this up via:
|
||||
|
||||
```shell
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
And watch for logs with:
|
||||
|
||||
```shell
|
||||
docker-compose logs -f
|
||||
```
|
||||
|
||||
## Building the docker image
|
||||
To build your own version of the docker image, run `./scripts/build_docker.sh`.
|
||||
|
||||
@ -1,13 +1,13 @@
|
||||
Running SilverBullet [[Install/Local|locally]] on your machine is cool, but you likely want to access it from elsewhere as well (other machines on your network, your mobile device), perhaps even from outside your home. For this you either need to use a VPN, or expose SB to the public Internet via _HTTPS_.
|
||||
Running SilverBullet locally on your machine is cool and all, but you likely want to access it from elsewhere as well (other machines on your network, your mobile device), perhaps even from outside your home. For this you either need to use a VPN, or expose SB to the public Internet via _HTTPS_.
|
||||
|
||||
In either scenario, be sure to enable some sort of [[Authentication]].
|
||||
|
||||
There’s two parts to this process:
|
||||
|
||||
1. Run the SilverBullet server itself somewhere, following the [[Install/Local]] instructions
|
||||
1. Run the SilverBullet server itself somewhere, following the [[Install]] instructions
|
||||
2. Exposing this server to the network/Internet
|
||||
|
||||
In all scenarios (that are not [[Install/Local]]) you _have_ to access SilverBullet via HTTPS otherwise certain features (such offline-support) won’t work.
|
||||
In all scenarios (that are not local) you _have_ to access SilverBullet via HTTPS, otherwise certain features (such offline-support) won’t work.
|
||||
|
||||
People have found various simple to more complex ways of achieving this.
|
||||
|
||||
|
||||
@ -1,28 +1,44 @@
|
||||
Welcome to wonderful world of SilverBullet. The goal of this manual is to give you a broad sense of how to use this tool and what it’s capable of. However, its full capabilities are yet to be discovered. Every day, people find new and creative ways to use the various SilverBullet features in ways nobody previously thought of. Perhaps you will be one of those people.
|
||||
Welcome to wonderful world of SilverBullet. The goal of this manual is to give you a broad sense of how to use this tool and what it’s capable of. However, its full capabilities are yet to be discovered. You too may find new and creative ways to use the various SilverBullet features in ways nobody previously thought of.
|
||||
|
||||
However, that is unlikely to happen unless you understand some of the basics. So let’s start there.
|
||||
However, that is all unlikely to happen unless you understand what SilverBullet can actually do. So let’s give you a bit of a sense.
|
||||
|
||||
> **warning** Warning
|
||||
> This manual is **very** much a work in progress.
|
||||
|
||||
## Keeping up-to-date
|
||||
* [[CHANGELOG]]: what’s new in SilverBullet
|
||||
# Keeping up-to-date
|
||||
* [[CHANGELOG]]: what’s new in SilverBullet? This page will give you the latest details. It’s worth monitoring this page, especially if something broke for you.
|
||||
|
||||
## Installation and deployment
|
||||
* [[Install]]
|
||||
# Installation and deployment
|
||||
The biggest hurdle to get over with SilverBullet is that you need to get this thing running. And as of yet, the only way to do that is to install and deploy it yourself. 🤷
|
||||
|
||||
* [[Install]]: Installation instructions for various setups
|
||||
* [[Deployments]]: various deployment options
|
||||
* [[Install/Deno Deploy|Deploying on Deno Deploy with S3]] (experimental)
|
||||
* [[Authelia]]: configuring SilverBullet with [Authelia](https://www.authelia.com/) authentication.
|
||||
* [[Guide/Deployment/Cloudflare and Portainer]]: configuring SilverBullet with a Cloudflare tunnel, portainer and optional Cloudflare zero trust authentication.
|
||||
|
||||
## Use
|
||||
# User interface
|
||||
* [[Manual/Page Picker]]
|
||||
* [[Manual/Command Palette]]
|
||||
* [[Client Modes]] (that sync button)
|
||||
|
||||
# Core Concepts
|
||||
These are some
|
||||
* [[Spaces]]
|
||||
* [[Pages]]
|
||||
* [[Frontmatter]]
|
||||
* [[Folders]]
|
||||
* [[Attachments]]
|
||||
* [[Templates]]
|
||||
|
||||
# Editing and Formatting
|
||||
* [[Markdown]]
|
||||
* [[Markdown/Syntax Highlighting]]
|
||||
* [[Markdown/Code Widgets]]
|
||||
* [[Manual/Outlines]]
|
||||
* [[End-User Programming]]
|
||||
* [[Objects]]
|
||||
* [[Frontmatter]]
|
||||
* [[Attributes]]
|
||||
* [[Live Queries]]
|
||||
* [[Live Templates]]
|
||||
* [[Objects]]
|
||||
* [[Frontmatter]]
|
||||
* [[Attributes]]
|
||||
* [[SETTINGS]]: A few settings you can tweak
|
||||
* [[Manual/Outlines]]
|
||||
|
||||
@ -1,4 +1,6 @@
|
||||
Markdown is a plain text formatting system [originally developed by John Gruber](https://daringfireball.net/projects/markdown/). It has since been standardized into [CommonMark](https://commonmark.org/), which is what SilverBullet uses (with [[Markdown/Extensions]]). While a bit more technical than [WYSIWYG](https://pl.wikipedia.org/wiki/WYSIWYG)-style editing (like MS Word), the nice thing about markdown is that it is a (relatively) easy-to-implement standard, and you can read files even without special tools (like SilverBullet). This means that you’ll always have access to the content even if you switch tools. It also means that you can use multiple tools at the same time to edit these files. You don’t have to use SilverBullet exclusively.
|
||||
Markdown is a plain text formatting system [originally developed by John Gruber](https://daringfireball.net/projects/markdown/). It has since been standardized into [CommonMark](https://commonmark.org/), which is what SilverBullet uses (with [[Markdown/Extensions]]). While a bit more technical than [WYSIWYG](https://pl.wikipedia.org/wiki/WYSIWYG)-style editing (like MS Word), the nice thing about markdown is that it is a (relatively) easy-to-implement standard, and you can read files even without special tools (like SilverBullet).
|
||||
|
||||
This means that _you will always have access to the content_ even if you switch tools. It also means that you can use multiple tools at the same time to edit these files. You don’t have to use SilverBullet exclusively.
|
||||
|
||||
There is a bit of a caveat here: Markdown is limited in certain ways, and various tools using markdown as the underlying file format (like SilverBullet) need features that are not directly supported by markdown. As a result, different tools introduce extensions to markdown that are not standard nor interoperable. While in some cases, these tools converge on particular pieces of syntax (such as the non-standard `[[page link]]` syntax), some level of divergence in the markdown that each tool supports is unavoidable. SilverBullet is complicit in this as well. It adds a few extensions that are not widely supported and assigns new meaning to certain markdown features to implement novel features. In its defense, all these features are optional. If you want to just write plain markdown, you can.
|
||||
|
||||
@ -8,3 +10,4 @@ More about markdown:
|
||||
|
||||
* [[Markdown/Basics]]: learn some the markdown basics
|
||||
* [[Markdown/Extensions]]: learn about SilverBullet’s set of markdown extensions
|
||||
* [[Markdown/Syntax Highlighting]]: languages that SilverBullet supports syntax highlighting for
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
Metadata is data about data. Most [[Objects]] have a set of default attributes that can be augmented in a few additional ways:
|
||||
|
||||
* [[Tags]]: to tag the object (and add to the `tags` attribute directly)
|
||||
* [[Frontmatter]]: at the top of pages, a [[YAML]] encoded block can be used to define additional attributes to a page
|
||||
* [[Frontmatter]]: at the top of [[Pages]], a [[YAML]] encoded block can be used to define additional attributes to a page
|
||||
* [[Attributes]] syntax
|
||||
|
||||
5
website/Pages.md
Normal file
5
website/Pages.md
Normal file
@ -0,0 +1,5 @@
|
||||
The primary thing you’ll be doing in SilverBullet (hopefully) is creating and editing pages. Pages are written in [[Markdown]], can contain [[Metadata]] and are kept on the server as text files.
|
||||
|
||||
There’s not much more to say about pages.
|
||||
|
||||
Ah one thing, [[Templates]] are “special” types of page that can be used for various purposes (e.g. as a _template_ for a new page, or to render [[Live Queries]] and [[Live Templates]]).
|
||||
@ -1,14 +1,17 @@
|
||||
SilverBullet aims to be your **workshop for the mind**: a creative [[Space]] where you collect, create and expand your personal knowledge, while also letting you constantly evolve the tools you use to do so.
|
||||
# Introduction
|
||||
SilverBullet aims to be your **workshop for the mind**: a creative [[Spaces]] where you collect, create and expand your personal knowledge, while also letting you constantly evolve the tools you use to do so.
|
||||
|
||||
While you _can_ use SilverBullet as a simple note taking application that stores notes in plain [[Markdown]] files on disk, it becomes truly powerful in the hands of more technical power users. By leveraging [[Metadata]] annotations, its [[Objects]] infrastructure, [[Live Queries]] and [[Live Templates]], SilverBullet becomes a powerful _end-user programming tool_, enabling you to quickly develop various types of ad-hoc knowledge applications.
|
||||
So yes, it’s basically a somewhat geeky note taking application.
|
||||
|
||||
SilverBullet is implemented as an _open-source_, _self-hosted_, _offline-capable_ web application (PWA).
|
||||
While you _can_ use SilverBullet as just a note taking application that stores notes in plain [[Markdown]] files on disk, it becomes truly powerful in the hands of more technical power users. By leveraging [[Metadata]] annotations, its [[Objects]] infrastructure, [[Live Queries]] and [[Live Templates]], SilverBullet becomes a powerful [[End-User Programming]] tool, enabling you to quickly develop various types of ad-hoc knowledge systems.
|
||||
|
||||
You’ve been told there is _no such thing_ as a [silver bullet](https://en.wikipedia.org/wiki/Silver_bullet).
|
||||
SilverBullet is implemented as an _open-source_, _self-hosted_, _offline-capable_ web application (PWA). In order to use it, you have to self host it: that is, you need to run the web server either on your own machine or in the cloud somewhere. See [[Install]] for instructions.
|
||||
|
||||
You may have been told there is _no such thing_ as a [silver bullet](https://en.wikipedia.org/wiki/Silver_bullet).
|
||||
|
||||
You were told wrong.
|
||||
|
||||
# Quick links
|
||||
# Links for the impatient
|
||||
* [[Install]]: how to install and deploy SilverBullet
|
||||
* [[Manual]]: the beginnings of a user manual
|
||||
* [[CHANGELOG]]: SilverBullet is in active development, so things change rapidly. Watch this to see what’s new and changed.
|
||||
@ -21,20 +24,20 @@ You were told wrong.
|
||||
* [Discord](https://discord.gg/EvXbFucTxn): For more real-time support and discussion, join our Discord!
|
||||
|
||||
# Features
|
||||
So, what does this thing do anyway?
|
||||
Alright then. Beyond the fancy, aspirational vision-y talk. What does this thing actually do and how does it work? You know... features, we need a feature list!
|
||||
|
||||
SilverBullet...
|
||||
* Runs in any modern browser (including on mobile) as a [[PWA]] in two [[Client Modes]] (_online_ and _synced_ mode), where the _synced mode_ enables **100% offline operation**, keeping a copy of content in the browser, syncing back to the server when a network connection is available.
|
||||
* Runs in any modern browser (including on mobile) as a [[PWA]] in two [[Client Modes]] (_online_ and _synced_ mode), where the _synced mode_ enables **100% offline operation**, keeping a copy of content in the browser’s local ([IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API)) database, 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. Incoming links are indexed and appear as “Linked Mentions” at the bottom of the pages linked to thereby providing _bi-directional linking_.
|
||||
* Supports wiki-style **page linking** using the `[[page link]]` syntax. Incoming links are indexed and appear as [[Linked Mentions]] at the bottom of the pages linked to thereby providing _bi-directional linking_.
|
||||
* Optimized for **keyboard-based operation**:
|
||||
* Quickly navigate between pages using the **page switcher** (triggered with `Cmd-k` on Mac or `Ctrl-k` on Linux and Windows).
|
||||
* Run commands via their keyboard shortcuts or the **command palette** (triggered with `Cmd-/` or `Ctrl-/` on Linux and Windows).
|
||||
* Use [[Slash Commands]] to perform common text editing operations.
|
||||
* Provides a platform for [end-user programming](https://www.inkandswitch.com/end-user-programming/) through its support for [[Objects]], [[Live Queries]] and [[Live Templates]].
|
||||
* Provides a platform for [end-user programming](https://www.inkandswitch.com/end-user-programming/) through its support for [[Objects]], [[Live Queries]] and [[Live Templates]], allowing to make parts of your pages _dynamic_.
|
||||
* Robust extension mechanism using [[🔌 Plugs]].
|
||||
* **Self-hosted**: you own your data. All content is stored as plain files in a folder on disk. Back up, sync, edit, publish, script with any additional tools you like.
|
||||
* SilverBullet is [open source, MIT licensed](https://github.com/silverbulletmd/silverbullet) software.
|
||||
* SilverBullet is free, [open source, MIT licensed](https://github.com/silverbulletmd/silverbullet) software.
|
||||
|
||||
To get a good feel of what SilverBullet is capable of, have a look at this (slightly out of date) introduction video.
|
||||
|
||||
@ -48,7 +51,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 syncs back (successfully) to the server. You are editing a local copy of this website, so changes do persist locally.
|
||||
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. It’s not a perfect rendition of the actual SilverBullet experience, but pretty close.
|
||||
|
||||
Don’t just sit there, try it!
|
||||
|
||||
@ -63,9 +66,9 @@ 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). Now, unplug your network cable and reload the page. It still works!
|
||||
browser or recent version of Safari)? 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:
|
||||
At the core of SilverBullet is [[Markdown]] with some added fancier features like tables:
|
||||
|
||||
| Page | Comment |
|
||||
|----------|----------|
|
||||
@ -76,7 +79,7 @@ or code snippets, like JavaScript:
|
||||
|
||||
```javascript
|
||||
function helloWorld() {
|
||||
return "Hello there!"
|
||||
return "Look at my I'm JavaScript!";
|
||||
}
|
||||
```
|
||||
|
||||
@ -87,30 +90,22 @@ name: SilverBullet
|
||||
rating: 5
|
||||
```
|
||||
|
||||
# Advanced features
|
||||
Where things get _really_ interesting is when using features like [[Live Queries]] that allow you to query all types of [[Objects]] indexed based on the pages in your [[Space]].
|
||||
# Beyond Markdown
|
||||
Where things get _really_ interesting is when using features like [[Live Queries]] that allow you to query all types of [[Objects]] indexed based on the pages in your [[Spaces]].
|
||||
|
||||
Let’s explore this with a meta example of using this functionality for this very website. All pages in this space that represent a [[🔌 Plugs|plug]] are tagged with the `#plug` tag. Now, if we would want to render a list of all plugs in one place using the [[template/plug]] template, we can simply do this:
|
||||
Let’s explore this with a meta example of using this functionality for this very website. All pages in this space that represent a [[🔌 Plugs|plug]] are tagged with the `#plug` tag. Now, if we would want to render a list of all plugs in one place using the [[template/plug]] template, we can simply do this as follows:
|
||||
|
||||
```query
|
||||
plug render [[template/plug]]
|
||||
```
|
||||
Hover over that list, click the edit button to see the query that generates this view.
|
||||
|
||||
And it’s not just pages that can be queried, there’s a large variety of queriable sources and you can define your own via tags. Examples include `task`s, `page`s, `tag`s, and `link`s.
|
||||
|
||||
For instance, here’s a list of all outgoing page links from this page:
|
||||
```query
|
||||
link where page = "{{@page.name}}" select toPage as name render [[template/page]]
|
||||
```
|
||||
The sky is the limit. See [[Objects]] and [[Live Queries]] for more information.
|
||||
|
||||
For additional productivity boosts, have a look at SilverBullet’s [[Templates]] functionality.
|
||||
And it’s not just pages that can be queried, there’s a large variety of queriable sources and you can define your own via tags. Examples include `task`s, `page`s, `tag`s, and `link`s. The sky is the limit. See [[Objects]] and [[Live Queries]] for more information.
|
||||
|
||||
# Install SilverBullet
|
||||
Has your mind been sufficiently blown to commit to an install? Took you long enough, alright then. Please proceed to [[Install]] and enjoy!
|
||||
|
||||
# Support
|
||||
If you (hypothetically) find bugs or have feature requests, post them in [our issue tracker](https://github.com/silverbulletmd/silverbullet/issues). Want to contribute? [Check out the code](https://github.com/silverbulletmd/silverbullet).
|
||||
If you (hypothetically) find bugs (we prefer to call them “features”) or have feature requests, post them in [our issue tracker](https://github.com/silverbulletmd/silverbullet/issues). Want to contribute? [Check out the code](https://github.com/silverbulletmd/silverbullet).
|
||||
|
||||
Want to chat with us? [Join our Discord](https://discord.gg/EvXbFucTxn)!
|
||||
@ -1,13 +0,0 @@
|
||||
A _space_ is SilverBullet terminology for a workspace, or project. [Obsidian](https://obsidian.md/) calls this a vault, [LogSeq](https://logseq.com/) calls it a graph. You may think of it as a folder or a directory — because in practical terms, that’s all it is.
|
||||
|
||||
Feel free to back-up or manipulate your space;s folder and its files with whatever tool you like — you don’t have to use SilverBullet exclusively. You may want to turn your space’s folder into a git repository, for instance, and do version control and back-ups that way — in which case you may appreciated the [[🔌 Git]] plug.
|
||||
|
||||
# Pages
|
||||
All pages in your space are stored as files with a `.md` file extension. While _folders_ are not really a first-class concept in SilverBullet, you can create pages with a `/` in their name, which will (under the hood) automatically create a folder structure to match it. So creating a page named `people/John` will ensure a `people` folder in your space’s root, and put a `John.md` file in it.
|
||||
|
||||
# Attachments
|
||||
Attachments are kept alongside the rest of your files with whatever file extension they have (e.g. `.jpg` for images, or `.pdf` for PDFs).
|
||||
|
||||
# Folder lay-out
|
||||
Every space in SilverBullet at the very least has an index page (by default named `index.md`) and a SETTINGS page (named `SETTINGS.md`). If you install custom [[🔌 Plugs]], these will be kept under `_plug` in your space’s folder.
|
||||
|
||||
12
website/Spaces.md
Normal file
12
website/Spaces.md
Normal file
@ -0,0 +1,12 @@
|
||||
A _space_ is SilverBullet terminology for a workspace, or project. [Obsidian](https://obsidian.md/) calls this a vault, [LogSeq](https://logseq.com/) calls it a graph. You may think of it as a [[Folders|folder]] or a directory — because in practical terms, that’s all it is.
|
||||
|
||||
Feel free to back-up or manipulate your space’s folder and its files with whatever tool you like — you don’t have to use SilverBullet exclusively. You may want to turn your space’s folder into a git repository, for instance, and do version control and back-ups that way — in which case you may appreciated the [[🔌 Git]] plug.
|
||||
|
||||
A space consists of
|
||||
* [[Folders]]
|
||||
* [[Pages]]
|
||||
* [[Attachments]]
|
||||
|
||||
# Folder lay-out
|
||||
Every space in SilverBullet at the very least has an index page (by default named `index.md`) and a [[SETTINGS]] page (named `SETTINGS.md`). If you install custom [[🔌 Plugs]], these will be kept under `_plug` in your space’s folder.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user