neil/silverbullet
1
0
Fork 0
Code

Rebranding from "Silver Bullet" to "SilverBullet" and updated a lot of website copy

Browse Source
This commit is contained in:
Zef Hemel 2023-01-16 16:45:55 +01:00
parent c8f0304ade
commit 18c1da4431
52 changed files with 302 additions and 290 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

101
README.md
View File

@ -1,6 +1,6 @@
# SilverBullet
Silver Bullet (SB) is an extensible, open source **personal knowledge
SilverBullet is an extensible, open source **personal knowledge
platform**. At its core it’s a clean markdown-based writing/note taking
application that stores your _pages_ (notes) as plain markdown files in a folder
referred to as a _space_. Pages can be cross-linked using the
@ -40,103 +40,8 @@ Or checkout these two videos:
[plugs](https://silverbullet.md/🔌_Plugs), and you can customize it to your
liking and your workflows.
## Installing Silver Bullet with Deno
### Installing Deno
Silver Bullet is built using [Deno](https://deno.land). To install Deno on Linux
or Mac run:
```shell
curl -fsSL https://deno.land/install.sh | sh
```
This will install Deno into `~/.deno/bin`, add this folder to your `PATH` in
your `~/.bashrc` or `~/.zshrc` file.
To install Deno on Windows (using Powershell) run:
```powershell
irm https://deno.land/install.ps1 | iex
```
### Install Silver Bullet
With Deno installed (see instruction above), 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 installed Deno following the previous
instructions).
To run Silver Bullet 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, SB will bind to port `3000` on all interfaces. To specify a
different address or port to listen on, use the `--hostname` and `--port`
options. By default SB doesn’t add authentication, to add
basic password authentication (BasicAuth), pass the `--user` flag (e.g.
`--user pete:1234` for username `pete` and password `1234`).
Once downloaded and booted, SB will print out a URL to open SB in your browser
(spoiler alert: by default this will be http://localhost:3000 ).
#protip: If you have a PWA enabled browser (like any browser based on Chromium)
hit that little button right of the location bar to install SB, and give it its
own window frame (sans location bar) and desktop/dock icon. At last the PWA has
found its killer app.
## Upgrading Silver Bullet
Simply run this:
silverbullet upgrade
And restart Silver Bullet. You should be good to go.
## Installing Silver Bullet 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
```
## Installing SilverBullet
Check out the [official website](https://silverbullet.md)
## Troubleshooting
If you upgraded to the new Deno-based SilverBullet from an old version, you may

3
build_mobile.ts
View File

@ -11,9 +11,6 @@ if (import.meta.main) {
},
});
await bundle(args.watch, "mobile", "mobile/dist");
await copy("mobile/index.html", `mobile/dist/index.html`, {
overwrite: true,
});
if (!args.watch) {
esbuild.stop();
}

1
common/util.ts
View File

@ -66,6 +66,7 @@ export async function ensureAndLoadSettings(
`Hello! And welcome to your brand new SilverBullet space!
<!-- #include [[💭 silverbullet.md/Getting Started]] -->
Loading some onboarding content for you (but doing so does require a working internet connection)...
<!-- /include -->`,
);
}

47
mobile/index.html
View File

@ -1,47 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport"
content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no" />
<base href="/" />
<title>Silver Bullet</title>
<script>
Deno = {
args: [],
build: {
arch: "x86_64",
},
env: {
get(key) {
// return undefined;
},
},
errors: {
AlreadyExists: class extends Error { },
}
};
</script>
<style>
html,
body {
margin: 0;
height: 100%;
padding: 0;
width: 100%;
overflow: hidden;
}
</style>
<link rel="stylesheet" href="/main.css" />
<script type="module" src="/client.js"></script>
<link rel="manifest" href="/manifest.json" -->
<link rel="icon" type="image/x-icon" href="/favicon.png" />
</head>
<body>
<div id="sb-root"></div>
</body>
</html>

2
scripts/build_demo.sh
View File

@ -17,6 +17,8 @@ cp -r dist_bundle/web/* website_build/
echo "And all plugs"
cp -r dist_bundle/_plug/* website_build/fs/_plug/
echo "And additional ones"
curl https://raw.githubusercontent.com/silverbulletmd/silverbullet-mermaid/main/mermaid.plug.json > website_build/fs/_plug/mermaid.plug.json
echo "But remove some plugs"
rm -rf website_build/fs/_plug/{directive,plugmd,publish,share}.plug.json
#echo "Copying netlify config files"

6
web/index.html
View File

@ -3,7 +3,8 @@
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width" />
<meta name="viewport"
content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no" />
<base href="/" />
<title>SilverBullet</title>
@ -40,7 +41,8 @@
</head>
<body>
<div id="sb-root"></div>
<div id="sb-root">
</div>
</body>
</html>

26
website/Desktop.md Normal file
View File

@ -0,0 +1,26 @@
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 access 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).

5
website/Download.md Normal file
View File

@ -0,0 +1,5 @@
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.

41
website/Getting Started.md
View File

@ -1,26 +1,43 @@
## Getting started
The best way to get a good feel for what SilverBullet is like to use, is to get your hands dirty (after washing your hands first, always wash your hands before touching a keyboard).
---
$disableDirectives: true
---
Here are some things for you to try _right now_:
## Getting started
The best way to get a good feel for what SilverBullet is like to use is to get your hands dirty. Not literally, that would be disgusting — wash your hands _before_ using SilverBullet please, keyboards are gross enough already, and before you say “but I’m using this on mobile” — don’t even get me started on mobile phone screens.
After your hands are properly washed, here are some things for you to try:
* Click on the page picker (book icon) icon at the top right, or hit `Cmd-k` (Mac) or `Ctrl-k` (Linux and Windows) to open the **page switcher**.
* Type the name of a non-existent page to create it.
* You can pages in folders (if you’re into that type of thing) simply by putting slashes (`/`) in the name (even on Windows), e.g. [[My Folder/My Page]] (note that although you only see the last bit of the name in live preview, the page is in fact nested in a folder).
* Click on the terminal button (top right) or hit `Cmd-/` (Mac) or `Ctrl-/` (Linux and Windows) to open the **command palette** (note that not all commands will work in this mode). On mobile you can tap the screen with 3 fingers at the same time to open the command palette.
* You _can_ create pages in folders (if you’re into that type of thing) simply by putting slashes (`/`) in the name (even on Windows), e.g. [[My Folder/My Page]] (note that although you only see the last bit of the name in live preview, the page is in fact nested in a folder).
* Click on the terminal icon (top right), hit `Cmd-/` (Mac) or `Ctrl-/` (Linux and Windows), or tap the screen with 3 fingers at the same time (on mobile) to open the **command palette**. The {[Stats: Show]} one is a safe one to try.
* Select some text and hit `Alt-m` to ==highlight== it, or `Cmd-b` (Mac) or `Ctrl-b` (Windows/Linux) to make it **bold**, or `Cmd-i` (Mac) or `Ctrl-i` (Windows/Linux) to make it _italic_.
* Click a link somewhere on this page to navigate there. When you link to a [[New Page]] it will initially show up in red (to indicate it does not yet exist), but once you click it — you will create the page automatically (only for real when you actually enter some text).
* Start typing `[[` somewhere to insert a page link (with completion).
* Start typing `[[` somewhere to insert your own page link (with completion).
* [ ] Tap this box 👈 to mark this task as done.
* Start typing `:party` to trigger the emoji picker 🎉
* Type `/` somewhere in the text to invoke a **slash command**.
* Hit `Cmd-p` (Mac) or `Ctrl-p` (Windows, Linux) to show a preview for the current page on the side.
* Click this button {[Editor: Toggle Vim Mode]} to toggle Vim mode
* If this is matching your personality type, you can click this button {[Editor: Toggle Vim Mode]} to toggle Vim mode. If you cannot figure out how to exit it, just click that button again. _Phew!_
Note that as you move your cursor around on this page and you get close to or “inside” marked up text, you will get to see the underlying [[💭 silverbullet.md/Markdown|Markdown]] code, this is what we refer to as “live preview” — generally your text looks clean, but you still can see what’s under the covers. To move your cursor somewhere by mouse without navigating or activating (e.g. a wiki, regular link, or a button) hold `Alt` when you click.
Notice that as you move your cursor around on this page and you get close to or “inside” marked up text, you will get to see the underlying [[💭 silverbullet.md/Markdown|Markdown]] code. This experience is what we refer to as “live preview” — generally your text looks clean, but you still can see what’s under the covers and edit it directly, as opposed to [WYSIWYG](https://en.wikipedia.org/wiki/WYSIWYG) that some other applications use. To move your cursor somewhere using your mouse without navigating or activating (e.g. a wiki, regular link, or a button) hold `Alt` when you click. Holding `Cmd` or `Ctrl` when clicking a link will open it in a new tab or window.
Hadn’t we mentioned [[💭 silverbullet.md/Markdown|Markdown]] yet? Yeah, that’s the markup language you’ll use to markup your documents. It’s pretty simple to learn if you don’t know it already.
Hadn’t we mentioned [[💭 silverbullet.md/Markdown|Markdown]] yet? Yeah, that’s the markup language you’ll use to add that dash of markup to your documents. It’s pretty simple to learn if you don’t know it already.
You will notice this whole page block is wrapped in a [[💭 silverbullet.md/%F0%9F%94%8C_Directive|Directive]] (in this case `#include`), which means that its content is automatically updated every time you run the {[Directives: Update]} command or navigate back to the page. In the case of `#include` this means the body will be replaced with the page included, so don’t be surprised when whatever you update inside of this directive block will be undone later. Just sayin’. [[💭 silverbullet.md/%F0%9F%94%8C_Directive|Directives]] are a powerful feature, so you should definitely look into them once you get comfortable with the basics.
You will notice this whole page section is wrapped in a strange type of block. This is a SilverBullet specific feature called a [[💭 silverbullet.md/%F0%9F%94%8C_Directive|Directive]] (in this case `#include`). There are various types of directives, and while we’re not keeping score, likely the coolest ones are [[💭 silverbullet.md/%F0%9F%94%8C_Directive/Query|queries]] — so you should definitely look into those.
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 -->
If you’re seeing this, something didn’t update quite right...
<!-- /query -->
That said, the directive used wrapping this page section is `#include` which simply inlines the content of another page into the current one. Directives recalculate their bodies in two scenarios:
1. When you load/switch to a page
2. When you explicitly run the {[Directives: Update]} command
In the case of `#include` this means the body will again be replaced with the page included, so don’t be surprised when whatever you just updated inside of this directive block will be undone later. Just sayin’. [[💭 silverbullet.md/%F0%9F%94%8C_Directive|Directives]] are a powerful feature, so you should definitely look into them once you get comfortable with the basics.
Feel free to completely remove all content on this page and make it your own, it’s just to get you started.
@ -28,4 +45,6 @@ Feel free to completely remove all content on this page and make it your own, it
Generally, you can find more information about SilverBullet on its official website. You have two ways to access it:
1. Through its [regular website link](https://silverbullet.md/)
2. Directly, through your local SilverBullet instance using [[💭 silverbullet.md/Cloud Links]]: [[💭 silverbullet.md/Silver Bullet]] (note that all of these will be read-only, for obvious reasons)
2. Directly without leaving SilverBullet, through [[💭 silverbullet.md/Cloud Links]], just click on this: [[💭 silverbullet.md/SilverBullet]] (note that all of these will be read-only, for obvious reasons)
To keep up with the latest and greatest going-ons in SilverBullet land, keep an eye on the [[💭 silverbullet.md/CHANGELOG]], regularly update your SilverBullet instance (`silverbullet upgrade` if you’re running the Deno version). If you run into any issues or have ideas on how to make SilverBullet even awesomer (yes, that’s a word), [join the conversation on GitHub](https://github.com/silverbulletmd/silverbullet).

4
website/Markdown.md
View File

@ -1,6 +1,8 @@
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 some extensions).
Specifically, Silver Bullet supports the following extensions to common mark:
If you’re not yet familiar with Markdown [here is a good guide to get you started](https://www.markdownguide.org/basic-syntax/).
We mentioned markdown _extensions_, here are the ones currently supported:
* [[Frontmatter]]
* Double-bracketed wiki links: `[[link to page]]`, optionally with aliases `[[link to page|alias]]`.

7
website/Mobile.md Normal file
View File

@ -0,0 +1,7 @@
There is a “native” mobile app under development (the code [lives here](https://github.com/silverbulletmd/silverbullet/tree/main/mobile)). Initially, it will be offered for iOS (and iPadOS), but soon thereafter an Android version is planned.
The mobile app is built using [CapacitorJS](https://capacitorjs.com/) and therefore cross-platform. It essentially wraps the existing web app, and swaps out the server calls to local on-device APIs, such as using the local filesystem to store content (pages and attachments), uses a local SQLite database, and it runs all [[🔌 Plugs]] code on device. It is capable of fully running offline.
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.
In the very likely scenario you’d like to synchronize with your space e.g. on [[Desktop]] or a [[Server]], you’ll need to use [[Sync]].

2
website/PLUGS.md
View File

@ -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
```

80
website/Server.md Normal file
View File

@ -0,0 +1,80 @@
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.
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
```

60
website/Silver Bullet.md → website/SilverBullet.md
View File

@ -1,13 +1,13 @@
Silver Bullet is an extensible, [open source](https://github.com/silverbulletmd/silverbullet), **personal knowledge management** system. Indeed, that’s fancy talk for “a note-taking app with links.” However, Silver Bullet goes a bit beyond just that.
_Quick links:_ [Roadmap](https://github.com/orgs/silverbulletmd/projects/2/views/1), [[CHANGELOG]], [Issues](https://github.com/silverbulletmd/silverbullet/issues), [Discussions](https://github.com/silverbulletmd/silverbullet/discussions), [Zef on Mastodon](https://hachyderm.io/@zef), [Mattermost chat](https://silverbullet.cloud.mattermost.com/), [Docker Hub](https://hub.docker.com/r/zefhemel/silverbullet).
SilverBullet is an extensible, [open source](https://github.com/silverbulletmd/silverbullet), **personal knowledge management** system. Indeed, that’s fancy talk for “a note-taking app with links.” However, SilverBullet goes a bit beyond _just_ that.
You’ve been told there is _no such thing_ as a [silver bullet](https://en.wikipedia.org/wiki/Silver_bullet). You were told wrong.
Let’s have a look at some of Silver Bullet’s features.
Before we get to the nitty gritty, some _quick links_ for the impatient reader: [[Download]], [Roadmap](https://github.com/orgs/silverbulletmd/projects/2/views/1), [[CHANGELOG]], [Issues](https://github.com/silverbulletmd/silverbullet/issues), [Discussions](https://github.com/silverbulletmd/silverbullet/discussions), [Mastodon](https://hachyderm.io/@silverbullet), [Mattermost chat](https://silverbullet.cloud.mattermost.com/), [Docker Hub](https://hub.docker.com/r/zefhemel/silverbullet).
To start, let’s have a look at some of SilverBullet’s features.
## Features
* Runs in any modern browser (including on mobile) and is installable as a [PWA](https://web.dev/progressive-web-apps/).
* Runs in any modern browser (including on mobile) when run as a [[Server]], but can also be run ask a [[Desktop]] (and soon) [[Mobile]] app.
* 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**:
@ -77,52 +77,26 @@ There are a few features you don’t get to fully experience in this environment
* **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 -->
## Where to go from here
Click on the links below to explore various aspects of SilverBullet more in-depth:
* [[CHANGELOG]]: What’s new?
* [[🔌 Plugs]]: extensions available in Silver Bullet
* [[🔌 Plugs]]: extensions available for, and as part of SilverBullet
* [[💡 Inspiration]]: some of the projects that inspired SilverBullet
* [[🔨 Development]]: how to start hacking on SilverBullet itself
## Installing Silver Bullet
This consists of two steps (unless Deno is already installed):
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 Silver Bullet itself
### Install Silver Bullet
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 Silver Bullet, 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, Silver Bullet will bind to port `3000`, to use a different port use the `--port` flag.
For security reasons, by default Silver Bullet 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.
Once downloaded and booted, Silver Bullet will print out a URL to open SB in your browser.
## Upgrading Silver Bullet
Silver Bullet is regularly updated. To get the latest and greatest, simply run:
```shell
silverbullet upgrade
```
And restart Silver Bullet. You should be good to go.
## 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).
Want to chat with us? [We have a Mattermost instance](https://silverbullet.cloud.mattermost.com/), join us!

39
website/Sync.md Normal file
View File

@ -0,0 +1,39 @@
SilverBullet now has a sync engine. Let’s still consider it _experimental_, but it’s ready for use.
The synchronization algorithm implemented is [pretty much this one described here](https://unterwaditzer.net/2016/sync-algorithm.html).
## Architecture
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 (as you should)
3. {[Sync: Sync]} performs a sync. It stores a local sync snapshot (basically a list of timestamps for all files in your space) in its local SQLite database every time.
4. Check {[Show Logs]} for sync logs.
Right now, sync needs to be triggered manually, so run {[Sync: Sync]} whenever you feel a sync is warranted.
## The sync process
1. The sync engine compares two file listings: the local one and 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 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!