Using topWidget to render beta-level on website
This commit is contained in:
Zef Hemel
@@ -1,19 +1,19 @@
|
||||
> **warning** Beta feature
|
||||
> This is a **beta** feature. Feel free to use it, but it may change (significantly) in the future or potentially replaced.
|
||||
#maturity/beta
|
||||
|
||||
SilverBullet is designed to be [[Extensions|extensible]]. In fact, a lot of functionality in SilverBullet is implemented through [[Space Lua]] embedded in [[Meta Pages]], other functionality is implemented using [[Plugs]].
|
||||
|
||||
A big part of the fun of SilverBullet is building your own extensions, bit or small. Libraries are the way to [[Share]] those extensions. Both for you to [[Libraries/Development|publish your own]] libraries, and to pull in other people’s creations.
|
||||
A big part of the fun of SilverBullet is building your own extensions, big or small. Libraries are the way to [[Share]] those extensions. Both for you to [[Libraries/Development|publish your own]] libraries, and to pull in other people’s creations.
|
||||
|
||||
There are a few things at play here:
|
||||
# Terms
|
||||
Let’s define terms:
|
||||
|
||||
[[Libraries]] are the **unit of distribution**, typically implemented as [[Meta Pages]]. Most libraries will be implemented in a single page (e.g. with a big [[Space Lua]] block), but more elaborate libraries may span multiple pages, some may contain [[Plugs]].
|
||||
[[Libraries]] are the **unit of distribution**, typically implemented as [[Meta Pages]]. Most libraries will be implemented in a single page (e.g. with a big [[Space Lua]] block), but more elaborate libraries may span multiple pages, some may wrap [[Plugs]].
|
||||
|
||||
[[Repositories]] are a **discovery mechanism** for libraries. They are collections of _pointers_ of _where_ to find libraries to install.
|
||||
[[Repositories]] are a **discovery and curation mechanism** for libraries. They are collections of _pointers_ of _where_ to find libraries to install. SilverBullet ships with the [[^Repositories/Std]] repository, but you can install additional ones.
|
||||
|
||||
[[Share]] is the general-purpose mechanism built into SilverBullet to both _push_, _pull_ and _sync_ content in your space with the outside world. In the context of Libraries this mechanism is used (partially under the hood, but you’ll recognize traces of it) both for you to _publish_ your libraries somewhere, as well as to _install_ and _update_ other people’s creations.
|
||||
[[Share]] is the general-purpose mechanism built into SilverBullet to both _push_, _pull_ and _sync_ content in your space with the outside world. In the context of Libraries this mechanism is used (partially under the hood, but you’ll recognize traces of it) both for you to _publish_ your libraries, as well as to _install_ and _update_ other people’s creations.
|
||||
|
||||
To make discovery and installation of libraries easier, SilverBullet includes a [[Library Manager]].
|
||||
To make discovery and installation of libraries easier, SilverBullet includes a basic [[Library Manager]].
|
||||
|
||||
By convention, libraries are kept under the `Library/` prefix (folder) in your space.
|
||||
|
||||
@@ -26,7 +26,7 @@ Here are some things that a library may provide:
|
||||
* Additional functionality with compiled [[Plugs]]
|
||||
|
||||
# Can I change libraries locally?
|
||||
Libraries you manually installed can be freely changed. Do note that when you attempt to update them, your local changes will be overwritten.
|
||||
Libraries you manually installed can be freely changed. Do note that when you attempt to update them, your local changes may be overwritten.
|
||||
|
||||
The [[^Library/Std]] library comes “baked in” with SilverBullet and is read only. You cannot change it. However, for most things there are ways to override or disable standard behavior, check [[Space Lua#Load order]] for some hints.
|
||||
|
||||
|
||||
@@ -1,29 +1,30 @@
|
||||
To develop your own SilverBullet library follow these steps:
|
||||
|
||||
# Write the code
|
||||
Put all functionality you like in a [[Meta Pages|Meta Page]] somewhere under `Library/`. For namespacing purposes it’s good form to put your (Github) username in the path as well, so create, for instance `Library/myuser/My Library`.
|
||||
# Decorate your library with frontmatter
|
||||
Put all functionality you like in a [[Meta Pages|Meta Page]] somewhere under `Library/`. For name spacing purposes it’s good form to put your (Github) username in the path as well, so create, for instance `Library/myuser/My Library`.
|
||||
|
||||
A library can contain, for instance:
|
||||
* [[Space Lua]]
|
||||
* [[Space Style]]
|
||||
Then, decorate your library page with some [[Frontmatter]]. Here is an minimal example library that defines a new “Hello world” command:
|
||||
|
||||
However, you can also include
|
||||
* [[Page Templates]]
|
||||
* [[Slash Commands]]
|
||||
|
||||
# Frontmatter
|
||||
Decorate your library page with some [[Frontmatter]], at the very least:
|
||||
```
|
||||
---
|
||||
name: Library/myuser/My Library
|
||||
tags: meta/library
|
||||
---
|
||||
```
|
||||
---
|
||||
name: Library/myuser/My Library
|
||||
tags: meta/library
|
||||
---
|
||||
This implements my super awesome hello world library!
|
||||
|
||||
```space-lua
|
||||
command.define {
|
||||
name = "Hello world",
|
||||
run = function()
|
||||
editor.flashNotification "Hello world!"
|
||||
end
|
||||
}
|
||||
```
|
||||
|
||||
> **note** Important
|
||||
> The `name` key _has_ to match your page’s full (path) name. Otherwise a validation error will appear on the frontmatter. When another user installs your library, they will install it to the location specified here.
|
||||
|
||||
If you want to distribute additional pages or files with the library (such as `.plug.js` files) make sure that they are kept at the same folder level as your library page. For instance if your library page is `Library/myuser/My Library` you can have a `Library/myuser/myplug.plug.js` and then mark it for distribution by adding it to the `files` key in your frontmatter, e.g.
|
||||
If you want to distribute additional pages or files with the library (such as `.plug.js` files) make sure that they are kept at the same folder level as your library page. For instance if your library page is `Library/myuser/My Library` you can have a `Library/myuser/myplug.plug.js` and then mark it for distribution by adding it to the `files` key in your frontmatter, e.g.:
|
||||
|
||||
```
|
||||
---
|
||||
name: Library/myuser/My Library
|
||||
@@ -34,11 +35,11 @@ files:
|
||||
```
|
||||
|
||||
# Share the library
|
||||
At this stage you can put your library file anywhere you like with a URL. However, it’s easiest to leverage [[Share]] support for publishing.
|
||||
At this stage you can put your library file anywhere you like with a URL. However, for convenience, it’s good to use [[Share]] support for publishing.
|
||||
|
||||
For the purposes of this example, let’s use Github. Create a [[^Library/Std/Infrastructure/Github]] token and configure it as specified in the [[^Library/Std/Infrastructure/Github#Configuration|instructions]].
|
||||
|
||||
[[^Library/Std/Infrastructure/Github]] share support offers two options: Gists and Github repo files. We recommend using a Github repo.
|
||||
[[^Library/Std/Infrastructure/Github]] share support offers two options: Gists and Github repo files. Let’s use a Github repo.
|
||||
|
||||
[Create a new github repo](https://github.com/new), you can name it something like `silverbullet-libraries`.
|
||||
|
||||
@@ -50,7 +51,7 @@ In your library to be shared, run the ${widgets.commandButton "Share: Page"} com
|
||||
|
||||
If all went well, an initial version of your page should now be uploaded to github, check your repo page.
|
||||
|
||||
You’ll notice that a few [[Share]] related frontmatter keys were set in your local copy (but not in the remote version). You can now make further changes to your page and run the ${widgets.commandButton "Share: Page"} command again (Cmd-p or Ctrl-p by default) and after entering another commit message your page will be pushed again. This is how you publish new version for other people to use.
|
||||
You’ll notice that a few [[Share]] related frontmatter keys were set in your local copy. You can now make further changes to your library and run the ${widgets.commandButton "Share: Page"} command again. After entering another commit message your page will be pushed again. This is how you publish new versions of your library for other people to use.
|
||||
|
||||
If you used `files` to include additional assets, you have to commit those to the repository through other means.
|
||||
|
||||
@@ -59,30 +60,37 @@ Your library is now ready to install, you can test this by running ${widgets.com
|
||||
You can now [broadcast that your library is ready to install](https://community.silverbullet.md/c/plugs-libraries/14)!
|
||||
|
||||
# Create a repository
|
||||
If you develop a few libraries, it may be good to make them more discoverable. To do so, you can group them in a [[Repositories|Repository]] (not to be confused with a Github repository).
|
||||
If you develop a few libraries, it may be good to make them more discoverable. To do so, you can group them in a [[Repositories|Repository]].
|
||||
|
||||
For this, create another page, this time under `Repository/`, e.g. `Repository/myuser` and tag it with `#meta/repository`. In the page body, put a list of all your libraries, encoded as [[Objects#data|data objects]] as follows.
|
||||
For this, create another page in your space, this time under `Repository/`, e.g. `Repository/myuser` and tag it with `#meta/repository`.
|
||||
|
||||
~~~
|
||||
```#meta/library/remote
|
||||
name: Library1
|
||||
description: This is my first awesome library
|
||||
website: http://url.com/to/docs
|
||||
uri: github:myuser/silverbullet-libraries/Library1.md
|
||||
---
|
||||
name: Library2
|
||||
description: This is my second awesome library
|
||||
uri: github:myuser/silverbullet-libraries/Library2.md
|
||||
```
|
||||
~~~
|
||||
In the page body, put a list of all your libraries, encoded as [[Objects#data|data objects]] as follows:
|
||||
|
||||
---
|
||||
tags: meta/repository
|
||||
---
|
||||
This is my curated list of awesome libraries!
|
||||
|
||||
```#meta/library/remote
|
||||
name: Library1
|
||||
description: This is my first awesome library
|
||||
website: http://url.com/to/docs
|
||||
uri: https://github.com/myuser/silverbullet-libraries/blob/main/Library1.md
|
||||
---
|
||||
name: Library2
|
||||
description: This is my second awesome library
|
||||
uri: https://github.com/myuser/silverbullet-libraries/blob/main/Library2.md
|
||||
```
|
||||
|
||||
Required keys are:
|
||||
* `name`: a descriptive name of your library. **Note**: this name is _not_ used as an installation location, the installation location is determined by the `name` key in the library itself.
|
||||
* `name`: a descriptive name of your library.
|
||||
**Note**: this name is _not_ used as an installation location, the installation location is determined by the `name` key in the library itself.
|
||||
* `uri`: The URI to install the library from.
|
||||
|
||||
Additional recommended keys are:
|
||||
* `description`: a more elaborate description of the library and its functionality
|
||||
* `author`: who developed this library
|
||||
* `website`: a website URL for more information
|
||||
|
||||
Now share this repo page using [[Share]] to the same github repo (or any other, it doesn’t really matter), and call it `REPO.md` (by convention).
|
||||
|
||||
|
||||
@@ -1,5 +1,4 @@
|
||||
> **note** Note
|
||||
> This page contains sections that apply to the current _edge_ release, it is not part of an official release yet.
|
||||
#maturity/beta
|
||||
|
||||
The library manager makes it easy to manage (install, update, remove) [[Libraries]].
|
||||
|
||||
|
||||
@@ -1,3 +0,0 @@
|
||||
#meta/template/slash
|
||||
> **warning** Beta feature
|
||||
> This is a **beta** feature. Feel free to use it, but it may change (significantly) in the future or potentially replaced.
|
||||
@@ -1,4 +0,0 @@
|
||||
#meta/template/slash
|
||||
> **note** Note
|
||||
> This page contains sections that apply to the current _edge_ release, it is not part of an official release yet.
|
||||
|
||||
@@ -0,0 +1,39 @@
|
||||
#meta
|
||||
|
||||
Some silverbullet.md specific widgets etc.
|
||||
|
||||
```space-lua
|
||||
event.listen {
|
||||
name = "hooks:renderTopWidgets",
|
||||
run = function(e)
|
||||
local meta = editor.getCurrentPageMeta()
|
||||
if not meta then
|
||||
return
|
||||
end
|
||||
local maturityTag = nil
|
||||
for _, tagName in ipairs(meta.tags) do
|
||||
if tagName:startsWith("maturity/") then
|
||||
maturityTag = tagName
|
||||
end
|
||||
end
|
||||
if maturityTag then
|
||||
return widget.new {
|
||||
markdown = spacelua.interpolate([==[
|
||||
**Note:** This is a #${maturityTag} feature. Feel free to use it, but it may change (significantly) in the future or potentially be replaced.
|
||||
]==], {maturityTag=maturityTag}),
|
||||
cssClasses = {"website-warning"},
|
||||
display = "block"
|
||||
}
|
||||
end
|
||||
end
|
||||
}
|
||||
```
|
||||
|
||||
```space-style
|
||||
.website-warning {
|
||||
background-color: #fff1d8;
|
||||
padding: 10px;
|
||||
margin: 0px !important;
|
||||
}
|
||||
```
|
||||
|
||||
@@ -1,8 +1,4 @@
|
||||
> **note** Note
|
||||
> This page contains sections that apply to the current _edge_ release, it is not part of an official release yet.
|
||||
|
||||
> **warning** Beta feature
|
||||
> This is a **beta** feature. Feel free to use it, but it may change (significantly) in the future or potentially replaced.
|
||||
#maturity/beta
|
||||
|
||||
Repositories are a collection of _pointers_ to [[Libraries]] to install. Their purpose is to offer a curated list of libraries to install.
|
||||
|
||||
|
||||
+8
-9
@@ -1,16 +1,12 @@
|
||||
> **note** Note
|
||||
> This page contains sections that apply to the current _edge_ release, it is not part of an official release yet.
|
||||
#maturity/beta
|
||||
|
||||
> **warning** Beta feature
|
||||
> This is a **beta** feature. Feel free to use it, but it may change (significantly) in the future or potentially replaced.
|
||||
SilverBullet is aimed for single-user, private use. Nevertheless, many have the need to _share_ some content kept in SilverBullet with the outside world: to push content out, pull it in, or even sync between different locations. This is where SilverBullet _share_ functionality comes in.
|
||||
|
||||
SilverBullet is aimed for single-user, private use. Nevertheless, many have the need to _share_ some content kept in SilverBullet with the outside world, to pull that content in, or even sync between different locations. This is where SilverBullet _share_ functionality comes in.
|
||||
|
||||
If you are interested in exporting content into another tool one time only, have a look at [[Export]].
|
||||
**Note:** If you are interested in one-off ways to get content out, have a look at [[Export]].
|
||||
|
||||
# Modes
|
||||
Sharing may be desirable in different directions:
|
||||
* _Push_: produce content in SilverBullet, then send it externally and be able to keep the external place up to date with changes, keeping SilverBullet as the source of truth. Example use cases:
|
||||
* _Push_: produce content in SilverBullet, then push it to some external location, while being able to keep the external place up to date with changes, keeping SilverBullet as the source of truth. Example use cases:
|
||||
* Blog posts
|
||||
* Social network posts
|
||||
* [[Libraries]] you want to distribute to others
|
||||
@@ -26,7 +22,10 @@ SilverBullet has [[^Library/Std/Infrastructure/Share|infrastructural support]] t
|
||||
* `share.mode`: specifies the _mode_ this sharing should happen, options are: `push`, `pull` or `sync`
|
||||
* `share.hash`: automatically calculated and updated content hash of your local version to detect whether local changes were made since the last share operation.
|
||||
|
||||
Performing a share operation (in whatever mode) is triggered with the ${widgets.commandButton "Share: Page"} (bound to `Cmd-p`/`Ctrl-p` by default) command on each page individually. However for certain cases, larger batches of pages may be shared together (for instance when using the “update all” in the [[Library Manager]]).
|
||||
# Workflow
|
||||
On the page you’re interested to share, run the ${widgets.commandButton "Share: Page"} (bound to `Cmd-p`/`Ctrl-p` by default) command. This will pop up a list of enabled “Share providers”. Pick one and follow the provider-specific setup steps. At the end, your page will be shared and the `share.*` frontmatter keys automatically set.
|
||||
|
||||
Subsequent shares can be done simply by running the `Share: Page` command again.
|
||||
|
||||
# Support
|
||||
Out of the box, sharing is supported for:
|
||||
|
||||
@@ -36,7 +36,7 @@ ${template.each(query[[
|
||||
limit 5
|
||||
]], templates.pageItem)}
|
||||
|
||||
## Todo items
|
||||
## To do items
|
||||
Maybe you want to collect all [[Tasks]] that you have not yet completed from across your space? No problem:
|
||||
${template.each(query[[
|
||||
from index.tag "task"
|
||||
@@ -53,7 +53,7 @@ ${embed.youtube "https://www.youtube.com/watch?v=mik1EbTshX4"}
|
||||
Want to see even more? Here is a whole [playlist with instruction videos](https://www.youtube.com/watch?v=bb1USz_cEBY&list=PLxFAb_vXRcEp4465MVI6Ha9wzNiX5VevQ) that go more in depth.
|
||||
|
||||
# Installing
|
||||
As mentioned, SilverBullet is a [[Self Hosted]] web application. You need to install it on a server. Perhaps you do this on a Raspberry Pi you didn’t have a use for, or a VPS somewhere in the cloud. SilverBullet is distributed as a single self-contained server [[Install/Binary]] or [[Install/Docker]] container.
|
||||
As mentioned, SilverBullet is a [[Self Hosted]] web application. This is great if you care about [[Data Sovereignty]], but it does mean you need to install it on a server yourself. Perhaps you do this on a Raspberry Pi you didn’t have a use for, or a VPS somewhere in the cloud. SilverBullet is distributed as a single self-contained server [[Install/Binary]] or [[Install/Docker]] container.
|
||||
|
||||
While this is a bit more complicated to set up than simply downloading desktop app or signing up for an account with some online service, self hosting is a path to both [[Data Sovereignty]] and to access your content from any device with a modern [[Browser]].
|
||||
|
||||
|
||||
Reference in New Issue
Block a user