Manual refactor
This commit is contained in:
Zef Hemel
parent
92ecbff4cd
commit
4b3a7aa180
@ -103,9 +103,9 @@ Due to significant changes in how data is stored, likely your space will be resy
|
||||
The big change in this release is that SilverBullet now supports two [[Client Modes|client modes]]: _online_ mode and _sync_ mode. Read more about them here: [[Client Modes]].
|
||||
|
||||
Other notable changes:
|
||||
* Massive reshuffling of built-in [[🔌 Plugs]], splitting the old “core” plug into [[🔌 Editor]], [[🔌 Template]] and [[🔌 Index]].
|
||||
* Massive reshuffling of built-in [[🔌 Plugs]], splitting the old “core” plug into [[Plugs/Editor]], [[Plugs/Template]] and [[Plugs/Index]].
|
||||
* Directives in [[Live Preview]] now always take up a single line height.
|
||||
* [[🔌 Tasks]] now support custom states (not just `[x]` and `[ ]`), for example:
|
||||
* [[Plugs/Tasks]] now support custom states (not just `[x]` and `[ ]`), for example:
|
||||
* [IN PROGRESS] An in progress task
|
||||
* [BLOCKED] A task that’s blocked
|
||||
[[🔌 Tasks|Read more]]
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
SilverBullet currently supports two modes for its client (the part of SilverBullet that runs in the browser):
|
||||
SilverBullet currently supports two modes for its client:
|
||||
|
||||
1. _Online mode_ (the default): keeps all content on the server and only loads content to the client on-demand.
|
||||
2. _Synced mode_ (offline capable): syncs all content to the client.
|
||||
@ -7,9 +7,10 @@ You can toggle between these two modes by toggling the 🔄 button in the top ba
|
||||
|
||||
You can switch modes any time and use different modes on different devices.
|
||||
|
||||
**Note:** It is technically possible to _switch off online mode_ (and allow synced mode only) by running the SilverBullet server with the `--sync-only` flag (or setting the `SB_SYNC_ONLY` environment variable to something). With this flag on, the sync button will not appear in the UI.
|
||||
**Note:** It is possible to _switch off online mode_ (and allow synced mode only) by running the SilverBullet server with the `--sync-only` flag, see [[Install/Configuration]].
|
||||
|
||||
## Online mode
|
||||
# Online mode
|
||||
$online
|
||||
In online mode, all content in your space is kept on the server, and a lot of the heavy lifting (such as indexing of pages) happens on the server as well. Content will only be loaded to the client on-demand.
|
||||
|
||||
Advantages:
|
||||
@ -20,7 +21,8 @@ Disadvantages:
|
||||
* **Requires a working network connection** to the server. You can not load pages nor successfully persist changes without it.
|
||||
* **Higher latency** since more interactions require calls to the server, this may be notable e.g., when completing page names.
|
||||
|
||||
## Synced mode
|
||||
# Synced mode
|
||||
$sync
|
||||
In this mode, all content is synchronized to the client, and all processing happens there. The server effectively acts as a “dumb data store.” All SilverBullet functionality is available even when there is no network connection available.
|
||||
|
||||
Advantages:
|
||||
|
||||
5
website/Command Palette.md
Normal file
5
website/Command Palette.md
Normal file
@ -0,0 +1,5 @@
|
||||
The Command Palette is used to explore SilverBullet’s numerous commands as well as execute them.
|
||||
|
||||
The UI and its operation is largely the same as the [[Page Picker]]‘s, with a few differences:
|
||||
|
||||
* If a keyboard shortcut is configured for the given command, it is listed along the command name to the right.
|
||||
@ -1,8 +1,8 @@
|
||||
## Stack
|
||||
# Stack
|
||||
SilverBullet 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 an HTTP server on [Deno](https://deno.land/) using [Oak](https://oakserver.github.io/oak/).
|
||||
|
||||
## Development
|
||||
Requirements: [Deno](https://deno.land/) 1.33 or newer. If you are running SilverBullet, you will already have Deno installed.
|
||||
# Development
|
||||
Requirements: [Deno](https://deno.land/) 1.39 or newer. If you installed [[Install/Deno]] SilverBullet you will already have your toolchain installed. Convenient!
|
||||
|
||||
Clone the repository from GitHub:
|
||||
|
||||
7
website/Editor.md
Normal file
7
website/Editor.md
Normal file
@ -0,0 +1,7 @@
|
||||
By design, the vast majority of the SilverBullet UI is taken up by the [[Markdown]] editor. This is where the magic happens.
|
||||
|
||||
This is where you write.
|
||||
|
||||
[[Slash Commands]]
|
||||
[[Templates]]
|
||||
|
||||
3
website/Full Text Search.md
Normal file
3
website/Full Text Search.md
Normal file
@ -0,0 +1,3 @@
|
||||
While, honestly not amazing, SilverBullet does have full-text search support.
|
||||
|
||||
To use it, run the {[Search Space]} command.
|
||||
3
website/Index Page.md
Normal file
3
website/Index Page.md
Normal file
@ -0,0 +1,3 @@
|
||||
The index page is the [[Pages|page]] that opens by default when either clicking the “home” button in the [[Top Bar]], or when you visit your SilverBullet’s URL without a page name in the URL.
|
||||
|
||||
The default index page’s name is `index`, but this is configurable in the [[SETTINGS]].
|
||||
@ -2,11 +2,8 @@ Welcome to wonderful world of SilverBullet. The goal of this manual is to give y
|
||||
|
||||
However, that is all unlikely to happen unless you understand what SilverBullet can actually do. So let’s give you a bit of a sense.
|
||||
|
||||
> **warning** Warning
|
||||
> This manual is **very** much a work in progress.
|
||||
|
||||
# Keeping up-to-date
|
||||
* [[CHANGELOG]]: what’s new in SilverBullet? This page will give you the latest details. It’s worth monitoring this page, especially if something broke for you.
|
||||
* [[CHANGELOG]]: what’s new in SilverBullet? This page will give you the latest details. It’s worth monitoring this page.
|
||||
|
||||
# Installation and deployment
|
||||
The biggest hurdle to get over with SilverBullet is that you need to get this thing running. And as of yet, the only way to do that is to install and deploy it yourself. 🤷
|
||||
@ -17,28 +14,59 @@ The biggest hurdle to get over with SilverBullet is that you need to get this th
|
||||
* [[Guide/Deployment/Cloudflare and Portainer]]: configuring SilverBullet with a Cloudflare tunnel, portainer and optional Cloudflare zero trust authentication.
|
||||
|
||||
# User interface
|
||||
* [[Manual/Page Picker]]
|
||||
* [[Manual/Command Palette]]
|
||||
* [[Client Modes]] (that sync button)
|
||||
SilverBullet’s UI is minimalist by design. Let’s look at the few UI elements and how to use them.
|
||||
|
||||
* The [[Top Bar]] contains:
|
||||
* [[Page Namer]]
|
||||
* [[Client Modes]] (the 🔄 button)
|
||||
* [[Index Page]] (the 🏠 button)
|
||||
* [[Page Picker]]
|
||||
* [[Command Palette]]
|
||||
* The main [[Editor]] component contains your page’s text, as well as potentially:
|
||||
* [[Table of Contents]]
|
||||
* [[Linked Mentions]]
|
||||
|
||||
# Core Concepts
|
||||
These are some
|
||||
These are the core concepts used in SilverBullet:
|
||||
* [[Spaces]]
|
||||
* [[Pages]]
|
||||
* [[Frontmatter]]
|
||||
* [[Page Name Rules]]
|
||||
* [[Folders]]
|
||||
* [[Attachments]]
|
||||
* [[Templates]]
|
||||
|
||||
# Editing and Formatting
|
||||
* [[Markdown]]
|
||||
* Content is written using [[Markdown]] and rendered using [[Live Preview]]
|
||||
* Markdown [[Markdown/Basics]]
|
||||
* Markdown [[Markdown/Extensions]]
|
||||
* [[Markdown/Admonitions]]
|
||||
* [[Plugs/Tasks]]
|
||||
* [[Markdown/Syntax Highlighting]]
|
||||
* [[Markdown/Code Widgets]]
|
||||
* [[Slash Commands]]
|
||||
* [[Manual/Outlines]]
|
||||
* [[End-User Programming]]
|
||||
|
||||
# Navigation
|
||||
The main ways to roam your space, beside following page links, are:
|
||||
* [[Page Picker]]
|
||||
* [[Linked Mentions]]
|
||||
* [[Full Text Search]]
|
||||
|
||||
# End-User Programming
|
||||
[[End-User Programming]] functionality allows you to be creative with the content you have in your space.
|
||||
* [[Objects]]
|
||||
* [[Frontmatter]]
|
||||
* [[Attributes]]
|
||||
* [[Templates]]
|
||||
* [[Live Queries]]
|
||||
* [[Live Templates]]
|
||||
* [[SETTINGS]]: A few settings you can tweak
|
||||
|
||||
# Extending SilverBullet
|
||||
A lot of SilverBullet’s functionality is built as [[Plugs]] using the robust [[PlugOS]] extension mechanism. If you are adventurous you can try to build [[Plugs/Development|such plugs yourself]].
|
||||
|
||||
# Contributing
|
||||
SilverBullet is free and open source software. You can contribute to it [via Github](https://github.com/silverbulletmd/silverbullet). For some details on how to do this, have a look at [[Development]].
|
||||
|
||||
# Personalization
|
||||
Want to tweak something? [[SETTINGS]] gives you a few settings you can tweak.
|
||||
|
||||
@ -1,5 +1,3 @@
|
||||
# Admonitions
|
||||
|
||||
Silverbullet supports [admonitions](https://github.com/community/community/discussions/16925) using GitHub syntax (`note` and `warning`).
|
||||
|
||||
> **note** This is a
|
||||
@ -5,7 +5,7 @@ Currently, SilverBullet provides two code widgets as part of its built-in [[🔌
|
||||
* `embed`
|
||||
* `markdown`
|
||||
|
||||
In addition, plugs like [[🔌 KaTeX]] and [[🔌 Mermaid]] add additional ones.
|
||||
In addition, plugs like [[Plugs/KaTeX]] and [[Plugs/Mermaid]] add additional ones.
|
||||
|
||||
## Embed
|
||||
This allows you to embed internet content into your page inside of an iframe. This is useful to, for instance, embed youtube videos. In fact, there is specific support for those.
|
||||
|
||||
@ -7,10 +7,11 @@ In addition to supporting [[Markdown/Basics|markdown basics]] as standardized by
|
||||
* [[Live Queries]]
|
||||
* [[Live Templates]]
|
||||
* [[Anchors]]
|
||||
* [[Markdown/Admonitions]]
|
||||
* Hashtags, e.g. `#mytag`.
|
||||
* [[Markdown/Command links]] syntax
|
||||
* [Tables](https://www.markdownguide.org/extended-syntax/#tables)
|
||||
* [Task lists](https://www.markdownguide.org/extended-syntax/#task-lists)
|
||||
* [Highlight](https://www.markdownguide.org/extended-syntax/#highlight)
|
||||
* [Automatic URL linking](https://www.markdownguide.org/extended-syntax/#automatic-url-linking)
|
||||
* Any addition custom markdown extensions provided by [[🔌 Plugs]]
|
||||
* Any addition custom markdown extensions provided by [[Plugs]]
|
||||
|
||||
@ -55,7 +55,7 @@ upnext render [[template/task]]
|
||||
```
|
||||
|
||||
## taskstate
|
||||
[[🔌 Tasks]] support the default `x` and ` ` states (done and not done), but custom states as well. Custom states used across your space are kept in `taskstate`:
|
||||
[[Plugs/Tasks]] support the default `x` and ` ` states (done and not done), but custom states as well. Custom states used across your space are kept in `taskstate`:
|
||||
|
||||
* [NOT STARTED] Task 1
|
||||
* [IN PROGRESS] Task 2
|
||||
|
||||
@ -1,6 +1,28 @@
|
||||
This file lists all plugs that SilverBullet will load. Run the {[Plugs: Update]} command to update and reload this list of plugs.
|
||||
SilverBullet at its core is bare bones in terms of functionality, most of its power it gains from **plugs**.
|
||||
|
||||
```yaml
|
||||
- github:silverbulletmd/silverbullet-git/git.plug.js
|
||||
- github:silverbulletmd/silverbullet-mermaid/mermaid.plug.js
|
||||
Plugs are an extension mechanism (implemented using a library called [[PlugOS]]) that runs “plug” code in the browser using [web workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers).
|
||||
|
||||
Plugs can hook into SB in various ways:
|
||||
* Extend the Markdown parser and its syntax
|
||||
* Define new commands and keybindings
|
||||
* Respond to various events triggered either on the server or client-side
|
||||
* Run recurring and background tasks.
|
||||
* 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 SilverBullet itself.
|
||||
|
||||
Plugs are distributed as self-contained JavaScript bundles (ending with `.plug.js`). SilverBullet will load all core plugs bundled with SB itself (listed below), as well as any additional plugs stored in the `_plug` folder in your [[Spaces|space]]. Typically, management of plugs in the `_plug` folder is done using [[Plug Management]].
|
||||
|
||||
# Core plugs
|
||||
These plugs are distributed with SilverBullet and are automatically enabled:
|
||||
```query
|
||||
plug where uri = null order by name render [[template/plug]]
|
||||
```
|
||||
|
||||
# Third-party plugs
|
||||
These plugs are written either by third parties or distributed separately from the main SB distribution.
|
||||
```query
|
||||
plug where uri != null order by name render [[template/plug]]
|
||||
```
|
||||
|
||||
Want to develop your own plugs? Have a look at [[Plugs/Development]].
|
||||
@ -1 +1,3 @@
|
||||
SilverBullet is developed as a [Progressive Web App](https://web.dev/progressive-web-apps/), a web application that is offline capable: after your first load and sync, (practically) all functionality is available even without a network connection.
|
||||
SilverBullet is developed as a [Progressive Web App](https://web.dev/progressive-web-apps/), a web application that is offline capable when run in [[Client Modes$sync|sync mode]].
|
||||
|
||||
After your first load and sync, (practically) all functionality is available even without a network connection.
|
||||
@ -1,4 +1,4 @@
|
||||
A few rules regarding page names:
|
||||
There are a few rules regarding page names:
|
||||
|
||||
* Page names cannot be empty
|
||||
* Page names cannot start with a `.`
|
||||
|
||||
7
website/Page Namer.md
Normal file
7
website/Page Namer.md
Normal file
@ -0,0 +1,7 @@
|
||||
At the header of each page, you see the currently open page name. Let’s call this user interface element the “Page Namer.” This element of the user interface serves a few roles:
|
||||
|
||||
* It indicates the **currently open name** (duh)
|
||||
* Its font color indicates the current **page status**:
|
||||
* Black (in light mode) indicates the page is currently saved
|
||||
* Gray (in light mode) indicates the page is currently not saved
|
||||
* By changing the page name and hitting `Enter` (or clicking/tapping outside of it) you **rename** the [[Pages|page]], automatically updating all references to it as well.
|
||||
29
website/Page Picker.md
Normal file
29
website/Page Picker.md
Normal file
@ -0,0 +1,29 @@
|
||||
The page picker functions as the primary way to navigate between [[Pages]], as well as a way to create new ones.
|
||||
|
||||
The page picker can be invoked by clicking the 📔 icon in the top bar, or by pressing `Cmd-k` on Mac, or `Ctrl-k` on Windows/Linux.
|
||||
|
||||
The main input is the **filter phrase** and can be used to narrow down the list of page results.
|
||||
|
||||
Pressing the `Enter` key will open/create the selected page. Pressing `Shift-Enter` will always open or the page _exactly matching_ the filter phrase. Therefore, if you intend to create a new page, simply type the name of the new page and hit `Shift-Enter`.
|
||||
|
||||
# Result ordering
|
||||
When no filter phrase is entered, pages are ordered by either _last opened_, or _last modified_ date in descending order. This makes it convenient to switch between recently edited pages.
|
||||
|
||||
When entering a filter phrase, the best matches should appear closer to the top, however the second option will always be an option to create a new page with _exactly_ the page name entered as the filter phrase.
|
||||
|
||||
# Keyboard shortcuts
|
||||
* `Enter`: selects the highlighted page from the list and navigate there. If that page is marked with “Create” it will create that page.
|
||||
* `Shift-Enter`: navigate to the page entered in as the filter phrase.
|
||||
* `Space`: with an empty filter phrase will attempt to do something intelligent:
|
||||
* If the currently opened page is nested in a [[Folders|folder]], it will auto complete the current folder name in its place.
|
||||
* If the currently opened page name starts with an emoji, it will complete that emoji in its place.
|
||||
* Otherwise, it will complete the full page name of the currently open page.
|
||||
* `ArrowUp`/`ArrowDown`: move up and down the highlighted page list
|
||||
* `PageUp`/`PageDown`: move up and down 5 entries in the page list in one go
|
||||
* `Home`: moves to the start of the list
|
||||
* `End`: moves to the end of the list
|
||||
* `Escape`: closes the page picker UI
|
||||
|
||||
# Mouse/touch operation
|
||||
You can obviously scroll and select an item from the list by clicking with the mouse, as well as close the page picker by clicking outside of it.
|
||||
|
||||
@ -1,5 +1,7 @@
|
||||
The primary thing you’ll be doing in SilverBullet (hopefully) is creating and editing pages. Pages are written in [[Markdown]], can contain [[Metadata]] and are kept on the server as text files.
|
||||
|
||||
Page names are relatively free-form, but have to adhere to a few [[Page Name Rules]].
|
||||
|
||||
There’s not much more to say about pages.
|
||||
|
||||
Ah one thing, [[Templates]] are “special” types of page that can be used for various purposes (e.g. as a _template_ for a new page, or to render [[Live Queries]] and [[Live Templates]]).
|
||||
11
website/Plug Management.md
Normal file
11
website/Plug Management.md
Normal file
@ -0,0 +1,11 @@
|
||||
Plug management using the `PLUGS` file is also implemented in the [[Plugs/Editor]] plug.
|
||||
|
||||
The optional `PLUGS` file is only processed when running the {[Plugs: Update]} command, in which case it will fetch all the listed plugs and copy them into the (hidden) `_plug/` folder in the user’s space. SilverBullet loads these files on boot (or on demand after running the {[Plugs: Update]} command).
|
||||
|
||||
You can also use the {[Plugs: Add]} to add a plug, which will automatically create a `PLUGS` if it does not yet exist.
|
||||
|
||||
The [[Plugs/Editor]] plug has support for the following URI prefixes for plugs:
|
||||
|
||||
* `https:` loading plugs via HTTPS, e.g. `[https://](https://raw.githubusercontent.com/silverbulletmd/silverbullet-github/main/github.plug.json)`
|
||||
* `github:org/repo/file.plug.json` internally rewritten to a `https` url as above.
|
||||
* `ghr:org/repo/version` to fetch a plug from a Github release
|
||||
51
website/Plugs/Development.md
Normal file
51
website/Plugs/Development.md
Normal file
@ -0,0 +1,51 @@
|
||||
> **warning** Unstable APIs
|
||||
> The plug APIs are still unstable and tend to change. You’re welcome to experiment and build stuff, but do take into account that things tend to change. Also note that all this is horrifically under documented.
|
||||
|
||||
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.yaml`. This file defines all functions that form your plug. To be loadable by SilverBullet (or any PlugOS-based system for that matter), it needs to be compiled into a bundle (ending with `.plug.js`).
|
||||
|
||||
Generally, the way to do this is to run `silverbullet plug:compile` as follows:
|
||||
|
||||
```shell
|
||||
silverbullet plug:compile yourplugname.plug.yaml
|
||||
```
|
||||
|
||||
During development, you may want to compile plugs in debug mode, which will not minify them and generate source maps:
|
||||
|
||||
```shell
|
||||
silverbullet plug:compile --debug yourplugname.plug.yaml
|
||||
```
|
||||
|
||||
If you use the plug template, this command is wrapped in your `deno.jsonc` file, so you can just run either:
|
||||
|
||||
```shell
|
||||
deno task build
|
||||
```
|
||||
|
||||
to build it once, or
|
||||
|
||||
```shell
|
||||
deno task watch
|
||||
```
|
||||
|
||||
to build it and rebuild it when files are changed. This will write a `yourplugname.plug.js` file into the same folder.
|
||||
|
||||
For development it’s easiest to simply copy the `.plug.js` file into your space’s `_plug/` folder:
|
||||
|
||||
```shell
|
||||
cp myplug.plug.js ~/myspace/_plug/
|
||||
```
|
||||
|
||||
Within seconds (watch your browser’s JavaScript console), your plug should be picked up both on the server and, synced to your browser and loaded. No need to even reload the page.
|
||||
|
||||
## Debugging
|
||||
Since plugs run in your browser, you can use the usual browser debugging tools. When you `console.log` things, these logs will appear in your browser’s JavaScript console.
|
||||
|
||||
## Distribution
|
||||
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.js` file there and instructing users to point to by adding
|
||||
`- github:yourgithubuser/yourrepo/yourplugname.plug.js` to their `PLUGS` file
|
||||
- Add a release in your github repo and instruct users to add the release as `- ghr:yourgithubuser/yourrepo` or if they need a specific 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.js`.
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
The `editor` plug implements foundational editor functionality for SilverBullet.
|
||||
|
||||
## Commands
|
||||
# Commands
|
||||
|
||||
* {[Editor: Toggle Dark Mode]}: toggles dark mode
|
||||
* {[Editor: Toggle Vim Mode]}: toggle vim mode, see: [[Vim]]
|
||||
@ -10,18 +10,18 @@ The `editor` plug implements foundational editor functionality for SilverBullet.
|
||||
* {[Help: Getting Started]}: Open getting started guide
|
||||
* {[Help: Version]}: Show version number
|
||||
|
||||
### Pages
|
||||
## Pages
|
||||
* {[Page: New]}: Create a new (untitled) page. Note that usually you would create a new page simply by navigating to a page name that does not yet exist.
|
||||
* {[Page: Delete]}: delete the current page
|
||||
* {[Page: Copy]}: copy the current page
|
||||
|
||||
### Navigation
|
||||
## Navigation
|
||||
* {[Navigate: Home]}: navigate to the home (index) page
|
||||
* {[Navigate To page]}: navigate to the page under the cursor
|
||||
* {[Navigate: Center Cursor]}: center the cursor at the center of the screen
|
||||
* {[Navigate: Move Cursor to Position]}: move cursor to a specific (numeric) cursor position (# of characters from the start of the document)
|
||||
|
||||
### Text editing
|
||||
## Text editing
|
||||
* {[Text: Quote Selection]}: turns the selection into a blockquote (`>` prefix)
|
||||
* {[Text: Listify Selection]}: turns the lines in the selection into a bulleted list
|
||||
* {[Text: Number Listify Selection]}: turns the lines in the selection into a numbered list
|
||||
@ -32,13 +32,11 @@ The `editor` plug implements foundational editor functionality for SilverBullet.
|
||||
* {[Text: Marker]}: mark text with a ==marker color==
|
||||
* {[Link: Unfurl]}: “Unfurl” a link, see [[🔌 Editor/Link Unfurl]]
|
||||
|
||||
### Folding commands
|
||||
* {[Fold: Fold]}: fold current section (list, header)
|
||||
* {[Fold: Unfold]}: unfold current section
|
||||
* {[Fold: Fold All]}: fold all sections
|
||||
* {[Fold: Unfold All]}: unfold all sections
|
||||
|
||||
## Debug
|
||||
# Outlines
|
||||
```template
|
||||
page: "[[Manual/Outlines]]"
|
||||
```
|
||||
# Debug
|
||||
Commands you shouldn’t need, but are nevertheless there:
|
||||
|
||||
* {[Debug: Reset Client]}: clean out all cached data on the client and reload
|
||||
@ -2,10 +2,10 @@
|
||||
|
||||
SilverBullet has a generic indexing infrastructure for [[Objects]]. Pages are automatically index upon save, so about every second.
|
||||
|
||||
The [[🔌 Index]] plug also defines syntax for [[Tags]].
|
||||
The [[Plugs/Index]] plug also defines syntax for [[Tags]].
|
||||
|
||||
## Content indexing
|
||||
The [[🔌 Index]] plug indexes the following:
|
||||
The [[Plugs/Index]] plug indexes the following:
|
||||
|
||||
* [[Metadata]]
|
||||
* [[Tags]]
|
||||
@ -3,4 +3,4 @@
|
||||
The Markdown plug provides support for various advanced Markdown features, specifically:
|
||||
|
||||
* {[Markdown Preview: Toggle]} preview
|
||||
* Sharing via the `file:` [[🔌 Share]] provider
|
||||
* Sharing via the `file:` [[Plugs/Share]] provider
|
||||
@ -4,6 +4,11 @@ repo: https://github.com/silverbulletmd/silverbullet-mattermost
|
||||
author: Zef Hemel
|
||||
---
|
||||
#plug #share-support
|
||||
|
||||
> **warning** Unmaintained
|
||||
> This plug is currently not being maintained, it may break at any time
|
||||
|
||||
|
||||
```template
|
||||
page: "[[!raw.githubusercontent.com/silverbulletmd/silverbullet-mattermost/main/README]]"
|
||||
raw: true
|
||||
@ -1,6 +1,6 @@
|
||||
#plug
|
||||
|
||||
The [[🔌 Template]] plug implements a few templating mechanisms.
|
||||
The [[Plugs/Template]] plug implements a few templating mechanisms.
|
||||
|
||||
### Page Templates
|
||||
> **Warning** Deprecated
|
||||
@ -5,6 +5,7 @@ uri: github:silverbulletmd/silverbullet-twitter/twitter.plug.js
|
||||
repo: https://github.com/silverbulletmd/silverbullet-twitter
|
||||
author: SilverBullet Authors
|
||||
---
|
||||
Remember Twitter?
|
||||
|
||||
```template
|
||||
page: "[[!raw.githubusercontent.com/silverbulletmd/silverbullet-twitter/main/README]]"
|
||||
@ -1,4 +1,4 @@
|
||||
This page contains settings for configuring SilverBullet and its Plugs. Changing any of these in most cases will go into effect immediately, except for `indexPage` which requires a reload.
|
||||
This page contains settings for configuring SilverBullet and its Plugs. Changing any of these in most cases will go into effect immediately, except `indexPage` and `customStyles` which require a reload.
|
||||
|
||||
```yaml
|
||||
# Initial page to load when launching SB
|
||||
|
||||
@ -1,11 +1,11 @@
|
||||
# Introduction
|
||||
SilverBullet aims to be your **workshop for the mind**: a creative [[Spaces]] where you collect, create and expand your personal knowledge, while also letting you constantly evolve the tools you use to do so.
|
||||
SilverBullet aims to be a **workshop for the mind**: a creative [[Spaces|space]] where you collect, create and expand your personal knowledge, while also letting you constantly evolve the tools you use to do so.
|
||||
|
||||
So yes, it’s basically a somewhat geeky note taking application.
|
||||
So yeah, it’s basically a somewhat geeky note taking application or personal wiki.
|
||||
|
||||
While you _can_ use SilverBullet as just a note taking application that stores notes in plain [[Markdown]] files on disk, it becomes truly powerful in the hands of more technical power users. By leveraging [[Metadata]] annotations, its [[Objects]] infrastructure, [[Live Queries]] and [[Live Templates]], SilverBullet becomes a powerful [[End-User Programming]] tool, enabling you to quickly develop various types of ad-hoc knowledge systems.
|
||||
While you _can_ use SilverBullet as just a note taking application that stores notes in plain [[Markdown]] files on disk; it becomes truly powerful in the hands of more technical power users. By leveraging [[Metadata]] annotations, its [[Objects]] infrastructure, [[Live Queries]] and [[Live Templates]], it becomes a powerful [[End-User Programming]] tool, enabling you to quickly develop various types of ad-hoc knowledge systems.
|
||||
|
||||
SilverBullet is implemented as an _open-source_, _self-hosted_, _offline-capable_ web application (PWA). In order to use it, you have to self host it: that is, you need to run the web server either on your own machine or in the cloud somewhere. See [[Install]] for instructions.
|
||||
SilverBullet is implemented as an _open-source_, _self-hosted_, _offline-capable_ web application ([[PWA]]). In order to use it, you have to self host it: that is, you need to run the web server either on your own machine, somewhere on your network, or in the cloud somewhere. See our [[Install|installation instructions]].
|
||||
|
||||
You may have been told there is _no such thing_ as a [silver bullet](https://en.wikipedia.org/wiki/Silver_bullet).
|
||||
|
||||
@ -13,7 +13,7 @@ You were told wrong.
|
||||
|
||||
# Links for the impatient
|
||||
* [[Install]]: how to install and deploy SilverBullet
|
||||
* [[Manual]]: the beginnings of a user manual
|
||||
* [[Manual]]: how to use this thing
|
||||
* [[CHANGELOG]]: SilverBullet is in active development, so things change rapidly. Watch this to see what’s new and changed.
|
||||
* Development:
|
||||
* [Roadmap](https://github.com/orgs/silverbulletmd/projects/2/views/1): currently planned features and priorities
|
||||
@ -24,13 +24,12 @@ You were told wrong.
|
||||
* [Discord](https://discord.gg/EvXbFucTxn): For more real-time support and discussion, join our Discord!
|
||||
|
||||
# Features
|
||||
Alright then. Beyond the fancy, aspirational vision-y talk. What does this thing actually do and how does it work? You know... features, we need a feature list!
|
||||
Alright then. Beyond the fancy, aspirational vision-y talk. What does this thing actually do, and how does it work? You know... features, we need a feature list!
|
||||
|
||||
SilverBullet...
|
||||
* Runs in any modern browser (including on mobile) as a [[PWA]] in two [[Client Modes]] (_online_ and _synced_ mode), where the _synced mode_ enables **100% offline operation**, keeping a copy of content in the browser’s local ([IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API)) database, syncing back to the server when a network connection is available.
|
||||
* 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. Incoming links are indexed and appear as [[Linked Mentions]] at the bottom of the pages linked to thereby providing _bi-directional linking_.
|
||||
* Optimized for **keyboard-based operation**:
|
||||
* SilverBullet runs in any modern browser (including mobile ones) as a [[PWA]] in two [[Client Modes]] (_online_ and _synced_ mode), where the _synced mode_ enables **100% offline operation**, keeping a copy of content in the browser’s local ([IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API)) database, syncing back to the server when a network connection is available.
|
||||
* SilverBullet 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.
|
||||
* SilverBullet supports wiki-style **page linking** using the `[[page link]]` syntax. Incoming links are indexed and appear as [[Linked Mentions]] at the bottom of the pages linked to thereby providing _bi-directional linking_.
|
||||
* SilverBullet is 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).
|
||||
* Use [[Slash Commands]] to perform common text editing operations.
|
||||
|
||||
@ -1,11 +1,11 @@
|
||||
Slash commands are built-in to SilverBullet. You can trigger them by typing a `/` in your text (after whitespace).
|
||||
|
||||
The [[🔌 Editor]] plug provides a few helpful ones:
|
||||
The [[Plugs/Editor]] plug provides a few helpful ones:
|
||||
|
||||
* `/h1` through `/h4` to turn the current line into a header
|
||||
* `/hr` to insert a horizontal rule (`---`)
|
||||
* `/table` to insert a markdown table (whoever can remember this syntax without it)
|
||||
* `/snippet` see [[🔌 Template@snippets]]
|
||||
* `/snippet` see [[Plugs/Template@snippets]]
|
||||
* `/today` to insert today’s date
|
||||
* `/tomorrow` to insert tomorrow’s date
|
||||
|
||||
|
||||
@ -1,3 +1,3 @@
|
||||
The TOC (Table of Contents) widget, when enabled, shows a table of contents at the start of the page for any page with 3 headers or more.
|
||||
The Table of Contents widget, when enabled, shows a table of contents at the start of the page for any page with 3 headers or more. It is updated whenever hovering the mouse cursor over it. Clicking any of the headers will navigate there within the page.
|
||||
|
||||
You can enable/disable this feature via {[Table of Contents: Toggle]}.
|
||||
@ -5,7 +5,7 @@ Templates are used in a few different contexts:
|
||||
1. To render [[Live Queries]]
|
||||
2. To render [[Live Templates]]
|
||||
3. To be included using [[Slash Templates]]
|
||||
4. Some legacy use cases described in [[🔌 Template]]
|
||||
4. Some legacy use cases described in [[Plugs/Template]]
|
||||
|
||||
## Creating templates
|
||||
Templates are defined as any other page. It’s convenient, although not required, to use a `template/` prefix when naming templates. It is also _recommended_ to tag templates with a `#template` tag. Note that this tag will be removed when the template is instantiated.
|
||||
|
||||
12
website/Top Bar.md
Normal file
12
website/Top Bar.md
Normal file
@ -0,0 +1,12 @@
|
||||
The top bar contains:
|
||||
|
||||
* [[Page Namer]]
|
||||
* The [[Client Modes]] selector
|
||||
* The home button, navigating to your [[Index Page]]
|
||||
* [[Page Picker]]
|
||||
* [[Command Palette]]
|
||||
|
||||
In addition the top bar color indicates the current online status (when the client is in [[Client Modes$sync|sync mode]]):
|
||||
|
||||
* **Gray** indicates SilverBullet is connected to the server
|
||||
* **Yellow** indicates not having a server connection
|
||||
@ -1,4 +1,4 @@
|
||||
The [[🔌 Editor]] plug provides various useful edit commands, such as:
|
||||
The [[Plugs/Editor]] plug provides various useful edit commands, such as:
|
||||
|
||||
* {[Text: Bold]} {[Text: Italic]} {[Text: Marker]} to respectively make text bold, italic or mark it.
|
||||
* {[Text: Listify Selection]} to turn each line in the selection into a (bullet) list
|
||||
|
||||
@ -1 +0,0 @@
|
||||
All pages are indexed using SQLite’s FTS5 mechanism. This functionality can be much improved, but it works. You can use it via the {[Search Space]} command.
|
||||
@ -1,11 +0,0 @@
|
||||
Plug management using the [[PLUGS]] file is also implemented in the [[🔌 Editor]] plug.
|
||||
|
||||
The optional [[PLUGS]] file is only processed when running the {[Plugs: Update]} command, in which case it will fetch all the listed plugs and copy them into the (hidden) `_plug/` folder in the user’s space. SilverBullet loads these files on boot (or on demand after running the {[Plugs: Update]} command).
|
||||
|
||||
You can also use the {[Plugs: Add]} to add a plug, which will automatically create a [[PLUGS]] if it does not yet exist.
|
||||
|
||||
The [[🔌 Editor]] plug has support for the following URI prefixes for plugs:
|
||||
|
||||
* `https:` loading plugs via HTTPS, e.g. `[https://](https://raw.githubusercontent.com/silverbulletmd/silverbullet-github/main/github.plug.json)`
|
||||
* `github:org/repo/file.plug.json` internally rewritten to a `https` url as above.
|
||||
* `ghr:org/repo/version` to fetch a plug from a Github release
|
||||
@ -1,45 +0,0 @@
|
||||
#plug
|
||||
|
||||
> **Warning** Deprecated
|
||||
> Directives are now deprecated and will likely soon be removed, use [[Live Templates]] and [[Live Queries]] instead.
|
||||
|
||||
|
||||
The directive plug is a built-in plug implementing various so-called “directive” that all take the form of `<!-- #directiveName ... -->` and close with `<!-- /directiveName -->`. Currently the following directives are supported:
|
||||
|
||||
* `#query` to perform queries: [[Live Queries]]
|
||||
* `#include` to inline the content of another page verbatim: [[@include]]
|
||||
* `#use` to use the content of another as a [handlebars](https://handlebarsjs.com/) template: [[@use]]
|
||||
* `#eval` to evaluate an arbitrary JavaScript expression and inline the result: [[@eval]]
|
||||
|
||||
|
||||
## Include
|
||||
$include
|
||||
The `#include` directive can be used to embed another page into your existing one. The syntax is as follows:
|
||||
|
||||
<!-- #include [[page reference]] -->
|
||||
|
||||
<!-- /include -->
|
||||
|
||||
Whenever the directives are updated, the body of the directive will be replaced with the latest version of the reference page.
|
||||
|
||||
## Use
|
||||
$use
|
||||
The `#use` directive can be used to use a referenced page as a handlebars template. Optionally, a JSON object can be passed as argument to the template:
|
||||
|
||||
<!-- #use [[template/plug]] {"name": "🔌 Directive", "repo": "https://google.com", "author": "Pete"} -->
|
||||
|
||||
<!-- /use -->
|
||||
|
||||
which renders as follows:
|
||||
<!-- #use [[template/plug]] {"name": "🔌 Directive", "repo": "https://google.com", "author": "Pete"} -->
|
||||
* [[🔌 Directive]] by **Pete** ([repo](https://google.com))
|
||||
<!-- /use -->
|
||||
* [ ] #test This is a test task
|
||||
|
||||
Note that a string is also a valid JSON value:
|
||||
|
||||
So, for instance, a template can take a tag name as an argument:
|
||||
|
||||
<!-- #use [[template/tagged-tasks]] "test" -->
|
||||
* [ ] [[🔌 Directive@1537]] This is a test task #test
|
||||
<!-- /use -->
|
||||
@ -1,5 +1,5 @@
|
||||
SilverBullet has infrastructure to “unfurl” — that is: replace with something nice — various types of URLs. Unfurling can be triggered by putting your cursor on any “naked” URL, and running the {[Link: Unfurl]} command.
|
||||
|
||||
Plugs can provide custom unfurls for specific URL patterns. For instance the [[🔌 Twitter]] plug provides the ability to unfurl tweets, and pull in their content.
|
||||
Plugs can provide custom unfurls for specific URL patterns. For instance the [[Plugs/Twitter]] plug provides the ability to unfurl tweets, and pull in their content.
|
||||
|
||||
[[🔌 Editor]] provides a generic URL unfurl, adding a title for a url.
|
||||
[[Plugs/Editor]] provides a generic URL unfurl, adding a title for a url.
|
||||
@ -1,78 +0,0 @@
|
||||
SilverBullet 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’s part of the silverbullet repo) that runs “plug” code in the browser using [web workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers).
|
||||
|
||||
Plugs can hook into SB in various ways:
|
||||
|
||||
* Extend the Markdown parser and its syntax
|
||||
* Define new commands and keybindings
|
||||
* Respond to various events triggered either on the server or client-side
|
||||
* Run recurring and background tasks.
|
||||
* 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.
|
||||
|
||||
Plugs are distributed as self-contained JavaScript bundles (ending with `.plug.js`). 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 SilverBullet and are automatically enabled:
|
||||
```query
|
||||
plug where uri = null order by name render [[template/plug]]
|
||||
```
|
||||
## Third-party plugs
|
||||
These plugs are written either by third parties or distributed separately from the main SB distribution:
|
||||
```query
|
||||
plug where uri != null order by name render [[template/plug]]
|
||||
```
|
||||
|
||||
## 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 SilverBullet (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:
|
||||
|
||||
```shell
|
||||
silverbullet plug:compile yourplugname.plug.yaml
|
||||
```
|
||||
|
||||
During development, you may want to compile plugs in debug mode, which will not minify them and generate source maps:
|
||||
|
||||
```shell
|
||||
silverbullet plug:compile --debug yourplugname.plug.yaml
|
||||
```
|
||||
|
||||
If you use the plug template, this command is wrapped in your `deno.jsonc` file, so you can just run either:
|
||||
|
||||
```shell
|
||||
deno task build
|
||||
```
|
||||
|
||||
to build it once, or
|
||||
|
||||
```shell
|
||||
deno task watch
|
||||
```
|
||||
|
||||
to build it and rebuild it when files are changed. This will write a `yourplugname.plug.js` file into the same folder.
|
||||
|
||||
Once you have a compiled `.plug.js` 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 simply copy the `.plug.js` file into your space’s `_plug/` folder:
|
||||
|
||||
```shell
|
||||
cp myplug.plug.js ~/myspace/_plug/
|
||||
```
|
||||
|
||||
Within seconds (watch your browser’s JavaScript console), your plug should be picked up, synced to your browser and loaded. No need to even reload the page.
|
||||
|
||||
## Debugging
|
||||
Since plugs run in your browser, you can use the usual browser debugging tools. When you console.log things, these logs will appear in your browser’s JavaScript console.
|
||||
|
||||
## Distribution
|
||||
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.js` file there and instructing users to point to by adding
|
||||
`- github:yourgithubuser/yourrepo/yourplugname.plug.js` to their `PLUGS` file
|
||||
- Add a release in your github repo and instruct users to add the release as `- ghr:yourgithubuser/yourrepo` or if they need a specific 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.js`.
|
||||
Loading…
Reference in New Issue
Block a user