From 0a7fc05fefef1cc640b539149f9fa169905fe519 Mon Sep 17 00:00:00 2001 From: Zef Hemel Date: Fri, 22 Dec 2023 16:40:38 +0100 Subject: [PATCH] Docs and template sets work --- plugs/editor/complete.ts | 4 +- plugs/template/complete.ts | 2 +- website/CHANGELOG.md | 2 +- website/Federation.md | 8 ++-- website/Keyboard Shortcuts.md | 4 +- website/Manual.md | 7 ++-- website/Markdown/Code Widgets.md | 2 +- website/Objects.md | 12 +++--- website/Spaces.md | 2 +- website/Special Pages.md | 2 +- website/Sync.md | 2 +- website/Template Sets.md | 40 ++++++++++++------- website/template/debug.md | 11 ++++- website/template/debug/debug.md | 12 ------ website/template/documented-template.md | 3 +- .../{maintenance => live}/conflicts.md | 1 + website/template/{tasks => live}/incoming.md | 1 + .../{tasks/tagged.md => live/tagged-tasks.md} | 1 + website/template/page.md | 7 ++++ website/template/page/slash-template.md | 1 + website/template/page/template.md | 3 +- website/template/slash/note-admonition.md | 9 +++++ website/template/slash/table.md | 7 ++++ website/template/slash/warning-admonition.md | 9 +++++ website/template/task.md | 1 + 25 files changed, 99 insertions(+), 54 deletions(-) delete mode 100644 website/template/debug/debug.md rename website/template/{maintenance => live}/conflicts.md (95%) rename website/template/{tasks => live}/incoming.md (97%) rename website/template/{tasks/tagged.md => live/tagged-tasks.md} (95%) create mode 100644 website/template/slash/note-admonition.md create mode 100644 website/template/slash/table.md create mode 100644 website/template/slash/warning-admonition.md diff --git a/plugs/editor/complete.ts b/plugs/editor/complete.ts index cd330cd..04f9c70 100644 --- a/plugs/editor/complete.ts +++ b/plugs/editor/complete.ts @@ -51,7 +51,7 @@ export async function pageComplete(completeEvent: CompleteEvent) { apply: isInTemplateContext ? pageMeta.name : `${pageMeta.name}|${pageMeta.displayName}`, - detail: `displayName: ${pageMeta.name}`, + detail: `displayName for: ${pageMeta.name}`, type: "page", }); } @@ -63,7 +63,7 @@ export async function pageComplete(completeEvent: CompleteEvent) { apply: isInTemplateContext ? pageMeta.name : `${pageMeta.name}|${alias}`, - detail: `alias: ${pageMeta.name}`, + detail: `alias to: ${pageMeta.name}`, type: "page", }); } diff --git a/plugs/template/complete.ts b/plugs/template/complete.ts index 8f5d567..efdf79b 100644 --- a/plugs/template/complete.ts +++ b/plugs/template/complete.ts @@ -52,7 +52,7 @@ export async function templateSlashComplete( ): Promise { const allTemplates = await queryObjects("template", { // Only return templates that have a trigger - filter: ["!=", ["attr", "trigger"], ["null"]], + filter: ["attr", "trigger"], }); return allTemplates.map((template) => ({ label: template.trigger!, diff --git a/website/CHANGELOG.md b/website/CHANGELOG.md index b002469..db73e8b 100644 --- a/website/CHANGELOG.md +++ b/website/CHANGELOG.md @@ -79,7 +79,7 @@ release. * The {[Directive: Convert to Live Query/Template]} now also converts `#use` and `#include` directives * Styling improvements for Linked Mentions * SilverBullet now fully works when added as PWA on Safari 17 (via the “Add to Dock” option). -* Fix support for handlebars variables in [[Live Queries]] and [[live]] +* Fix support for handlebars variables in [[Live Queries]] and [[Live Templates]] * Plug robustness improvements (SB shouldn’t fully break when loading plugs that rely on disabled syscalls) * Various other bug fixes diff --git a/website/Federation.md b/website/Federation.md index 07e93ab..bd82c04 100644 --- a/website/Federation.md +++ b/website/Federation.md @@ -1,10 +1,10 @@ -Federation enables _browsing_, and _synchronizing_ (parts of) spaces outside of the user’s space into your SilverBullet client. +Federation enables _browsing_, and _synchronizing_ (parts of) spaces _outside_ the user’s space into your SilverBullet client. This enables a few things: -* Linking and browsing publicly hosted SilverBullet spaces (or websites adhering to its [[API]]). For instance the [[!silverbullet.md/CHANGELOG|SilverBullet CHANGELOG]] without leaving the comfort of your own SilverBullet client. -* Reusing content from externally hosted sources, such as: - * _Templates_, e.g. by federating with `silverbullet.md/template` will give you access to the example templates hosted there without manually copying and pasting them and automatically pull in the latest version. So you can, for instance, use `render [[!silverbullet.md/template/page]]` to use the [[template/page]] template. +* **Linking and browsing** to other publicly hosted SilverBullet spaces (or websites adhering to its [[API]]). For instance the [[!silverbullet.md/CHANGELOG|SilverBullet CHANGELOG]] without leaving the comfort of your own SilverBullet client. +* **Reusing** content from externally hosted sources, such as: + * _Templates_, e.g. by federating with `silverbullet.md/template` will give you access to the example templates hosted there without manually copying and pasting them and automatically pull in the latest version. So you can, for instance, use `render [[!silverbullet.md/template/page]]` to use the [[template/page]] template. See [[Template Sets]] for more on this use case. * _Data_: such as tasks, item, data hosted elsewhere that you want to query from your own space. **Note:** Federation does not support authentication yet, so all federated spaces need to be unauthenticated and will be _read-only_. diff --git a/website/Keyboard Shortcuts.md b/website/Keyboard Shortcuts.md index d622f3f..d2c145e 100644 --- a/website/Keyboard Shortcuts.md +++ b/website/Keyboard Shortcuts.md @@ -1,4 +1,4 @@ -This page lists some potentially useful keyboard shortcuts. Also have a look at [[Manual/Outlines]] for outline specific keyboard shortcuts. +This page lists some potentially useful keyboard shortcuts. Also have a look at [[Outlines]] for outline specific keyboard shortcuts. # Highlights Particularly useful keyboard shortcuts (that you may not know about). @@ -17,7 +17,7 @@ Particularly useful keyboard shortcuts (that you may not know about). |----------|----------| | Cmd-/ / Ctrl-/ | Run command | | Cmd-k/Ctrl-k | Open page | -| Cmd-Shift-p/Ctrl-Shift-p | Update plugs (from the [[PLUGS]] file) | +| Cmd-Shift-p/Ctrl-Shift-p | Update plugs (from the `PLUGS` file) | | Alt-q | Refresh all live queries and templates on this page | | Cmd-p/Ctrl-p | Toggle markdown preview | | Ctrl-Alt-t | Toggle table of contents| diff --git a/website/Manual.md b/website/Manual.md index 3255e2c..c5da8e1 100644 --- a/website/Manual.md +++ b/website/Manual.md @@ -53,14 +53,13 @@ The main ways to roam your space, beside following page links, are: * [[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. +# Advanced topics * [[Objects]] * [[Frontmatter]] * [[Attributes]] -* [[Templates]] * [[Live Queries]] -* [[Live Templates]] +* [[Templates]] and [[Live Templates]] +* [[Federation]]: it possibly to “sync in” content from outside sources, such as [[Template Sets]] # 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]]. diff --git a/website/Markdown/Code Widgets.md b/website/Markdown/Code Widgets.md index 40d491b..6dcf957 100644 --- a/website/Markdown/Code Widgets.md +++ b/website/Markdown/Code Widgets.md @@ -1,6 +1,6 @@ Code widgets are a SilverBullet-specific “extension” to [[Markdown]]. Technically, it’s not an extension — it just gives new meaning to markdown’s native fenced code blocks — code blocks that start with a triple backtick, specifying a programming language. -Currently, SilverBullet provides two code widgets as part of its built-in [[🔌 Plugs]]: +Currently, SilverBullet provides two code widgets as part of its built-in [[Plugs]]: * `embed` * `markdown` diff --git a/website/Objects.md b/website/Objects.md index 154088a..b7c52fd 100644 --- a/website/Objects.md +++ b/website/Objects.md @@ -15,13 +15,13 @@ Every object has a set of [[Attributes]]. At the very least: * `ref`: a unique _identifier_ (unique to the page, at least), often represented as a pointer to the place (page, position) in your space where the object is defined. For instance, a _page_ object will use the page name as its `ref` attribute, and a `task` will use `page@pos` (where `pos` is the location the task appears in `page`). -* `tags`: an array of type(s) of an object, see [[@tags]]. +* `tags`: an array of type(s) of an object, see [[$tags]]. In addition, any number of additional tag-specific and custom [[Attributes]] can be defined (see below). # Tags $tags -Every object has one or more tags, defining the types of an object. Some tags are built-in (as described below), but you can easily define new tags by simply using the #hashtag notation in strategic locations (more on these locations later). +Every object has one or more tags, defining the _types_ of an object. Some tags are built-in (as described below), but you can easily define new tags by simply using the #hashtag notation in strategic locations (more on these locations later). Here are the currently built-in tags: @@ -48,7 +48,7 @@ The following query shows all attributes available for tasks: ```query upnext ``` -Although you may want to render it using a template such as [[template/tasks/task] instead: +Although you may want to render it using a template such as [[template/task]] instead: ```query upnext render [[template/task]] @@ -68,10 +68,10 @@ taskstate where page = "{{@page.name}}" ## template $template -Indexes all pages tagged with `#template`. Technically this is not a built-in, but we’ll list it here anyway. See [[Templates]] for more information on templates. +Indexes all pages tagged with `#template`. See [[Templates]] for more information on templates. ```query -template +template select name ``` @@ -149,7 +149,7 @@ The ultimate meta tag is _tag_ itself, which indexes for all tags used, in which Here are the tags used/defined in this page: ```query -tag where page = "{{@page.name}}" +tag where page = "{{@page.name}}" select name, parent ``` ## attribute diff --git a/website/Spaces.md b/website/Spaces.md index 685108f..fd3fd8b 100644 --- a/website/Spaces.md +++ b/website/Spaces.md @@ -8,5 +8,5 @@ A space consists of * [[Attachments]] # Folder lay-out -Every space in SilverBullet at the very least has an index page (by default named `index.md`) and a [[SETTINGS]] page (named `SETTINGS.md`). If you install custom [[🔌 Plugs]], these will be kept under `_plug` in your space’s folder. +Every space in SilverBullet at the very least has an index page (by default named `index.md`) and a [[SETTINGS]] page (named `SETTINGS.md`). If you install custom [[Plugs]], these will be kept under `_plug` in your space’s folder. diff --git a/website/Special Pages.md b/website/Special Pages.md index 7a1686f..057db3f 100644 --- a/website/Special Pages.md +++ b/website/Special Pages.md @@ -5,5 +5,5 @@ All special pages except [[SETTINGS]] are optional: if they don’t exist, well, Here are the current list of “special pages” known to humankind: * [[SETTINGS]] for setting various settings -* [[PLUGS]] as a source for the plug manager to decide what plugs to load and where from +* `PLUGS` as a source for the plug manager to decide what plugs to load and where from * [[VIMRC]] for tweaking [[Vim]] mode diff --git a/website/Sync.md b/website/Sync.md index 4844356..df74c84 100644 --- a/website/Sync.md +++ b/website/Sync.md @@ -1,4 +1,4 @@ -The SilverBullet CLI has a `sync` command that can be used to synchronize local as well as remote [[Space|spaces]]. This can be useful when migrating between different [[Install/Configuration$storage|storage implementations]]. It can also be used to back up content elsewhere. Under the hood, this sync mechanism uses the exact same sync engine used for the Sync [[Client Modes]]. +The SilverBullet CLI has a `sync` command that can be used to synchronize local as well as remote [[Spaces]]. This can be useful when migrating between different [[Install/Configuration$storage|storage implementations]]. It can also be used to back up content elsewhere. Under the hood, this sync mechanism uses the exact same sync engine used for the Sync [[Client Modes]]. # Use cases * **Migration**: you hosted SilverBullet on your local device until now, but have since set up an instance via [[Install/Deno Deploy]] and want to migrate your content there. diff --git a/website/Template Sets.md b/website/Template Sets.md index c7b6c63..bf84381 100644 --- a/website/Template Sets.md +++ b/website/Template Sets.md @@ -15,32 +15,42 @@ federate: If you don’t want to sync _all_ these templates, you can use more specific URIs, e.g. ```yaml federate: -- uri: silverbullet.md/template/task +- uri: silverbullet.md/template/page/ ``` -to just get the `task` stuff. +to just get the page templates, for instance. -To reference a template, use the federation syntax, e.g. `[[!silverbullet.md/template/task]]`. +To reference a template, use the [[Federation]] syntax, e.g. `[[!silverbullet.md/template/task]]`. + +# Page Templates +Use these [[Page Templates]] with the {[Page: From Template]} command. -## Maintenance ```query -template where name =~ /^template\/maintenance/ -order by order -render [[template/documented-template]] +template where type = "page" render [[template/documented-template]] ``` -## Pages + +# Slash Templates +These can be used as [[Slash Templates]]: + +```query +template where type = "slash" render [[template/documented-template]] +``` + +# Live Templates +Use these as `page` in [[Live Templates]]. + ```query template -where name =~ /^template\/pages/ +where type = "live" order by order render [[template/documented-template]] ``` -## Tasks + +# Live Query +Use these in your `render` clauses in [[Live Queries]]. + ```query -template where name =~ /^template\/task/ +template +where type = "query" order by order render [[template/documented-template]] ``` -## Debugging -```query -template where name =~ /^template\/debug/ render [[template/documented-template]] -``` diff --git a/website/template/debug.md b/website/template/debug.md index 0ebdc94..87a91d1 100644 --- a/website/template/debug.md +++ b/website/template/debug.md @@ -1,5 +1,14 @@ -#template +--- +tags: template +type: query +order: 100 +description: | + Renders its object value in a `key: value` format +usage: | + Can be used by passing in a YAML object in a template via `value` or in a `render` clause of a query +--- {{#each .}} {{@key}}: {{.}} {{/each}} + --- \ No newline at end of file diff --git a/website/template/debug/debug.md b/website/template/debug/debug.md deleted file mode 100644 index f141a4b..0000000 --- a/website/template/debug/debug.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -tags: template -description: | - Renders its object value in a `key: value` format -usage: | - Can be used by passing in a YAML object in a template via `value` or in a `render` clause of a query ---- -{{#each .}} -{{@key}}: {{.}} -{{/each}} - ---- \ No newline at end of file diff --git a/website/template/documented-template.md b/website/template/documented-template.md index c4196af..7e67f1f 100644 --- a/website/template/documented-template.md +++ b/website/template/documented-template.md @@ -1,4 +1,5 @@ -* [[{{ref}}|{{ref}}]] {{description}} +#template +* [[{{ref}}|{{#if displayName}}{{displayName}}{{else}}{{ref}}{{/if}}]] {{description}} {{#if usage}} * **Usage:** {{usage}} {{/if}} \ No newline at end of file diff --git a/website/template/maintenance/conflicts.md b/website/template/live/conflicts.md similarity index 95% rename from website/template/maintenance/conflicts.md rename to website/template/live/conflicts.md index 476b45a..88432c6 100644 --- a/website/template/maintenance/conflicts.md +++ b/website/template/live/conflicts.md @@ -1,5 +1,6 @@ --- tags: template +type: live description: Lists all pages with ".conflicted" in the name, created as a result of a synchronization conflict. --- diff --git a/website/template/tasks/incoming.md b/website/template/live/incoming.md similarity index 97% rename from website/template/tasks/incoming.md rename to website/template/live/incoming.md index 95056fd..0dae1b5 100644 --- a/website/template/tasks/incoming.md +++ b/website/template/live/incoming.md @@ -1,5 +1,6 @@ --- tags: template +type: live description: | Shows all tasks that reference (tag) the current page. For instance a task that references `[[John]]` in its name, would appear on the `John` page if it would use this [[sets/tasks/incoming]] template. order: 2 diff --git a/website/template/tasks/tagged.md b/website/template/live/tagged-tasks.md similarity index 95% rename from website/template/tasks/tagged.md rename to website/template/live/tagged-tasks.md index eb5727f..a3b27d4 100644 --- a/website/template/tasks/tagged.md +++ b/website/template/live/tagged-tasks.md @@ -1,5 +1,6 @@ --- tags: template +type: live description: Queries all tasks tagged with a specific tag. usage: Pass in the tag to filter on as the `value` of this template order: 2 diff --git a/website/template/page.md b/website/template/page.md index b2751bb..6770f4f 100644 --- a/website/template/page.md +++ b/website/template/page.md @@ -1 +1,8 @@ +--- +tags: template +type: query +order: 1 +description: A page reference link as a list item +--- + * [[{{name}}]] \ No newline at end of file diff --git a/website/template/page/slash-template.md b/website/template/page/slash-template.md index eb1033b..4f2aee5 100644 --- a/website/template/page/slash-template.md +++ b/website/template/page/slash-template.md @@ -3,6 +3,7 @@ tags: template type: page displayName: Slash Template pageName: "template/slash/" +description: Define a new Slash Template frontmatter: tags: template trigger: "|^|" diff --git a/website/template/page/template.md b/website/template/page/template.md index 092ada2..c8019e0 100644 --- a/website/template/page/template.md +++ b/website/template/page/template.md @@ -3,8 +3,9 @@ tags: template type: page displayName: Page Template pageName: "template/page/" +description: Define a new Page Template frontmatter: tags: template + displayName: "|^|" type: page --- -|^| \ No newline at end of file diff --git a/website/template/slash/note-admonition.md b/website/template/slash/note-admonition.md new file mode 100644 index 0000000..52a46d8 --- /dev/null +++ b/website/template/slash/note-admonition.md @@ -0,0 +1,9 @@ +--- +tags: template +type: slash +trigger: "note-admonition" +displayName: "/note-admonition" +description: Insert a "note" admonition +--- +> **note** Note +> |^| diff --git a/website/template/slash/table.md b/website/template/slash/table.md new file mode 100644 index 0000000..dfb6bda --- /dev/null +++ b/website/template/slash/table.md @@ -0,0 +1,7 @@ +--- +tags: template +trigger: "table" +--- +| Header A | Header B | +|----------|----------| +| |^| | Cell B | diff --git a/website/template/slash/warning-admonition.md b/website/template/slash/warning-admonition.md new file mode 100644 index 0000000..f69e5e7 --- /dev/null +++ b/website/template/slash/warning-admonition.md @@ -0,0 +1,9 @@ +--- +tags: template +type: slash +trigger: "warning-admonition" +displayName: "/warning-admonition" +description: Insert a "warning" admonition +--- +> **warning** Warning +> |^| diff --git a/website/template/task.md b/website/template/task.md index 46dfc5c..45e19f3 100644 --- a/website/template/task.md +++ b/website/template/task.md @@ -1,5 +1,6 @@ --- tags: template +type: query description: generic task template that supports updating the status back in the origin page order: 1 ---