More website copy editing
Zef Hemel
parent
b43c028e51
commit
33736d2622
|
|
@ -1,22 +1,25 @@
|
|||
Silver Bullet is extensible, [open source](https://github.com/silverbulletmd/silverbullet), **personal
|
||||
knowledge management** software. Indeed, at the most basic level that translates to “a note-taking app with links.” However, Silver Bullet goes a bit beyond just that.
|
||||
knowledge management** software. Indeed, at the most basic level that translates to “a note-taking app with links.” However, Silver Bullet goes a beyond just that.
|
||||
|
||||
Let’s have a look at some of its features.
|
||||
|
||||
## Features
|
||||
* Runs in any modern browser (including mobile browsers) and is installable as a PWA.
|
||||
* Provides a distraction-free, enjoyable markdown writing experience using [[Live Preview|live preview]] that **reduces visual noise**, but still gives direct access to the underlying [[Markdown]] syntax.
|
||||
* Supports wiki-like page linking using the `[[page link]]` syntax, keeping links up-to-date as pages are renamed.
|
||||
* Supports wiki-like page linking using the `[[page link]]` syntax, keeping links up-to-date when pages are renamed.
|
||||
* 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).
|
||||
* 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 [[🔌 Core/Slash Commands|slash commands]] to perform common text editing operations.
|
||||
* Supports annotating pages with metadata (using [[Frontmatter]]).
|
||||
* Provides a platform for [End-user Programming](https://www.inkandswitch.com/end-user-programming/) through its support of [[🔌 Directive|directives]] (such as [[🔌 Directive/Query|#query]]), which make parts of pages _dynamic_.
|
||||
* Robust extension mechanism using [[🔌 Plugs]]
|
||||
* You own your data. All content is stored as plain files in a folder on disk. Nothing fancy.
|
||||
* Self hosted: you own your data. All content is stored as plain files in a folder on disk. Back up, sync, edit, script with any other tools you like.
|
||||
* Silver Bullet is [open source, MIT licensed](https://github.com/silverbulletmd/silverbullet) software.
|
||||
|
||||
|
||||
To get a good feel of what Silver Bullet is capable of, [have a look at at this **introduction video**](https://youtu.be/VemS-cqAD5k).
|
||||
|
||||
## Try it
|
||||
Here’s the kicker:
|
||||
|
||||
|
|
@ -26,11 +29,11 @@ That’s right, **this very website is powered by Silver Bullet itself**. 🤯
|
|||
|
||||
On this site, everything is editable as in a regular copy of Silver Bullet, just none of it persists (the back-end is read-only). So, edit away, reload the page and everything resets.
|
||||
|
||||
So, don’t just sit there, try it!
|
||||
Don’t just sit there, try it!
|
||||
|
||||
* Click on the page picker (folder tree) 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 nonexistent page to create it (although it won’t save in this environment).
|
||||
* Click on the page picker (folder tree) 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 (although it won’t save in this environment).
|
||||
* Click on the run 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).
|
||||
* Select some text and hit `Alt-m` to ==highlight== it, or `Cmd-b` (Mac) or `Ctrl-b` to make it **bold**.
|
||||
* 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.
|
||||
* Start typing `[[` somewhere to insert a page link (with completion).
|
||||
* [ ] Tap this box 👈 to mark this task as done.
|
||||
|
|
@ -70,11 +73,6 @@ 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.
|
||||
|
||||
|
||||
## Demo video
|
||||
|
||||
Some things are just [better explained in a video](https://youtu.be/VemS-cqAD5k).
|
||||
|
||||
## Where to go from here
|
||||
Click on the links below to explore various aspects of Silver Bullet more
|
||||
in-depth:
|
||||
|
|
@ -105,12 +103,12 @@ To run Silver Bullet, create a folder for your pages (it can be empty, or be an
|
|||
silverbullet <pages-path>
|
||||
```
|
||||
|
||||
By default, Silver Bullet will bind to port `3000`, to use a different port use the the `--port` flag.
|
||||
By default, Silver Bullet will bind to port `3000`, to use a different port use the the `--port` flag. By default Silver Bullet is unauthenticated, to password-protect it, specify a password with the `--password` flag.
|
||||
|
||||
Once downloaded and booted, Silver Bullet will print out a URL to open SB in your browser (spoiler alert: by default this will be http://localhost:3000 ).
|
||||
Once downloaded and booted, Silver Bullet will print out a URL to open SB in your browser (by default this will be http://localhost:3000 ).
|
||||
|
||||
## Upgrading Silver Bullet
|
||||
Simply run:
|
||||
Silver Bullet is regularly updated. To get the latest and greatest, simply run:
|
||||
|
||||
```shell
|
||||
silverbullet upgrade
|
||||
|
|
@ -121,4 +119,6 @@ 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!
|
||||
[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!
|
||||
|
|
|
|||
|
|
@ -1,6 +1,8 @@
|
|||
Silver Bullet 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 runs plug code on the server in a sandboxed v8 Deno web worker, and in the browser using web workers). Plugs can hook into SB in various ways:
|
||||
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 can hook into SB in various ways:
|
||||
|
||||
* Extend the Markdown parser and its syntax
|
||||
* Define new commands and keybindings
|
||||
|
|
@ -10,6 +12,8 @@ Plugs are an extension mechanism (implemented using a library called `plugos` th
|
|||
|
||||
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]].
|
||||
|
||||
## Core plugs
|
||||
These plugs are distributed with Silver Bullet and are automatically enabled:
|
||||
<!-- #query page where type = "plug" and uri = null order by name render [[template/plug]] -->
|
||||
|
|
@ -39,30 +43,35 @@ These plugs are written either by third parties or distributed separately from t
|
|||
## How to develop your own plug
|
||||
The easiest way to get started is to click the “Use this template” on the [silverbullet-plug-template](https://github.com/silverbulletmd/silverbullet-plug-template) repo.
|
||||
|
||||
Generally, every plug consists of a YAML manifest file named
|
||||
`yourplugname.plug.yml`. This file defines all functions that form your plug. To be loadable by Silver Bullet (or any plugos-based system for that matter), it needs to be compiled into a JSON bundle (ending with `.plug.json`).
|
||||
Generally, every plug consists of a YAML manifest file named `yourplugname.plug.yml`. This file defines all functions that form your plug. To be loadable by Silver Bullet (or any PlugOS-based system for that matter), it needs to be compiled into a JSON bundle (ending with `.plug.json`).
|
||||
|
||||
Generally, the way to do this is to run `silverbullet plug:compile` as follows:
|
||||
|
||||
silverbullet plug:compile yourplugname.plug.yaml
|
||||
```shell
|
||||
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:
|
||||
|
||||
deno task build
|
||||
```shell
|
||||
deno task build
|
||||
```
|
||||
|
||||
to build it once, or
|
||||
|
||||
deno task watch
|
||||
```shell
|
||||
deno task watch
|
||||
```
|
||||
|
||||
to build it and rebuild when files are changed.
|
||||
|
||||
This will write out a `yourplugname.plug.json` file into the same folder.
|
||||
to build it and rebuild when files are changed. This will write a `yourplugname.plug.json` 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.
|
||||
|
||||
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:
|
||||
|
||||
- file:/home/me/git/yourplugname/yourplugname.plug.json
|
||||
```yaml
|
||||
- file:/home/me/git/yourplugname/yourplugname.plug.json
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,25 +1,42 @@
|
|||
## Stack
|
||||
Silver Bullet 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. [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 using Oak.
|
||||
Silver Bullet 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/).
|
||||
|
||||
## Development
|
||||
Requirements: [Deno](https://deno.land/) 1.26 or newer.
|
||||
Requirements: [Deno](https://deno.land/) 1.28 or newer. If you are running Silver Bullet, you will already have Deno installed.
|
||||
|
||||
To run, after clone:
|
||||
Clone the repository from Github:
|
||||
|
||||
```shell
|
||||
git clone git@github.com:silverbulletmd/silverbullet.git
|
||||
cd silverbullet
|
||||
```
|
||||
|
||||
And build it:
|
||||
|
||||
```shell
|
||||
deno task build
|
||||
```
|
||||
|
||||
You can then run the server in “watch mode” (automatically restarting when you change source files) with:
|
||||
For convenience, replace your `silverbullet` install with the one from this repo via:
|
||||
|
||||
```shell
|
||||
deno task install
|
||||
```
|
||||
|
||||
You can now run the server in “watch mode” (automatically restarting when you change source files) with:
|
||||
|
||||
```shell
|
||||
deno task watch-server <PATH-TO-YOUR-SPACE>
|
||||
```
|
||||
|
||||
After this initial build, it's convenient to run three commands in parallel (in separate terminals):
|
||||
It's convenient to run three commands in parallel (in separate terminals):
|
||||
|
||||
```shell
|
||||
deno task watch-web
|
||||
deno task watch-server <PATH-TO-YOUR-SPACE>
|
||||
deno task watch-plugs
|
||||
```
|
||||
|
||||
All of these watch for file changes and a rebuild should trigger automatically.
|
||||
|
||||
Note that there are dependencies between these builds. Any change to any of the built-in _plugs_ requires a rebuild of the web app. Any rebuild of the web app will only be picked up by the server after it restarts (which should happen automatically).
|
||||
Loading…
Reference in New Issue