From 51e3dd72e8dd2d3b5b4500fb34192f911abc1498 Mon Sep 17 00:00:00 2001 From: Zef Hemel Date: Sat, 11 Nov 2023 14:28:46 +0100 Subject: [PATCH] 0.5.4 --- plugs/index/builtins.ts | 6 +++++ version.ts | 2 +- website/CHANGELOG.md | 5 +++- website/Objects.md | 9 +++++++ website/Slash Commands.md | 2 ++ website/Slash Templates.md | 42 ++++++++++++++++++++++++++++++++ website/Templates.md | 31 ++++++++++++++--------- website/template/debug.md | 1 + website/template/people.md | 1 + website/template/plug.md | 1 + website/template/tagged-tasks.md | 11 +++------ website/template/task.md | 1 + website/template/today.md | 1 - website/🔌 Template.md | 25 ++++++------------- 14 files changed, 99 insertions(+), 39 deletions(-) create mode 100644 website/Slash Templates.md delete mode 100644 website/template/today.md diff --git a/plugs/index/builtins.ts b/plugs/index/builtins.ts index 1f217d97..71907a47 100644 --- a/plugs/index/builtins.ts +++ b/plugs/index/builtins.ts @@ -65,6 +65,12 @@ export const builtins: Record> = { page: "string", pos: "number", }, + template: { + ref: "string", + page: "string", + pos: "number", + trigger: "string", + }, }; export async function loadBuiltinsIntoIndex() { diff --git a/version.ts b/version.ts index de4a1b8f..f4187f2d 100644 --- a/version.ts +++ b/version.ts @@ -1 +1 @@ -export const version = "0.5.3"; +export const version = "0.5.4"; diff --git a/website/CHANGELOG.md b/website/CHANGELOG.md index 275f63fb..bafa3a95 100644 --- a/website/CHANGELOG.md +++ b/website/CHANGELOG.md @@ -2,7 +2,10 @@ An attempt at documenting the changes/new features introduced in each release. --- -## Next +## 0.5.4 +* We’re on a journey to rethink [[Templates]]: + * It is now _recommended_ you tag all your templates with a `#template` tag, this will exclude them from [[Objects]] indexing and may in the future be used to do better template name completion (but not yet). + * New feature: Introducing [[Slash Templates]], allowing you to create custom [[Slash Commands]]. This deprecates snippets and page templates, because [[Slash Templates]] are awesomer. * Many styling fixes and improvements to [[Live Queries]] and [[Live Templates]] * Added a “source” button to [[Live Queries]] and [[Live Templates]] for better debugging (showing you the markdown code rendered by the template so you can more easily detect issues) * [[Live Queries]]: diff --git a/website/Objects.md b/website/Objects.md index 2586059d..07b5010c 100644 --- a/website/Objects.md +++ b/website/Objects.md @@ -66,6 +66,15 @@ And can be queried as follows: 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. + +```query +template +``` + + ## item $item List items (both bullet point and numbered items) are indexed by default with the `item` tag, and additional tags can be added using [[Tags]]. diff --git a/website/Slash Commands.md b/website/Slash Commands.md index fd0792a0..1cb4d4bd 100644 --- a/website/Slash Commands.md +++ b/website/Slash Commands.md @@ -8,3 +8,5 @@ The [[🔌 Editor]] plug provides a few helpful ones: * `/snippet` see [[🔌 Template@snippets]] * `/today` to insert today’s date * `/tomorrow` to insert tomorrow’s date + +You can create custom slash commands using [[Slash Templates]]. diff --git a/website/Slash Templates.md b/website/Slash Templates.md new file mode 100644 index 00000000..088ad36a --- /dev/null +++ b/website/Slash Templates.md @@ -0,0 +1,42 @@ +Slash templates allow you to define custom [[Slash Commands]] that expand “snippet style” templates inline. They’re like [[🔌 Template$snippets]], but appear immediately as slash commands. + +## Definition +You can define a slash template by creating a [[Templates|template page]] with a template tag and `trigger` attribute. + +Example: + + --- + tags: template + trigger: meeting-notes + --- + ## Meeting notes for {{today}}! + + |^| + +## Use +You can _trigger_ the slash template by typing `/meeting-notes` in any page. That’s it. + +## Frontmatter +A template’s [[Frontmatter]] is interpreted by SilverBullet’s template engine and removed when instantiated. However, to still include frontmatter after instantiation, you can use the `frontmatter` attribute. + +Example: + + --- + tags: template + trigger: meeting-notes + frontmatter: | + date: {{today}} + --- + ## Meeting notes for {{today}}! + + |^| + +Which will expand into e.g. + + --- + date: 2023-11-11 + --- + ## Meeting notes for 2023-11-11 + + . + diff --git a/website/Templates.md b/website/Templates.md index 6ff87a4e..ac8a833d 100644 --- a/website/Templates.md +++ b/website/Templates.md @@ -1,17 +1,26 @@ -For various use cases, SilverBullet uses [Handlebars templates](https://handlebarsjs.com/). +Templates are _reusable_ pieces of markdown content, usually with placeholders that are replaced once instantiated. -Generally templates are stored in your space as regular pages, which allows for reuse. Some examples include [[template/task]] and [[template/page]]. -As a convention, we often name templates with a `template/` prefix, although this is purely a convention. +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]] + +## 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. + +Tagging a page with a `#template` tag (either in the [[Frontmatter]] or using a [[Tags]] at the very beginning of the page content) does two things: + +1. It excludes the page from being indexed for [[Objects]], that is: any tasks, items, paragraphs etc. will not appear in your space’s object database. Which is usually what you want. +2. It allows you to register your templates to be used as [[Slash Templates]]. + +Templates consist of markdown, but can also include [Handlebars syntax](https://handlebarsjs.com/), such as `{{today}}`, and `{{#each .}}`. + +In addition the special `|^|` marker can be used to specify the desired cursor position after the template is included (relevant mostly to [[Slash Templates]]). -[[Live Templates]] allow templates to be defined inline, for instance: -```template -template: | - Hello, {{name}}! Today is _{{today}}_ -value: - name: Pete -``` ### Template helpers -There are a number of built-in handlebars helpers you can use +There are a number of built-in handlebars helpers you can use: - `{{today}}`: Today’s date in the usual YYYY-MM-DD format - `{{tomorrow}}`: Tomorrow’s date in the usual YYY-MM-DD format diff --git a/website/template/debug.md b/website/template/debug.md index 45b06d65..0ebdc940 100644 --- a/website/template/debug.md +++ b/website/template/debug.md @@ -1,3 +1,4 @@ +#template {{#each .}} {{@key}}: {{.}} {{/each}} diff --git a/website/template/people.md b/website/template/people.md index 046643c4..7b4c0993 100644 --- a/website/template/people.md +++ b/website/template/people.md @@ -1,3 +1,4 @@ +#template | Name | Age | |----------|----------| {{#each .}} diff --git a/website/template/plug.md b/website/template/plug.md index fb7813ab..01e2b66b 100644 --- a/website/template/plug.md +++ b/website/template/plug.md @@ -1 +1,2 @@ +#template * [[{{name}}]] {{#if author}}by **{{author}}** ([repo]({{repo}})){{/if}} \ No newline at end of file diff --git a/website/template/tagged-tasks.md b/website/template/tagged-tasks.md index e646dc1b..017eed7d 100644 --- a/website/template/tagged-tasks.md +++ b/website/template/tagged-tasks.md @@ -1,7 +1,4 @@ ---- -$disableDirectives: true ---- - - - - \ No newline at end of file +#template +```query +task where tags = "{{.}}" and done = false render [[template/task]] +``` \ No newline at end of file diff --git a/website/template/task.md b/website/template/task.md index 6d21030e..8afdb28a 100644 --- a/website/template/task.md +++ b/website/template/task.md @@ -1 +1,2 @@ +#template * [{{state}}] [[{{ref}}]] {{name}} \ No newline at end of file diff --git a/website/template/today.md b/website/template/today.md deleted file mode 100644 index 7c97914a..00000000 --- a/website/template/today.md +++ /dev/null @@ -1 +0,0 @@ -Today is {{today}}! \ No newline at end of file diff --git a/website/🔌 Template.md b/website/🔌 Template.md index 1ec7651d..278b4572 100644 --- a/website/🔌 Template.md +++ b/website/🔌 Template.md @@ -3,6 +3,9 @@ The [[🔌 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`. @@ -38,6 +41,9 @@ Will prompt you to pick a page name (defaulting to “📕 “), and then create ### 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. @@ -65,7 +71,7 @@ with a 🗓️ emoji by default, but this is configurable via the `weeklyNotePre 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. -## Slash commands +## Built-in slash commands * `/front-matter`: Insert [[Frontmatter]] * `/h1` - `/h4`: turn the current line into a header * `/code`: insert a fenced code block @@ -74,20 +80,3 @@ The {[Quick Note]} command will navigate to an empty page named with the current * `/page-template`: insert a page template * `/today`: insert today’s date * `/tomorrow`: insert tomorrow’s date - -### Template helpers -$vars -Currently supported (hardcoded in the code): - -- `{{today}}`: Today’s date in the usual YYYY-MM-DD format -- `{{tomorrow}}`: Tomorrow’s date in the usual YYY-MM-DD format -- `{{yesterday}}`: Yesterday’s date in the usual YYY-MM-DD format -- `{{lastWeek}}`: Current date - 7 days -- `{{nextWeek}}`: Current date + 7 days -- `{{escapeRegexp "hello/there"}}` to escape a regexp, useful when injecting e.g. a page name into a query — think `name =~ /{{escapeRegexp @page.name}}/ -`* `{{replaceRegexp string regexp replacement}}`: replace a regular expression in a string, example use: `{{replaceRegexp name "#[^#\d\s\[\]]+\w+" ""}}` to remove hashtags from a task name -- `{{json @page}}` translate any (object) value to JSON, mostly useful for debugging -- `{{substring "my string" 0 3}}` performs a substring operation on the first argument, which in this example would result in `my ` -- `{{prefixLines "my string\nanother" " "}}` prefixes each line (except the first) with the given prefix. -- `{{niceDate @page.lastModified}}` translates any timestamp into a “nice” format (e.g. `2023-06-20`). -- The `@page` variable contains all page meta data (`name`, `lastModified`, `contentType`, as well as any custom [[Frontmatter]] attributes). You can address it like so: `{{@page.name}}`