neil/silverbullet
1
0
Fork 0
Code
51686b4792
silverbullet/website/Templates.md

3.9 KiB
Raw Blame History

Templates are reusable pieces of markdown content, usually with placeholders that are replaced once instantiated.

There are two general uses for templates:

  1. Live uses, where page content is dynamically updated based on templates:
  1. One-off uses, where a template is instantiated once and inserted into an existing or new page:

Creating templates

Templates are regular pages Tags 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.

Naming: it’s common, although not required, to use a template/ prefix when naming 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 and to frontmatter for Live Template Widgets
  • 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, such as {{today}}, and {{#each .}}.

The special |^| marker can be used to specify the desired cursor position after the template is included.

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
  • {{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}}