Website updates, using a query to generate a plug list.
Zef Hemel
parent
1816925e37
commit
83c54b2754
|
|
@ -8,6 +8,7 @@ What does Silver Bullet look like? Well, have a look around. **You’re looking
|
|||
|
||||
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 `npx` command (see below) to download and run it locally in its fully functioning mode.
|
||||
|
||||
## Playground
|
||||
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:
|
||||
|
|
@ -24,16 +25,28 @@ Here are some things to try:
|
|||
* 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).
|
||||
|
||||
Cool, no?
|
||||
|
||||
There are a few features you don’t get to try in this environment, because they rely on some back-end processing, such as:
|
||||
There are a few features you don’t get to try in this environment, because they rely on back-end processing, such as:
|
||||
|
||||
* 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.
|
||||
* Intelligent page renaming, automatically updating any pages that link to it.
|
||||
* Full text search.
|
||||
* Dynamically **extending** and updating SB’s functionality by installing additional [[🔌 Plugs]] and writing your own.
|
||||
* **Extending** and updating SB’s functionality by installing additional [[🔌 Plugs]] and writing your own.
|
||||
|
||||
To experience these, you’ll have to install SB yourself (see below).
|
||||
## Extensions
|
||||
What type of extensions, you ask? Let us demonstrate this in a very meta way: by querying a list of plugs an 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” render “template/plug” -->
|
||||
* [[🔌 Git]] by **Zef Hemel** ([repo](https://github.com/silverbulletmd/silverbullet-github))
|
||||
* [[🔌 Ghost]] by **Zef Hemel** ([repo](https://github.com/silverbulletmd/silverbullet-ghost))
|
||||
* [[🔌 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))
|
||||
* [[🔌 Backlinks]] by **Guillermo Vayá** ([repo](https://github.com/Willyfrog/silverbullet-backlinks))
|
||||
<!-- /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, and have a look at one of the linked pages to see how the meta data used to query and render is supplied to SB. 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:
|
||||
|
|
|
|||
|
|
@ -0,0 +1 @@
|
|||
* [[{{name}}]] by **{{author}}** ([repo]({{repo}}))
|
||||
|
|
@ -0,0 +1,10 @@
|
|||
```meta
|
||||
type: plug
|
||||
uri: ghr:Willyfrog/silverbullet-backlinks
|
||||
repo: https://github.com/Willyfrog/silverbullet-backlinks
|
||||
author: Guillermo Vayá
|
||||
```
|
||||
|
||||
Provides access to pages that link to the one currently being edited.
|
||||
|
||||
Use the `Show Backlinks for current page` command to toggle.
|
||||
|
|
@ -0,0 +1,28 @@
|
|||
```meta
|
||||
type: plug
|
||||
uri: github:silverbulletmd/silverbullet-ghost/ghost.plug.json
|
||||
repo: https://github.com/silverbulletmd/silverbullet-ghost
|
||||
author: Zef Hemel
|
||||
```
|
||||
|
||||
Very basic plug to publish pages and posts onto the [Ghost](https://ghost.org) platform
|
||||
|
||||
## Configuration
|
||||
|
||||
In your `SETTINGS` specify the following settings:
|
||||
|
||||
```yaml
|
||||
ghostUrl: https://your-ghost-blog.ghost.io
|
||||
ghostPostPrefix: posts
|
||||
ghostPagePrefix: pages
|
||||
```
|
||||
|
||||
And in your `SECRETS` file:
|
||||
|
||||
```yaml
|
||||
ghostAdminKey: your:adminkey
|
||||
```
|
||||
|
||||
This will assume the naming pattern of `posts/my-post-slug` where the first top-level heading (`# Hello`) will be used as the post title.
|
||||
|
||||
Commands to use `Ghost: Publish`
|
||||
|
|
@ -0,0 +1,18 @@
|
|||
```meta
|
||||
type: plug
|
||||
uri: github:silverbulletmd/silverbullet-github/github.plug.json
|
||||
repo: https://github.com/silverbulletmd/silverbullet-github
|
||||
author: Zef Hemel
|
||||
```
|
||||
|
||||
The git plug provides very basic “git sync” functionality, it assumes you have git configured for push and pull in your space. It offers two commands:
|
||||
|
||||
* `Git : Sync`:
|
||||
* Adds all *.md files in your folder to git
|
||||
* It commits them with a "Snapshot" commit message
|
||||
* It `git pull`s changes from the remote server
|
||||
* It `git push`es changes to the remote server
|
||||
|
||||
* `Git: Snapshot`:
|
||||
* Asks you for a commit message
|
||||
* Commits
|
||||
|
|
@ -0,0 +1,32 @@
|
|||
```meta
|
||||
type: plug
|
||||
uri: github:silverbulletmd/silverbullet-github/github.plug.json
|
||||
repo: https://github.com/silverbulletmd/silverbullet-github
|
||||
author: Zef Hemel
|
||||
```
|
||||
|
||||
Provides Github events, notifications and pull requests as query sources using SB's query mechanism
|
||||
|
||||
* `gh-event` required filters in the `where` clause:
|
||||
* `username`: the user whose events to query
|
||||
* `gh-pull`
|
||||
* `repo`: the repo to query PRs for
|
||||
* `gh-notification` requires a `githubToken` to be configured in `SECRETS`.
|
||||
|
||||
## Example
|
||||
|
||||
Example uses:
|
||||
|
||||
## Recent pushes
|
||||
<!-- #query gh-event where username = "zefhemel" and type = "PushEvent" select type, actor_login, created_at, payload_ref limit 3 -->
|
||||
|
||||
<!-- /query -->
|
||||
|
||||
## Recent PRs
|
||||
<!-- #query gh-pull where repo = "silverbulletmd/silverbullet" and user_login = "zefhemel" limit 3 render "template/gh-pull" -->
|
||||
|
||||
<!-- /query -->
|
||||
|
||||
Where the `template/gh-pull` looks as follows:
|
||||
|
||||
* ({{state}}) [{{title}}]({{html_url}})
|
||||
|
|
@ -0,0 +1,70 @@
|
|||
```meta
|
||||
type: plug
|
||||
uri: github:silverbulletmd/silverbullet-mattermost/mattermost.plug.json
|
||||
repo: https://github.com/silverbulletmd/silverbullet-mattermost
|
||||
author: Zef Hemel
|
||||
```
|
||||
|
||||
Provides a `mm-saved` query provider (and maybe more in the future). Please follow the installation, configuration sections, and have a look at the example.
|
||||
|
||||
## Configuration
|
||||
You need two bits of configuration to make this plug work. In `SETTINGS` provide the `mattermostUrl` and `mattermostDefaultTeam` settings, they default to the following:
|
||||
|
||||
```yaml
|
||||
mattermostUrl: https://community.mattermost.com
|
||||
mattermostDefaultTeam: core
|
||||
```
|
||||
|
||||
In `SECRETS` provide a Mattermost personal access token (or hijack one from your current session):
|
||||
|
||||
```yaml
|
||||
mattermostToken: your-token
|
||||
```
|
||||
|
||||
To make this look good, it's recommended you render your query results a template. Here is one to start with, you can keep it in e.g. `templates/mm-saved`:
|
||||
|
||||
[{{username}}]({{desktopUrl}}) in **{{channelName}}** at {{updatedAt}} {[Unsave]}:
|
||||
|
||||
{{prefixLines (substring message 0 300 " ... (More)") "> "}}
|
||||
|
||||
---
|
||||
|
||||
Note that the `{[Unsaved]}` "button" when clicked, will unsave the post automatically 😎
|
||||
|
||||
## Query sources
|
||||
|
||||
* `mm-saved` fetches (by default 15) saved posts in Mattermost
|
||||
|
||||
## Example
|
||||
|
||||
Example uses (using the `template/mm-saved` template above):
|
||||
|
||||
<!-- #query mm-saved order by updatedAt desc limit 5 render "template/mm-saved" -->
|
||||
[lindy.isherwood](mattermost://community.mattermost.com/private-core/pl/u8ospw14ptg47fystidzudigjw) in **R&D Meeting** at 2022-07-22 {[Unsave]}:
|
||||
|
||||
> #### [Meeting Recording](https://mattermost.zoom.us/rec/share/e0CmkZr_1xaW0Zd-7N-saD5fir9pmjJy6-xw4JZ7el7IMIUUUr99FiC2WePmBZDw.HRzSgvBjxhsPGQWo)
|
||||
>
|
||||
> Access Passcode: `wq$!BA6N`
|
||||
|
||||
---
|
||||
[harrison](mattermost://community.mattermost.com/core/pl/akuzqwdm4if7fdmajjb94hpm5c) in **** at 2022-07-20 {[Unsave]}:
|
||||
|
||||
> Hey Zef. Can we chat about the Affirm issue a bit when I get back? From what I've gathered, Devin's told customer support that the issue in Chromium isn't something we can reasonably fix, and while I don't feel like that's anything I should be worried about since it's out of my area, I keep getting ... (More)
|
||||
|
||||
---
|
||||
[zef.hemel](mattermost://community.mattermost.com/core/pl/k41cfgdbhfg5unm8yx1cjkh8ty) in **** at 2022-07-20 {[Unsave]}:
|
||||
|
||||
> I'll have to get back to this tomorrow. Filename says "arm64" though
|
||||
|
||||
---
|
||||
[zef.hemel](mattermost://community.mattermost.com/core/pl/9e1ha9yzzpdm9ffhu4od65yykc) in **** at 2022-07-19 {[Unsave]}:
|
||||
|
||||
> Agreed. Thinking what are better indicators than what we already ask. I’ll reach out.
|
||||
|
||||
---
|
||||
[zef.hemel](mattermost://community.mattermost.com/private-core/pl/hh79ikgfzb8zmb4ezjuow7a1mw) in **Team: Web Platform** at 2022-07-15 {[Unsave]}:
|
||||
|
||||
> @webplatform in yesterday’s 1:1 with @harrison we came up with the concept of “theme weeks” to solve our problem of scheduling _important but not urgent_ work. Examples are: looking at performance improvements, cleaning/fixing lingering bugs from our backlog, working on accessibility tickets, perfor ... (More)
|
||||
|
||||
---
|
||||
<!-- /query -->
|
||||
|
|
@ -0,0 +1,23 @@
|
|||
```meta
|
||||
type: plug
|
||||
uri: github:silverbulletmd/silverbullet-mount/mount.plug.json
|
||||
repo: https://github.com/silverbulletmd/silverbullet-mount
|
||||
author: Zef Hemel
|
||||
```
|
||||
|
||||
Enables mounting of external folders or SB instances into your space mounted under a `🚪` prefix.
|
||||
|
||||
## Configuration
|
||||
Create a `MOUNTS` page:
|
||||
|
||||
```yaml
|
||||
# Mounting another local folder with a docs/ prefix
|
||||
- prefix: docs/
|
||||
path: file:/Users/me/docs
|
||||
# Mounting an external SB instance to remote/
|
||||
- prefix: remote/
|
||||
path: http://some-ip:3000
|
||||
password: mypassword
|
||||
```
|
||||
|
||||
This will make these available under `🚪 docs/` and `🚪 remote/` respectively.
|
||||
|
|
@ -1,8 +0,0 @@
|
|||
Here is a list of plugs you can install. If you know of any more, please let us know by issuing a PR [to the repo](https://github.com/silverbulletmd/silverbullet/tree/main/website)!
|
||||
|
||||
* [Git](https://github.com/silverbulletmd/silverbullet-git): adds very rudimentary git sync plug, to synchronize your pages with a git repository.
|
||||
* [Github](https://github.com/silverbulletmd/silverbullet-github): adds `gh-events` and `gh-pulls` as a query provider.
|
||||
* [Ghost](https://github.com/silverbulletmd/silverbullet-ghost): adds the ability to publish pages to [Ghost](https://ghost.org/).
|
||||
* [Mount](https://github.com/silverbulletmd/silverbullet-mount): adds the ability to “mount” external directories and SB instances into your space.
|
||||
* [Backlinks](https://github.com/Willyfrog/silverbullet-backlinks): persistently shows your page’s backlinks in a side panel.
|
||||
* [Mattermost](https://github.com/silverbulletmd/silverbullet-mattermost): a basic Mattermost plug exposing saved posts as a query source.
|
||||
|
|
@ -2,25 +2,15 @@ Silver Bullet at its core is bare bones in terms of functionality, most of its p
|
|||
|
||||
Plugs are an extension mechanism (implemented using a library called `plugos` 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 functionality. Plugs can be loaded, unloaded and updated without having to restart SB itself.
|
||||
|
||||
[[🔌 Plug Directory]]
|
||||
|
||||
Examples of functionality implemented as plugs:
|
||||
|
||||
* _Core functionality_ such as:
|
||||
* Navigation between pages by clicking or hitting `Cmd/Ctrl-Enter`
|
||||
* Page auto complete when using the `[[page link]]` syntax
|
||||
* Indexing of cross-page links and automatically updating all references to them when a page is renamed
|
||||
* Text editing commands such as bold (`Cmd/Ctrl-b`) and italics (`Cmd/Ctrl-i`) or quote or itemize entire sections.
|
||||
* Full text indexing and search
|
||||
* Slash commands such as `/today`, `/tomorrow` and `/meta` (to insert page meta data)
|
||||
* Emoji auto complete using the `:emoji:` syntax
|
||||
* An embedded query language that can be used to query various sets of indexed entities, such as:
|
||||
* Tasks using the Markdown task syntax
|
||||
* Page backlinks
|
||||
* Page in your space and its meta data
|
||||
* Data objects embedded in your pages
|
||||
* Git integration
|
||||
* Github integration
|
||||
## Directory
|
||||
<!-- #query page where type = “plug” render “template/plug” -->
|
||||
* [[🔌 Git]] by **Zef Hemel** ([repo](https://github.com/silverbulletmd/silverbullet-github))
|
||||
* [[🔌 Ghost]] by **Zef Hemel** ([repo](https://github.com/silverbulletmd/silverbullet-ghost))
|
||||
* [[🔌 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))
|
||||
* [[🔌 Backlinks]] by **Guillermo Vayá** ([repo](https://github.com/Willyfrog/silverbullet-backlinks))
|
||||
<!-- /query -->
|
||||
|
||||
## How to develop your own plug
|
||||
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).
|
||||
|
|
|
|||
Loading…
Reference in New Issue