Manual refactor
This commit is contained in:
Zef Hemel
@@ -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`.
|
||||
@@ -0,0 +1,45 @@
|
||||
#plug
|
||||
|
||||
The `editor` plug implements foundational editor functionality for SilverBullet.
|
||||
|
||||
# Commands
|
||||
|
||||
* {[Editor: Toggle Dark Mode]}: toggles dark mode
|
||||
* {[Editor: Toggle Vim Mode]}: toggle vim mode, see: [[Vim]]
|
||||
* {[Stats: Show]}: shows some stats about the current page (word count, reading time etc.)
|
||||
* {[Help: Getting Started]}: Open getting started guide
|
||||
* {[Help: Version]}: Show version number
|
||||
|
||||
## 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
|
||||
* {[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: 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
|
||||
* {[Text: Link Selection]}: turns the selection into a link.
|
||||
#ProTip You can can also select text and paste a URL on it via `Ctrl-v`/`Cmd-v` to turn it into a link)
|
||||
* {[Text: Bold]}: make text **bold**
|
||||
* {[Text: Italic]}: make text _italic_
|
||||
* {[Text: Marker]}: mark text with a ==marker color==
|
||||
* {[Link: Unfurl]}: “Unfurl” a link, see [[🔌 Editor/Link Unfurl]]
|
||||
|
||||
# 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
|
||||
* {[Debug: Reload UI]}: reload the UI (same as refreshing the page)
|
||||
* {[Account: Logout]}: (when using built-in [[Authentication]]) Logout
|
||||
|
||||
@@ -0,0 +1,3 @@
|
||||
#plug
|
||||
|
||||
The Emoji plug provides support for auto-completion of the `:emoji:` style syntax. It currently has support for the [15.1 emoji unicode standard](https://emojipedia.org/emoji-15.1).
|
||||
@@ -0,0 +1,10 @@
|
||||
---
|
||||
uri: github:silverbulletmd/silverbullet-github/github.plug.js
|
||||
repo: https://github.com/silverbulletmd/silverbullet-github
|
||||
author: Zef Hemel
|
||||
---
|
||||
#plug #share-support
|
||||
```template
|
||||
page: "[[!raw.githubusercontent.com/silverbulletmd/silverbullet-github/main/README]]"
|
||||
raw: true
|
||||
```
|
||||
@@ -0,0 +1,21 @@
|
||||
#plug
|
||||
|
||||
SilverBullet has a generic indexing infrastructure for [[Objects]]. Pages are automatically index upon save, so about every second.
|
||||
|
||||
The [[Plugs/Index]] plug also defines syntax for [[Tags]].
|
||||
|
||||
## Content indexing
|
||||
The [[Plugs/Index]] plug indexes the following:
|
||||
|
||||
* [[Metadata]]
|
||||
* [[Tags]]
|
||||
* Page backlinks (queryable via the `link` query source), this information is used when renaming a page (automatically updating pages that link to it).
|
||||
* List items, such as bulleted and numbered lists (queryable via the `item` query source)
|
||||
* Paragraphs
|
||||
|
||||
## Commands
|
||||
* {[Space: Reindex]}: Reindexes the entire space
|
||||
* {[Page: Rename]}: Rename a page
|
||||
#ProTip Renaming is more conveniently done by editing the page name in the header and hitting `Enter`.
|
||||
* {[Page: Batch Rename Prefix]}: Rename a page prefix across the entire space
|
||||
* {[Page: Extract]}: Extract the selected text into its own page
|
||||
@@ -0,0 +1,12 @@
|
||||
---
|
||||
tags:
|
||||
- plug
|
||||
uri: github:silverbulletmd/silverbullet-katex/katex.plug.js
|
||||
repo: https://github.com/silverbulletmd/silverbullet-katex
|
||||
author: Zef Hemel
|
||||
---
|
||||
|
||||
```template
|
||||
page: "[[!raw.githubusercontent.com/silverbulletmd/silverbullet-katex/main/README]]"
|
||||
raw: true
|
||||
```
|
||||
@@ -0,0 +1,6 @@
|
||||
#share-support #plug
|
||||
|
||||
The Markdown plug provides support for various advanced Markdown features, specifically:
|
||||
|
||||
* {[Markdown Preview: Toggle]} preview
|
||||
* Sharing via the `file:` [[Plugs/Share]] provider
|
||||
@@ -0,0 +1,15 @@
|
||||
---
|
||||
uri: github:silverbulletmd/silverbullet-mattermost/mattermost.plug.json
|
||||
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
|
||||
```
|
||||
@@ -0,0 +1,18 @@
|
||||
---
|
||||
tags:
|
||||
- plug
|
||||
uri: github:silverbulletmd/silverbullet-mermaid/mermaid.plug.js
|
||||
repo: https://github.com/silverbulletmd/silverbullet-mermaid
|
||||
author: Zef Hemel
|
||||
---
|
||||
|
||||
Example use:
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start --> Stop
|
||||
```
|
||||
|
||||
```template
|
||||
page: "[[!raw.githubusercontent.com/silverbulletmd/silverbullet-mermaid/main/README]]"
|
||||
raw: true
|
||||
```
|
||||
@@ -0,0 +1,10 @@
|
||||
---
|
||||
uri: github:m1lt0n/silverbullet-serendipity/serendipity.plug.json
|
||||
repo: https://github.com/m1lt0n/silverbullet-serendipity
|
||||
author: Pantelis Vratsalis
|
||||
---
|
||||
#plug
|
||||
```template
|
||||
page: "[[!raw.githubusercontent.com/m1lt0n/silverbullet-serendipity/main/README]]"
|
||||
raw: true
|
||||
```
|
||||
@@ -0,0 +1,13 @@
|
||||
---
|
||||
repo: https://github.com/silverbulletmd/silverbullet
|
||||
---
|
||||
#plug
|
||||
|
||||
The Share plug provides infrastructure for sharing pages outside of your space. It standardizes the {[Share: Publish]} (bound to `Cmd-s` or `Ctrl-s`) to publish the current page to all share providers specified under the `$share` key in [[Frontmatter]].
|
||||
|
||||
See the [original RFC](https://github.com/silverbulletmd/silverbullet/discussions/117) for implementation details.
|
||||
|
||||
Specific implementations for sharing are implemented in other plugs, specifically:
|
||||
```query
|
||||
share-support render [[template/page]]
|
||||
```
|
||||
@@ -0,0 +1,53 @@
|
||||
#plug
|
||||
|
||||
The Tasks plug implements task support in SilverBullet.
|
||||
|
||||
## Task states
|
||||
The tasks plug support the standard “done” and “not done” states via `[x]` and `[ ]` notation in the context of a list (this is fairly widely accepted [[Markdown]] syntax):
|
||||
|
||||
* [ ] This is a task (toggle me!)
|
||||
|
||||
However, custom states can also be used for extra flexibility:
|
||||
|
||||
* [TODO] This task is still to do
|
||||
* [IN PROGRESS] In progress task
|
||||
* [RESOLVED] A resolved task
|
||||
* [-] Whatever this state means
|
||||
* [/] Or this one
|
||||
|
||||
You can cycle through the states by clicking on the status or by running the {[Task: Cycle State]} command while on a task. There is also auto complete for all known custom task states in a space.
|
||||
|
||||
## Annotations
|
||||
Tasks can also be annotated with [[Tags]]:
|
||||
|
||||
* [ ] This is a tagged task #my-tag
|
||||
|
||||
As well as [[Attributes]]:
|
||||
|
||||
* [ ] This is a task with attributes [taskAttribute: true]
|
||||
|
||||
## Deadlines
|
||||
|
||||
Tasks can specify deadlines:
|
||||
|
||||
* [ ] This is due 📅 2022-11-26
|
||||
|
||||
When the cursor is positioned inside of a due date, the {[Task: Postpone]} command can be used to postpone the task for a certain period.
|
||||
|
||||
## Querying
|
||||
All meta data (`done` status, `state`, `tags`, `deadline` and custom attributes) is extracted and available via the `task` query source to [[Live Queries]]:
|
||||
|
||||
```query
|
||||
task where page = "{{@page.name}}"
|
||||
```
|
||||
|
||||
## Rendering
|
||||
There is a [[!silverbullet.md/template/tasks/task]] template you can use to render tasks nicely rather than using the default table (as demonstrated above). When you use this template, you can even cycle through the states of the task by click on its state _inside_ the rendered query, and it will update the state of the _original_ task automatically (although not yet in reverse) — this works across pages.
|
||||
|
||||
Try it (by clicking on the checkbox inside of the directive):
|
||||
|
||||
```query
|
||||
task where page = "{{@page.name}}" and name = "Remote toggle me" render [[template/task]]
|
||||
```
|
||||
|
||||
* [ ] Remote toggle me
|
||||
@@ -0,0 +1,82 @@
|
||||
#plug
|
||||
|
||||
The [[Plugs/Template]] plug implements a few templating mechanisms.
|
||||
|
||||
### Page Templates
|
||||
> **Warning** Deprecated
|
||||
> Use [[Slash Templates]] instead
|
||||
|
||||
The {[Template: Instantiate Page]} command enables you to create a new page based on a page template.
|
||||
|
||||
Page templates, by default, are looked for in the `template/page/` prefix. So creating e.g. a `template/page/Meeting Notes` page will create a “Meeting Notes” template. You can override this prefix by setting the `pageTemplatePrefix` in `SETTINGS`.
|
||||
|
||||
Page templates have one “magic” type of page metadata that is used during
|
||||
instantiation:
|
||||
|
||||
* `$name` is used as the default value for a new page based on this template
|
||||
|
||||
In addition, any standard template placeholders are available (see below)
|
||||
|
||||
For instance:
|
||||
|
||||
---
|
||||
$name: "📕 "
|
||||
---
|
||||
|
||||
# {{@page.name}}
|
||||
As recorded on {{today}}.
|
||||
|
||||
## Introduction
|
||||
## Notes
|
||||
## Conclusions
|
||||
|
||||
Will prompt you to pick a page name (defaulting to “📕 “), and then create the following page (on 2022-08-08) when you pick “📕 Harry Potter” as a page name:
|
||||
|
||||
# 📕 Harry Potter
|
||||
As recorded on 2022-08-08.
|
||||
|
||||
## Introduction
|
||||
## Notes
|
||||
## Conclusions
|
||||
|
||||
### Snippets
|
||||
$snippets
|
||||
> **Warning** Deprecated
|
||||
> Use [[Slash Templates]] instead
|
||||
|
||||
Snippets are similar to page templates, except you insert them into an existing page with the `/snippet` slash command. The default prefix is `snippet/` which is configurable via the `snippetPrefix` setting in `SETTINGS`.
|
||||
|
||||
Snippet templates do not support the `$name` page meta, because it doesn’t apply.
|
||||
|
||||
However, snippets do support the special `|^|` placeholder for placing the cursor caret after injecting the snippet. If you leave it out, the cursor will simply be placed at the end, but if you like to insert the cursor elsewhere, that position can be set with the `|^|` placeholder.
|
||||
|
||||
For instance to replicate the `/query` slash command as a snippet:
|
||||
|
||||
<!-- #query |^| -->
|
||||
|
||||
<!-- /query -->
|
||||
|
||||
Which would insert the cursor right after `#query`.
|
||||
|
||||
### Daily Note
|
||||
|
||||
The {[Open Daily Note]} command navigates (or creates) a daily note prefixed with a 📅 emoji by default, but this is configurable via the `dailyNotePrefix` setting in `SETTINGS`. If you have a page template (see above) named `template/page/Daily Note` it will use this as a template, otherwise, the page will just be empty (this path is also configurable via the `dailyNoteTemplate` setting).
|
||||
|
||||
### Weekly Note
|
||||
|
||||
The {[Open Weekly Note]} command navigates (or creates) a weekly note prefixed
|
||||
with a 🗓️ emoji by default, but this is configurable via the `weeklyNotePrefix` setting in `SETTINGS`. If you have a page template (see above) named `template/page/Weekly Note` it will use this as a template, otherwise, the page will just be empty.
|
||||
|
||||
### Quick Note
|
||||
|
||||
The {[Quick Note]} command will navigate to an empty page named with the current date and time prefixed with a 📥 emoji, but this is configurable via the `quickNotePrefix` in `SETTINGS`. The use case is to take a quick note outside of your current context.
|
||||
|
||||
## Built-in slash commands
|
||||
* `/frontmatter`: Insert [[Frontmatter]]
|
||||
* `/h1` - `/h4`: turn the current line into a header
|
||||
* `/code`: insert a fenced code block
|
||||
* `/hr`: insert a horizontal rule
|
||||
* `/table`: insert a table
|
||||
* `/page-template`: insert a page template
|
||||
* `/today`: insert today’s date
|
||||
* `/tomorrow`: insert tomorrow’s date
|
||||
@@ -0,0 +1,13 @@
|
||||
---
|
||||
tags:
|
||||
- plug
|
||||
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]]"
|
||||
raw: true
|
||||
```
|
||||
Reference in New Issue
Block a user