Work on #587: revamped templates
This commit is contained in:
Zef Hemel
@@ -15,9 +15,12 @@ Here is an example:
|
||||
## This is a section
|
||||
This is content
|
||||
|
||||
SilverBullet allows arbitrary metadata to be added to pages this way, with two exceptions:
|
||||
# Special attributes
|
||||
While SilverBullet allows arbitrary metadata to be added to pages, there are a few attributes with special meaning:
|
||||
|
||||
* `name` is an attribute used for page names, so don’t attempt to override it in frontmatter
|
||||
* `tags` can be specified (as in the example) and are, in effect, another way of adding tags to your page. You can achieve the same result by simply adding hashtags in the body of your document, e.g. `#tag1 #tag2`.
|
||||
* `name` (==DISALLOWED==): is an attribute used for page names, _you should not set it_.
|
||||
* `displayName` (`string`): very similar in effect as `aliases` but will use this name for the page in certain contexts.
|
||||
* `aliases` (`array of strings`): allow you to specify a list of alternative names for this page, which can be used to navigate or link to this page
|
||||
* `tags` (`array of strings` or `string`): an alternative (and perhaps preferred) way to assign [[Tags]] to a page. In principle you specify them as a list of strings, but for convenience you can also specify them as (possibly comma-separated) string, e.g. `tags: tag1, tag2, tag3`
|
||||
|
||||
SilverBullet also has the _convention_ of using attributes starting with a `$` for internal use. For instance, the sharing capability uses the `$share` attribute, and `$disableDirectives: true` has the special meaning of disabling [[🔌 Directive]] processing on a page.
|
||||
In addition, in the context of [[Templates]] frontmatter has a very specific interpretation.
|
||||
@@ -3,29 +3,28 @@ Live templates rendering [[Templates]] inline in a page.
|
||||
## Syntax
|
||||
Live Templates are specified using [[Markdown]]‘s fenced code block notation using `template` as a language. The body of the code block specifies the template to use, as well as any arguments to pass to it.
|
||||
|
||||
Generally you’d use it in one of two ways, either using a `page` template reference, or an inline `template`:
|
||||
Generally you’d use it in one of two ways, either using a `page` [[Templates|template]] reference, or an inline `template`:
|
||||
|
||||
Here’s an example using `page`:
|
||||
|
||||
```template
|
||||
page: "[[template/today]]"
|
||||
```
|
||||
And here’s an example using `template`:
|
||||
|
||||
And here’s an example using `template`:
|
||||
```template
|
||||
template: |
|
||||
Today is {{today}}!
|
||||
```
|
||||
To pass in a value to the template, you can specify the optional `value` attribute:
|
||||
|
||||
To pass in a value to the template, you can specify the optional `value` attribute:
|
||||
```template
|
||||
template: |
|
||||
Hello, {{name}}! Today is _{{today}}_
|
||||
value:
|
||||
name: Pete
|
||||
```
|
||||
If you just want to render the raw markdown without handling it as a handlebars template, set `raw` to true:
|
||||
|
||||
If you just want to render the raw markdown without handling it as a handlebars template, set `raw` to true:
|
||||
```template
|
||||
template: |
|
||||
This is not going to be {{processed}} by Handlebars
|
||||
|
||||
@@ -0,0 +1,26 @@
|
||||
The {[Page: From Template]} command enables you to create a new page based on a page template. A page template is a [[Templates|template]] with the `type` attribute (in [[Frontmatter]]) set to `page`.
|
||||
|
||||
An example:
|
||||
|
||||
---
|
||||
tags: template
|
||||
type: page
|
||||
pageName: "📕 "
|
||||
---
|
||||
# {{@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 2023-08-08) when you pick “📕 Harry Potter” as a page name:
|
||||
|
||||
# 📕 Harry Potter
|
||||
As recorded on 2022-08-08.
|
||||
|
||||
## Introduction
|
||||
## Notes
|
||||
## Conclusions
|
||||
|
||||
As with any [[Templates|template]], the `frontmatter` can be used to define [[Frontmatter]] for the new page.
|
||||
@@ -2,62 +2,6 @@
|
||||
|
||||
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).
|
||||
|
||||
@@ -7,10 +7,6 @@ indexPage: "[[SilverBullet]]"
|
||||
# Load custom CSS styles from the following page, can also be an array
|
||||
customStyles: "[[STYLES]]"
|
||||
|
||||
# Template related settings
|
||||
pageTemplatePrefix: "template/page/"
|
||||
snippetPrefix: "snippet/"
|
||||
|
||||
quickNotePrefix: "📥 "
|
||||
|
||||
dailyNotePrefix: "📅 "
|
||||
|
||||
@@ -33,6 +33,7 @@ Some highlights:
|
||||
* SilverBullet runs in any modern browser (including mobile ones) as a [[PWA]] in two [[Client Modes]] ([[Client Modes$online|online]] and [[Client Modes$sync|synced]] mode), where the _synced mode_ enables **100% offline operation**, keeping a copy of content in the browser’s local ([IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API)) database, syncing back to the server when a network connection is available.
|
||||
* SilverBullet provides an enjoyable [[Markdown]] writing experience with a clean UI, rendering text using [[Live Preview|live preview]], further **reducing visual noise** while still providing direct access to the underlying markdown syntax.
|
||||
* SilverBullet supports wiki-style **page linking** using the `[[page link]]` syntax. Incoming links are indexed and appear as [[Linked Mentions]] at the bottom of the pages linked to thereby providing _bi-directional linking_.
|
||||
* SilverBullet allows you to be extra productive using its [[Templates]] mechanism.
|
||||
* SilverBullet is optimized for **keyboard-based operation**:
|
||||
* Quickly navigate between pages using the **page switcher** (triggered with `Cmd-k` on Mac or `Ctrl-k` on Linux and Windows).
|
||||
* Run commands via their keyboard shortcuts or the **command palette** (triggered with `Cmd-/` or `Ctrl-/` on Linux and Windows).
|
||||
|
||||
@@ -5,7 +5,6 @@ The [[Plugs/Editor]] plug provides a few helpful ones:
|
||||
* `/h1` through `/h4` to turn the current line into a header
|
||||
* `/hr` to insert a horizontal rule (`---`)
|
||||
* `/table` to insert a markdown table (whoever can remember this syntax without it)
|
||||
* `/snippet` see [[Plugs/Template@snippets]]
|
||||
* `/today` to insert today’s date
|
||||
* `/tomorrow` to insert tomorrow’s date
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
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.
|
||||
Slash templates allow you to define custom [[Slash Commands]] that expand “snippet style” templates inline.
|
||||
|
||||
## Definition
|
||||
# Definition
|
||||
You can define a slash template by creating a [[Templates|template page]] with a template tag and `trigger` attribute.
|
||||
|
||||
Example:
|
||||
@@ -13,11 +13,8 @@ Example:
|
||||
|
||||
|^|
|
||||
|
||||
## 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.
|
||||
A template’s [[Frontmatter]] is interpreted by SilverBullet’s [[Templates|template]] engine and removed when instantiated. However, to still include frontmatter after instantiation, you can use the `frontmatter` attribute.
|
||||
|
||||
Example:
|
||||
|
||||
@@ -40,3 +37,7 @@ Which will expand into e.g.
|
||||
|
||||
.
|
||||
|
||||
When the page already contains frontmatter before invoking the slash command, it will be augmented with the additional frontmatter specified by the template.
|
||||
|
||||
# Use
|
||||
You can _trigger_ the slash template by typing `/<trigger>` (e.g. `/meeting-notes`) in any page.
|
||||
|
||||
+43
-13
@@ -1,25 +1,55 @@
|
||||
Templates are _reusable_ pieces of markdown content, usually with placeholders that are replaced once instantiated.
|
||||
Templates are reusable pieces of markdown content, usually with placeholders that are replaced once instantiated.
|
||||
|
||||
Templates are used in a few different contexts:
|
||||
There are two general uses for templates:
|
||||
|
||||
1. To render [[Live Queries]]
|
||||
2. To render [[Live Templates]]
|
||||
3. To be included using [[Slash Templates]]
|
||||
4. Some legacy use cases described in [[Plugs/Template]]
|
||||
1. _Live_ uses, where page content is dynamically updated based on templates:
|
||||
* [[Live Queries]]
|
||||
* [[Live Templates]]
|
||||
2. _One-off_ uses, where a template is instantiated once and inserted into an existing or new page:
|
||||
* [[Slash Templates]]
|
||||
* [[Page Templates]]
|
||||
|
||||
## 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.
|
||||
# Creating templates
|
||||
Templates are regular pages [[Tags|tagged]] with the `#template` tag. Note that, when tagged inline (by putting `#template` at the beginning of the page), the 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:
|
||||
**Naming**: it’s common, although not required, to use a `template/` prefix when naming templates.
|
||||
|
||||
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]].
|
||||
Tagging a page with a `#template` tag (either in the [[Frontmatter]] or using a [[Tags]] at the very beginning of the page content) does a few things:
|
||||
|
||||
1. It will make the page appear when completing template names, e.g. in `render` clauses in [[Live Queries]], or after the `page` key in [[Live Templates]].
|
||||
2. 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.
|
||||
3. It registers your templates to be used as [[Slash Templates]] as well as [[Page Templates]].
|
||||
|
||||
## Frontmatter
|
||||
[[Frontmatter]] has special meaning in templates. The following attributes are used:
|
||||
|
||||
* `tags`: should always be set to `template`
|
||||
* `type` (optional): should be set to `page` for [[Page Templates]]
|
||||
* `trigger` (optional): defines the slash command name for [[Slash Templates]]
|
||||
* `displayName` (optional): defines an alternative name to use when e.g. showing the template picker for [[Page Templates]], or when template completing a `render` clause in a [[Live Templates]].
|
||||
* `pageName` (optional, [[Page Templates]] only): specify a (template for a) page name.
|
||||
* `frontmatter` (optional): defines [[Frontmatter]] to be added/used in the rendered template. This can either be specified as a string or as an object.
|
||||
|
||||
An example:
|
||||
|
||||
---
|
||||
tags: template
|
||||
type: page
|
||||
trigger: one-on-one
|
||||
displayName: "1:1 template"
|
||||
pageName: "1-1s/"
|
||||
frontmatter:
|
||||
dateCreated: "{{today}}"
|
||||
---
|
||||
# {{today}}
|
||||
* |^|
|
||||
|
||||
# Template content
|
||||
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]]).
|
||||
The special `|^|` marker can be used to specify the desired cursor position after the template is included.
|
||||
|
||||
### Template helpers
|
||||
## Handlebar helpers
|
||||
There are a number of built-in handlebars helpers you can use:
|
||||
|
||||
- `{{today}}`: Today’s date in the usual YYYY-MM-DD format
|
||||
|
||||
@@ -0,0 +1,9 @@
|
||||
---
|
||||
tags: template
|
||||
type: page
|
||||
displayName: Slash Template
|
||||
pageName: "template/slash/"
|
||||
frontmatter:
|
||||
tags: template
|
||||
trigger: "|^|"
|
||||
---
|
||||
@@ -0,0 +1,10 @@
|
||||
---
|
||||
tags: template
|
||||
type: page
|
||||
displayName: Page Template
|
||||
pageName: "template/page/"
|
||||
frontmatter:
|
||||
tags: template
|
||||
type: page
|
||||
---
|
||||
|^|
|
||||
@@ -1 +1 @@
|
||||
Today is {{today}}!
|
||||
#template Today is {{today}}!
|
||||
Reference in New Issue
Block a user