2022-07-15 12:59:47 +00:00
|
|
|
|
## Markdown as a platform
|
2022-10-12 09:47:13 +00:00
|
|
|
|
|
|
|
|
|
Silver Bullet (SB) is highly-extensible,
|
|
|
|
|
[open source](https://github.com/silverbulletmd/silverbullet) **personal
|
|
|
|
|
knowledge management** software. Indeed, that’s fancy language for “a note
|
|
|
|
|
taking app with links.”
|
2022-07-15 12:59:47 +00:00
|
|
|
|
|
2022-09-05 14:15:01 +00:00
|
|
|
|
Here is a screenshot:
|
2022-07-15 17:10:56 +00:00
|
|
|
|
|
2022-09-06 12:36:06 +00:00
|
|
|
|
![Silver Bullet PWA screenshot](silverbullet-pwa.png)
|
2022-07-15 17:10:56 +00:00
|
|
|
|
|
2022-10-12 09:47:13 +00:00
|
|
|
|
At its core, SB is a Markdown editor that stores _pages_ (notes) as plain
|
|
|
|
|
markdown files in a folder referred to as a _space_. Pages can be cross-linked
|
|
|
|
|
using the `[[link to other page]]` syntax. However, once you leverage its
|
|
|
|
|
various extensions (called _plugs_) it can feel more like a _knowledge
|
|
|
|
|
platform_, allowing you to annotate, combine and query your accumulated
|
|
|
|
|
knowledge in creative ways, specific to you. To get a good feel for it,
|
|
|
|
|
[watch this video](https://youtu.be/RYdc3UF9gok).
|
2022-07-24 19:39:37 +00:00
|
|
|
|
|
2022-09-05 14:41:58 +00:00
|
|
|
|
Or [try it in a sandbox demo environment](https://demo.silverbullet.md/Sandbox).
|
|
|
|
|
|
2022-07-24 19:39:37 +00:00
|
|
|
|
## Extensions
|
|
|
|
|
|
2022-10-12 09:47:13 +00:00
|
|
|
|
What type of extensions, you ask? Let us demonstrate this in a very meta way: by
|
|
|
|
|
querying a list of plugs and injecting it into this page!
|
|
|
|
|
|
|
|
|
|
Here’s a list of (non-built-in) plugs documented in this space (note the
|
|
|
|
|
`#query` ... `/query` notation used):
|
2022-07-24 19:39:37 +00:00
|
|
|
|
|
2022-08-09 13:37:47 +00:00
|
|
|
|
<!-- #query page where type = "plug" order by name render [[template/plug]] -->
|
2022-10-12 09:47:13 +00:00
|
|
|
|
|
|
|
|
|
- [[🔌 Backlinks]] by **Guillermo Vayá**
|
|
|
|
|
([repo](https://github.com/Willyfrog/silverbullet-backlinks))
|
|
|
|
|
- [[🔌 Core]] by **Silver Bullet Authors**
|
|
|
|
|
([repo](https://github.com/silverbulletmd/silverbullet))
|
|
|
|
|
- [[🔌 Ghost]] by **Zef Hemel**
|
|
|
|
|
([repo](https://github.com/silverbulletmd/silverbullet-ghost))
|
|
|
|
|
- [[🔌 Git]] by **Zef Hemel**
|
|
|
|
|
([repo](https://github.com/silverbulletmd/silverbullet-github))
|
|
|
|
|
- [[🔌 Github]] by **Zef Hemel**
|
|
|
|
|
([repo](https://github.com/silverbulletmd/silverbullet-github))
|
|
|
|
|
- [[🔌 Mattermost]] by **Zef Hemel**
|
|
|
|
|
([repo](https://github.com/silverbulletmd/silverbullet-mattermost))
|
|
|
|
|
- [[🔌 Mount]] by **Zef Hemel**
|
|
|
|
|
([repo](https://github.com/silverbulletmd/silverbullet-mount))
|
|
|
|
|
- [[🔌 Query]] by **Silver Bullet Authors**
|
|
|
|
|
([repo](https://github.com/silverbulletmd/silverbullet))
|
|
|
|
|
|
2022-10-10 13:09:56 +00:00
|
|
|
|
<!-- /query -->
|
2022-07-16 19:14:10 +00:00
|
|
|
|
|
2022-10-12 09:47:13 +00:00
|
|
|
|
In a regular SB installation, the body of this query 👆 (in between the
|
|
|
|
|
placeholders) would automatically be kept up to date as new pages are added to
|
|
|
|
|
the space that match the query. 🤯 Have a look at the [[template/plug]]
|
|
|
|
|
_template_ (referenced in the `render` clause) to see how the results are
|
|
|
|
|
rendered using handlebars syntax and have a look at one of the linked pages to
|
|
|
|
|
see how the _metadata_ is specified, which is subsequently used to query and
|
|
|
|
|
render in this page. And to learn about the specific plug, of course.
|
2022-07-16 19:14:10 +00:00
|
|
|
|
|
2022-07-15 12:59:47 +00:00
|
|
|
|
## Explore more
|
|
|
|
|
|
2022-10-12 09:47:13 +00:00
|
|
|
|
Click on the links below to explore various aspects of Silver Bullet more
|
|
|
|
|
in-depth:
|
|
|
|
|
|
|
|
|
|
- [[CHANGELOG]]
|
|
|
|
|
- [[🤯 Features]]
|
|
|
|
|
- [[💡 Inspiration]]
|
|
|
|
|
- [[🔌 Plugs]]
|
|
|
|
|
- [[🔨 Development]]
|
2022-07-15 12:59:47 +00:00
|
|
|
|
|
2022-10-10 12:50:21 +00:00
|
|
|
|
More of a video person? Here are two to get you started:
|
2022-07-15 12:59:47 +00:00
|
|
|
|
|
2022-10-12 09:47:13 +00:00
|
|
|
|
- [A Tour of Silver Bullet’s features](https://youtu.be/RYdc3UF9gok) — spoiler
|
|
|
|
|
alert: it’s cool.
|
|
|
|
|
- [A look the SilverBullet architecture](https://youtu.be/mXCGau05p5o) — spoiler
|
|
|
|
|
alert: it’s plugs all the way down.
|
2022-07-15 12:59:47 +00:00
|
|
|
|
|
2022-07-15 17:57:14 +00:00
|
|
|
|
## Principles
|
2022-10-12 09:47:13 +00:00
|
|
|
|
|
2022-07-15 17:57:14 +00:00
|
|
|
|
Some core principles that underly Silver Bullet’s philosophy:
|
|
|
|
|
|
2022-10-12 09:47:13 +00:00
|
|
|
|
- **Free and open source**. Silver Bullet is MIT licensed.
|
|
|
|
|
- **The truth is in the markdown.** Markdown is simply text files, stored on
|
|
|
|
|
disk. Nothing fancy. No proprietary formats or lock in. While SB uses a
|
|
|
|
|
database for indexing and caching some data, all of that can be rebuilt from
|
|
|
|
|
its markdown source at any time. If SB would ever go away, you can still read
|
|
|
|
|
your pages with any text editor.
|
|
|
|
|
- **Single, distraction-free mode.** SB doesn’t have a separate view and edit
|
|
|
|
|
mode. It doesn’t have a “focus mode.” You’re always in focused edit mode, why
|
|
|
|
|
wouldn’t you?
|
|
|
|
|
- **Keyboard oriented**. You can use SB fully using the keyboard, typin’ the
|
|
|
|
|
keys.
|
|
|
|
|
- **Extend it your way**. SB is highly extensible with [[🔌 Plugs]], and you can
|
|
|
|
|
customize it to your liking and your workflows.
|
2022-07-15 17:57:14 +00:00
|
|
|
|
|
2022-07-16 19:14:10 +00:00
|
|
|
|
## Installing Silver Bullet
|
2022-07-15 12:59:47 +00:00
|
|
|
|
|
2022-10-24 14:29:58 +00:00
|
|
|
|
### Installing Deno
|
2022-10-12 09:47:13 +00:00
|
|
|
|
|
2022-10-24 14:29:58 +00:00
|
|
|
|
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
|
|
|
|
|
```
|
2022-07-15 12:59:47 +00:00
|
|
|
|
|
2022-10-24 14:29:58 +00:00
|
|
|
|
This will install Deno into `~/.deno/bin`, add this folder to your `PATH` in
|
|
|
|
|
your `~/.bashrc` or `~/.zshrc` file.
|
2022-07-15 12:59:47 +00:00
|
|
|
|
|
2022-10-24 14:29:58 +00:00
|
|
|
|
To install Deno on Windows (using Powershell) run:
|
2022-07-15 12:59:47 +00:00
|
|
|
|
|
2022-10-24 14:29:58 +00:00
|
|
|
|
```powershell
|
|
|
|
|
irm https://deno.land/install.ps1 | iex
|
|
|
|
|
```
|
2022-10-10 13:09:56 +00:00
|
|
|
|
|
2022-10-24 14:29:58 +00:00
|
|
|
|
### Install Silver Bullet
|
2022-10-10 13:09:56 +00:00
|
|
|
|
|
2022-10-24 14:29:58 +00:00
|
|
|
|
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:
|
2022-10-10 13:09:56 +00:00
|
|
|
|
|
2022-10-24 14:29:58 +00:00
|
|
|
|
```shell
|
|
|
|
|
silverbullet <pages-path>
|
|
|
|
|
```
|
2022-10-10 13:09:56 +00:00
|
|
|
|
|
|
|
|
|
By default, SB will bind to port `3000`, to use a different port use the
|
2022-10-12 09:47:13 +00:00
|
|
|
|
`--port` flag. By default SB doesn’t offer any sort of authentication, to add
|
|
|
|
|
basic password authentication, pass the `--password` flag.
|
2022-10-10 13:09:56 +00:00
|
|
|
|
|
2022-10-12 09:47:13 +00:00
|
|
|
|
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 ).
|
2022-07-16 19:14:10 +00:00
|
|
|
|
|
2022-10-24 14:29:58 +00:00
|
|
|
|
#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.
|
|
|
|
|
|
|
|
|
|
## Troubleshooting
|
|
|
|
|
|
|
|
|
|
If you upgraded to the new Deno-based Silver Bullet from an old version, you may
|
|
|
|
|
have to use the `silverbullet fix <pages-path>` command to flush out your old
|
|
|
|
|
database and plugs. Plugs will likely need to be updated.
|
2022-07-15 18:15:11 +00:00
|
|
|
|
|
2022-10-12 09:47:13 +00:00
|
|
|
|
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).
|