pull/561/head 0.5.4
Zef Hemel 2023-11-11 14:28:46 +01:00
parent c92502b5c2
commit 51e3dd72e8
14 changed files with 99 additions and 39 deletions

View File

@ -65,6 +65,12 @@ export const builtins: Record<string, Record<string, string>> = {
page: "string",
pos: "number",
},
template: {
ref: "string",
page: "string",
pos: "number",
trigger: "string",
},
};
export async function loadBuiltinsIntoIndex() {

View File

@ -1 +1 @@
export const version = "0.5.3";
export const version = "0.5.4";

View File

@ -2,7 +2,10 @@ An attempt at documenting the changes/new features introduced in each
release.
---
## Next
## 0.5.4
* Were 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]]:

View File

@ -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 well 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]].

View File

@ -8,3 +8,5 @@ The [[🔌 Editor]] plug provides a few helpful ones:
* `/snippet` see [[🔌 Template@snippets]]
* `/today` to insert todays date
* `/tomorrow` to insert tomorrows date
You can create custom slash commands using [[Slash Templates]].

View File

@ -0,0 +1,42 @@
Slash templates allow you to define custom [[Slash Commands]] that expand “snippet style” templates inline. Theyre 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. Thats it.
## Frontmatter
A templates [[Frontmatter]] is interpreted by SilverBullets 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
.

View File

@ -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. Its 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 spaces 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}}`: Todays date in the usual YYYY-MM-DD format
- `{{tomorrow}}`: Tomorrows date in the usual YYY-MM-DD format

View File

@ -1,3 +1,4 @@
#template
{{#each .}}
{{@key}}: {{.}}
{{/each}}

View File

@ -1,3 +1,4 @@
#template
| Name | Age |
|----------|----------|
{{#each .}}

View File

@ -1 +1,2 @@
#template
* [[{{name}}]] {{#if author}}by **{{author}}** ([repo]({{repo}})){{/if}}

View File

@ -1,7 +1,4 @@
---
$disableDirectives: true
---
<!-- #query task where tags = "{{.}}" and done = false render [[template/task]] -->
<!-- /query -->
#template
```query
task where tags = "{{.}}" and done = false render [[template/task]]
```

View File

@ -1 +1,2 @@
#template
* [{{state}}] [[{{ref}}]] {{name}}

View File

@ -1 +0,0 @@
Today is {{today}}!

View File

@ -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 doesnt 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 todays date
* `/tomorrow`: insert tomorrows date
### Template helpers
$vars
Currently supported (hardcoded in the code):
- `{{today}}`: Todays date in the usual YYYY-MM-DD format
- `{{tomorrow}}`: Tomorrows date in the usual YYY-MM-DD format
- `{{yesterday}}`: Yesterdays 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}}`