Website improvements

website/Sandbox.md

@@ -1,51 +1,32 @@
-What does Silver Bullet look like? Well, have a look around. **You’re looking at
+What does Silver Bullet look like? Well, have a look around. **You’re looking at it at this very moment!** 🤯
-it at this very moment!** 🤯
 
-Note that what you’re looking at is not a fully functional version, because the
+Note that what you’re looking at is not a fully functional version, because the _back-end is read-only_. That said, it should give you some feel for what it’s like to use SB before making the commitment of running a single `deno` command (see here: [[Silver Bullet]]) to download and run it locally in its fully functioning mode.
-_back-end is read-only_. That said, it should give you some feel for what it’s
-like to use SB before making the commitment of running a single `npx` command
-(see below) to download and run it locally in its fully functioning mode.
 
 ## Start playing
-
+So, feel free to make some edits in this space. Don’t worry, you won’t break anything, nothing is saved (just reload the page to see).
-So, feel free to make some edits in this space. Don’t worry, you won’t break
-anything, nothing is saved (just reload the page to see).
 
 Here are some things to try:
 
-- Click on the page title (`index` for this particular one) at the top, or hit
+* Click on the page title (`index` for this particular one) at the top, 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).
-  `Cmd-k` (Mac) or `Ctrl-k` (Linux and Windows) to open the **page switcher**.
+* Click on the run button (top right) or hit `Cmd-/` (Mac) or `Ctrl-/` (Linux and Windows) to open the **command palette** (note not all commands will work in this quasi read-only mode).
-  Type the name of a nonexistent page to create it (although it won’t save in
+* Select some text and hit `Alt-m` to ==highlight== it, or `Cmd-b` (Mac) or `Ctrl-b` to make it **bold**.
-  this environment).
+* Click a link somewhere in this page to navigate there.
-- Click on the run button (top right) or hit `Cmd-/` (Mac) or `Ctrl-/` (Linux
+* Start typing `[[` somewhere to insert a page link (with completion).
-  and Windows) to open the **command palette** (note not all commands will work
+* [ ] Tap this box 👈 to mark this task as done.
-  in this quasi read-only mode).
+* Start typing `:party` to trigger the emoji picker 🎉
-- Select some text and hit `Alt-m` to ==highlight== it, or `Cmd-b` (Mac) or
+* Type `/` somewhere in the text to invoke a **slash command**.
-  `Ctrl-b` to make it **bold**.
+* Hit `Cmd-p` (Mac) or `Ctrl-p` (Windows, Linux) to show a live preview for the current page on the side, if your brain doesn’t speak native Markdown yet.
-- Click a link somewhere in this page to navigate there.
+* Open this site on your phone or tablet and… it just works!
-- Start typing `[[` somewhere to insert a page link (with completion).
+* Are you using a browser with **PWA support** (e.g. any Chromium-based
-- [ ] Tap this box 👈 to mark this task as done.
+  browser)? Click on that little icon to the right of your location bar that says “Install Silver Bullet” 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).
-- 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 live preview for the
-  current page on the side, if your brain doesn’t speak native Markdown yet.
-- 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 Silver Bullet” 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).
 
-There are a few features you don’t get to fully experience in this environment,
+There are a few features you don’t get to fully experience in this environment, because they rely on a working back-end, such as:
-because they rely on a working back-end, such as:
 
-- Using SB’s powerful page indexing and **query mechanism** where part of pages
+* Using SB’s powerful page indexing and **query mechanism** where part of pages are automatically rendered and kept up to date by querying various data sources (such as pages and their metadata, back links, tasks embedded in pages, and list items) with an SQL like syntax, rendered with handlebars templates.
-  are automatically rendered and kept up to date by querying various data
+* Intelligent **page renaming**, automatically updating any pages that link to it.
-  sources (such as pages and their metadata, back links, tasks embedded in
+* **Full text search**.
-  pages, and list items) with an SQL like syntax, rendered with handlebars
+* **Extending** and updating SB’s functionality by installing additional [[🔌 Plugs]] (SB parlance for plug-ins) and writing your own.
-  templates.
+
-- Intelligent **page renaming**, automatically updating any pages that link to
+That’s all, now go install this baby already!
-  it.
+
-- **Full text search**.
+Instructions here 👉 [[Silver Bullet]]
-- **Extending** and updating SB’s functionality by installing additional [[🔌
-  Plugs]] (SB parlance for plug-ins) and writing your own.

website/Silver Bullet.md

@@ -1,45 +1,24 @@
 ## Markdown as a platform
-Silver Bullet (SB) is highly-extensible,
+Silver Bullet (SB) is highly-extensible, [open source](https://github.com/silverbulletmd/silverbullet) **personal
-[open source](https://github.com/silverbulletmd/silverbullet) **personal
 knowledge management** software. Indeed, that’s fancy language for “a note taking app with links.”
 
 Here is a screenshot:
 
 ![Silver Bullet PWA screenshot](silverbullet-pwa.png)
-
 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).
 
-## Extensions
+And then, [give it a try in our Sandbox](https://demo.silverbullet.md/Sandbox).
-
-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):
-
-<!-- #query page where type = "plug" order by name render [[template/plug]] -->
-* [[🔌 Backlinks]] by **Guillermo Vayá** ([repo](https://github.com/Willyfrog/silverbullet-backlinks))
-* [[🔌 Core]] by **Silver Bullet Authors** ([repo](https://github.com/silverbulletmd/silverbullet))
-* [[🔌 Directive]] 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))
-* [[🔌 Serendipity]] by **Pantelis Vratsalis** ([repo](https://github.com/m1lt0n/silverbullet-serendipity))
-<!-- /query -->
-
-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.
 
 ## Explore more
 Click on the links below to explore various aspects of Silver Bullet more
 in-depth:
 
-- [[CHANGELOG]]
+* [[CHANGELOG]] — what’s new?
-- [[🤯 Features]]
+* [[🤯 Features]]
-- [[💡 Inspiration]]
+* [[💡 Inspiration]]
-- [[🔌 Plugs]]
+* [[🔌 Plugs]]
-- [[🔨 Development]]
+* [[🔨 Development]]
 
 More of a video person? Here are two to get you started:
 
@@ -56,18 +35,19 @@ Some core principles that underly Silver Bullet’s philosophy:
 - **Extend it your way**. SB is highly extensible with [[🔌 Plugs]], and you can customize it to your liking and your workflows.
 
 ## Installing Silver Bullet
+This consists of two steps (unless Deno is already installed:
+
+1. Installing Deno
+2. Installing Silver Bullet itself
 
 ### Installing Deno
-
+Silver Bullet is built using [Deno](https://deno.land). To install Deno on Linux or Mac run:
-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
+This will install Deno into `~/.deno/bin`, add this folder to your `PATH` in your `~/.bashrc` or `~/.zshrc` file.
-your `~/.bashrc` or `~/.zshrc` file.
 
 To install Deno on Windows (using Powershell) run:
 
@@ -76,8 +56,7 @@ irm https://deno.land/install.ps1 | iex
 ```
 
 ### Install Silver Bullet
-
+With Deno installed, run:
-With Deno installed (see instruction above), run:
 
 ```shell
 deno install -f --name silverbullet -A --unstable https://get.silverbullet.md

website/💡 Inspiration.md

@@ -1,10 +1,5 @@
 Inspiration for Silver Bullet comes primarily from
 [Obsidian](https://obsidian.md/) and its vast plug-in ecosystem (the
-work-in-progress plugs around querying and tasks are inspired by Obsidian’s
+work-in-progress plugs around querying and tasks are inspired by Obsidian’s tasks and dataview plugins), but also [Roam Research](https://roamresearch.com/) was an inspiration.
-tasks and dataview plugins), but also [Roam Research](https://roamresearch.com/)
-was an inspiration.
 
-The way plugs are implemented is a further iteration on how this was done in a
+The way plugs are implemented is a further iteration on how this was done in a previous project of mine (now defunct) called [Zed](https://github.com/zedapp/zed) as well as [Matterless](https://github.com/zefhemel/matterless).
-previous project of mine (now defunct) called
-[Zed](https://github.com/zedapp/zed) as well as
-[Matterless](https://github.com/zefhemel/matterless).

website/🔌 Plugs.md

@@ -1,105 +1,63 @@
-Silver Bullet at its core is bare bones in terms of functionality, most of its
+Silver Bullet at its core is bare bones in terms of functionality, most of its power it gains from **plugs**.
-power it gains from **plugs**.
 
-Plugs are an extension mechanism (implemented using a library called `plugos`
+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 can extend the Markdown parser and its syntax, define new commands and keybindings, respond to various events triggered either on the server or client side, as well as run recurring and background tasks. Plugs can even define their own extension
-that runs plug code on the server in a sandboxed v8 node.js process, and in the
-browser using web workers). Plugs can hook into SB in various ways: plugs can
-extend the Markdown parser and its syntax, define new commands and keybindings,
-respond to various events triggered either on the server or client side, as well
-as run recurring and background tasks. Plugs can even define their own extension
 mechanisms through custom events. Each plug runs in its own sandboxed
-environment and communicates with SB via _syscalls_ that expose a vast range of
+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.
-functionality. Plugs can be loaded, unloaded and updated without having to
-restart SB itself.
 
 ## Directory
-
 <!-- #query page where type = "plug" order by name render [[template/plug]] -->
-
+* [[🔌 Backlinks]] by **Guillermo Vayá** ([repo](https://github.com/Willyfrog/silverbullet-backlinks))
-- [[🔌 Backlinks]] by **Guillermo Vayá**
+* [[🔌 Core]] by **Silver Bullet Authors** ([repo](https://github.com/silverbulletmd/silverbullet))
-  ([repo](https://github.com/Willyfrog/silverbullet-backlinks))
+* [[🔌 Directive]] by **Silver Bullet Authors** ([repo](https://github.com/silverbulletmd/silverbullet))
-- [[🔌 Ghost]] by **Zef Hemel**
+* [[🔌 Ghost]] by **Zef Hemel** ([repo](https://github.com/silverbulletmd/silverbullet-ghost))
-  ([repo](https://github.com/silverbulletmd/silverbullet-ghost))
+* [[🔌 Git]] by **Zef Hemel** ([repo](https://github.com/silverbulletmd/silverbullet-github))
-- [[🔌 Git]] by **Zef Hemel**
+* [[🔌 Github]] by **Zef Hemel** ([repo](https://github.com/silverbulletmd/silverbullet-github))
-  ([repo](https://github.com/silverbulletmd/silverbullet-github))
+* [[🔌 Mattermost]] by **Zef Hemel** ([repo](https://github.com/silverbulletmd/silverbullet-mattermost))
-- [[🔌 Github]] by **Zef Hemel**
+* [[🔌 Serendipity]] by **Pantelis Vratsalis** ([repo](https://github.com/m1lt0n/silverbullet-serendipity))
-  ([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))
-- [[🔌 Directive]] by **Silver Bullet Authors**
-  ([repo](https://github.com/silverbulletmd/silverbullet))
-
 <!-- /query -->
 
 ## How to develop your own plug
-
+The easiest way to get started is to click the “Use this template” on the [silverbullet-plug-template](https://github.com/silverbulletmd/silverbullet-plug-template) repo.
-At this stage, to get started, it’s probably easiest to fork one of the existing
-plugs found in the [SilverBullet github org](https://github.com/silverbulletmd),
-for instance the
-[github one](https://github.com/silverbulletmd/silverbullet-github).
 
 Generally, every plug consists of a YAML manifest file named
-`yourplugname.plug.yml`. It’s convenient to have a `package.json` file in your
+`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`).
-repo to add any dependencies. One dev dependency you will definitely need is
-[@plugos/plugos](https://www.npmjs.com/package/@plugos/plugos) which will supply
-you with the `plugos-bundle` command, which is used to “compile” your plug YAML
-file into its bundled `.plug.json` form, which Silver Bullet will be able to
-load and execute.
 
-Generally, the way to invoke `plugos-bundle` is as follows:
+Generally, the way to do this is to run `silverbullet plug:compile` as follows:
 
-    plugos-bundle yourplugname.plug.yaml
+    silverbullet plug:compile yourplugname.plug.yaml
 
-This will write out a `yourplugname.plug.json` file into the same folder. For
+However, if you use the plug template, this command is wrapped in your `deno.jsonc` file, so you can just run either:
-development it’s convenient to add a `-w` flag to automatically recompile when
-changes to the YAML or source files are detected.
 
-In order to keep bundles somewhat small, a few dependencies come prebundled with
+    deno task build
-SB. A the time of this writing:
 
-- `yaml` (a YAML reader and stringifier library)
+to build it once, or
-- `@lezer/lr` (a parser library)
-- `handlebars`
 
-If you use any of these, you can add e.g. `--exclude handlebars` to _not_ have
+    deno task watch
-them be included in the bundle (they will be loaded from SB itself).
 
-Once you have a compiled `.plug.json` file you can load it into SB in a few ways
+to build it and rebuild when files are changed.
-by listing it in your space’s `PLUGS` page.
 
-For development it’s easiest to use the `file:` prefix for this, by adding this
+This will write out a `yourplugname.plug.json` file into the same folder.
-in the `yaml` block section there to your existing list of plugs:
+
+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
 
-Reload your list of plugs via the `Plugs: Update` command (`Cmd-Shift-p` on Mac,
+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.
-`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.
 
 Once you’re happy with your plug, you can distribute it in various ways:
 
-- You can put it on github by simply committing the resulting `.plug.json` file
+- You can put it on github by simply committing the resulting `.plug.json` file there and instructing users to point to by adding
-  there and instructing users to point to by adding
+  `- github:yourgithubuser/yourrepo/yourplugname.plug.json` to their `PLUGS` file
-  `- github:yourgithubuser/yourrepo/yourplugname.plug.json` to their `PLUGS`
+- Add a release in your github repo and instruct users to add the release as `- ghr:yourgithubuser/yourrepo` or if they need a spcecific release `- ghr:yourgithubuser/yourrepo/release-name`
-  file
+- You can put it on any other web server, and tell people to load it via https, e.g. `- https://mydomain.com/mypugname.plug.json`.
-- Add a release in your github repo and instruct users to add the release as
-  `- ghr:yourgithubuser/yourrepo` or if they need a spcecific release
-  `- ghr:yourgithubuser/yourrepo/release-name`
-- You can put it on any other web server, and tell people to load it via https,
-  e.g. `- https://mydomain.com/mypugname.plug.json`.
 
 ### Recommended development workflow
-
+I develop plugs as follows: in one terminal I have `deno task watch` running at all times, constantly recompiling my code as I change it.
-I develop plugs as follows: in one terminal I have `plugos-bundle -w` running at
-all times, constantly recompiling my code as I change it.
 
 I also have SB open with a `file:` based link in my `PLUGS` file.
 
-Whenever I want to test a change, I switch to SB, hit `Cmd-Shift-p` and test if
+Whenever I want to test a change, I switch to SB, hit `Cmd-Shift-p` and test if stuff works.
-stuff works.
 
-Often I also have the `Debug: Show Logs` command running to monitor both server
+Often I also have the `Debug: Show Logs` command running to monitor both server and client logs for any errors and debug information.
-and client logs for any errors and debug information.

website/🔨 Development.md

@@ -1,39 +1,25 @@
 ## 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.
-[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.
 
 ## Development
-
+Requirements: [Deno](https://deno.land/) 1.26 or newer.
-Requirements: [Deno](https://deno.land/) 1.26.
 
 To run, after clone:
 
-```shell
-deno task install
-```
-
-To prepare the initial web and plug build run:
-
 ```shell
 deno task build
 ```
 
-You can then run the server in “watch mode” (automatically restarting when you
+You can then run the server in “watch mode” (automatically restarting when you change source files) with:
-change source files) with:
 
 ```shell
-deno task watch-server -- <PATH-TO-YOUR-SPACE>
+deno task watch-server <PATH-TO-YOUR-SPACE>
 ```
 
-After this initial build, it's convenient to run three commands in parallel (in
+After this initial build, it's convenient to run three commands in parallel (in separate terminals):
-separate terminals):
 
 ```shell
 deno task watch-web
-deno task watch-server -- <PATH-TO-YOUR-SPACE>
+deno task watch-server <PATH-TO-YOUR-SPACE>
 deno task watch-plugs
 ```

website/🤯 Features.md

@@ -1,15 +1,7 @@
-* **Powerful Markdown editor** at its core (powered by
+* **Powerful Markdown editor** at its core (powered by [CodeMirror](https://codemirror.net))
-  [CodeMirror](https://codemirror.net))
+* **Distraction-free** UI with [What You See is What You Mean](https://en.wikipedia.org/wiki/WYSIWYM) markdown editing.
-* **Distraction-free** UI with
+* **Future proof**: stores all notes in a regular folder with markdown files, no proprietary file formats. While SB uses an SQLite database for indexes, this database can be wiped and rebuilt based on your pages at any time. Your markdown files are the single source of truth.
-  [What You See is What You Mean](https://en.wikipedia.org/wiki/WYSIWYM)
+* **Run anywhere**: run it on your local machine, or install it on a server. You access it via your web browser (desktop or mobile), or install it as a PWA (giving it its own window frame and dock/launcher/dock icon).
-  Markdown editing.
-* **Future proof**: stores all notes in a regular folder with markdown files, no
-  proprietary file formats. While SB uses an SQLite database for indexes, this
-  database can be wiped and rebuilt based on your pages at any time. Your
-  Markdown files are the single source of truth.
-* **Run anywhere**: run it on your local machine, or install it on a server. You
-  access it via your web browser (desktop or mobile), or install it as a PWA
-  (giving it its own window frame and dock/launcher/dock icon).
 * **Keyboard oriented:** you can fully operate SB via the keyboard (on
   laptop/desktop machines as well as iPads with a keyboard).
 * **Extensible** through [[🔌 Plugs]]