Rebuilt frontmatter templates as template widgets
This commit is contained in:
Zef Hemel
@@ -6,8 +6,14 @@ release.
|
||||
_Not yet released, this will likely become 0.6.0._
|
||||
|
||||
* **Directives have now been removed** from the code base. Please use [[Live Queries]] and [[Live Templates]] instead. If you hadn’t migrated yet and want to auto migrate, downgrade your SilverBullet version to 0.5.11 (e.g. using the `zefhemel/silverbullet:0.5.11` docker image) and run the {[Directive: Convert Entire Space to Live/Templates]} command with that version.
|
||||
* Custom renderer for [[Frontmatter]], enabling... [[Live Frontmatter Templates]] to specify custom rendering (using [[Templates]] of course) — see some of the plugs pages (e.g. [[Plugs/Editor]], [[Plugs/Git]]) to see what you can do with this (template here: [[internal-template/plug-frontmatter]]).
|
||||
* Somewhat nicer rendering of {{templateVars}}.
|
||||
* New [[Markdown/Code Widgets|Code Widget]]: `toc` to manually include a [[Table of Contents]]
|
||||
* New template type: [[Live Template Widgets]] allowing you to automatically add templates to the top or bottom of your pages (based on some criteria). Using this feature it possible to implement [[Table of Contents]] and [[Linked Mentions]] without having “hard coded” into SilverBullet itself.
|
||||
* **“Breaking” change:** Two features are now no longer hardcoded into SilverBullet, but can be activated quite easily using [[Live Template Widgets]] (see their respective documentation pages on instructions on how to do this):
|
||||
* [[Table of Contents]]
|
||||
* [[Linked Mentions]]
|
||||
* Templates:
|
||||
* Somewhat nicer rendering of {{templateVars}} (notice the gray background)
|
||||
* Rendering of [[Markdown/Code Widgets]] (such as live queries and templates) **are now disabled** on template pages, which should make them less confusing to read and interpret.
|
||||
|
||||
---
|
||||
|
||||
@@ -129,6 +135,6 @@ Other notable changes:
|
||||
* [[Plugs/Tasks]] now support custom states (not just `[x]` and `[ ]`), for example:
|
||||
* [IN PROGRESS] An in progress task
|
||||
* [BLOCKED] A task that’s blocked
|
||||
[[🔌 Tasks|Read more]]
|
||||
[[Plugs/Tasks|Read more]]
|
||||
* Removed [[Cloud Links]] support in favor of [[Federation]]. If you still have legacy cloud links, simply replace the 🌩️ with a `!` and things should work as before.
|
||||
|
||||
|
||||
@@ -1 +1,3 @@
|
||||
Linked mentions
|
||||
Linked Mentions are references from other pages to the current page. Technically, they’re not a built-in feature, but you can easily implement them using [[Live Template Widgets]].
|
||||
|
||||
To enable linked mentions being added to your pages, include the [[template/widget/linked-mentions]] template in your space, either through copy and pasting or through [[Federation]].
|
||||
|
||||
@@ -1,36 +0,0 @@
|
||||
Live Frontmatter Templates allow you to override the default rendering of [[Frontmatter]] at the top of your pages with a custom template.
|
||||
|
||||
> **warning** Warning
|
||||
> This feature is still _experimental_, aspects of it may change, or it could be removed altogether.
|
||||
|
||||
If you have no idea what that means or what you would use this for; you probably don’t need this feature. Don’t worry about it.
|
||||
|
||||
# Defining
|
||||
Live Frontmatter Templates follow the same pattern as other [[Templates]] with a few additional attributes:
|
||||
|
||||
* `tags`: should be set to `template` as for any other template
|
||||
* `type`: should be set to `frontmatter`
|
||||
* `where`: should contain an [[Live Queries$expression]] that evaluates to true for the _pages_ you would like to apply this Live Frontmatter Template to, usually this checks for a specific tag, but it can be any expression. Think of this as a `where` clause that should match for the pages this template is applied to.
|
||||
* `priority` (optional): in case you have multiple Live Frontmatter Templates that have matching `where` expression, the one with the priority set to the lowest number wins.
|
||||
|
||||
# Example
|
||||
The following Frontmatter Template applies to all pages tagged with `person` (see the `where`). It first lists all [[Frontmatter]] attributes, followed by a use of the [[!silverbullet.md/template/live/incoming]] template, showing all incomplete tasks that reference this particular page.
|
||||
|
||||
Indeed, you can use [[Live Queries]] and [[Live Templates]] here as well.
|
||||
|
||||
---
|
||||
tags: template
|
||||
type: frontmatter
|
||||
where: 'tags = "person"'
|
||||
---
|
||||
{{#each .}}**{{@key}}**: {{.}}
|
||||
{{/each}}
|
||||
## Incoming tasks
|
||||
```template
|
||||
page: "[[!silverbullet.md/template/live/incoming]]"
|
||||
```
|
||||
|
||||
## Plug frontmatter template
|
||||
This site uses the [[internal-template/plug-frontmatter]] template for pages tagged with `plug`, such as [[Plugs/Editor]], [[Plugs/Github]] and [[Plugs/Mermaid]].
|
||||
|
||||
|
||||
@@ -0,0 +1,34 @@
|
||||
Live Template Widgets allow you to automatically render templated markdown widgets to the top or bottom of pages matching specific criteria.
|
||||
|
||||
> **warning** Warning
|
||||
> This feature is still _experimental_, aspects of it may change, or it could be removed altogether.
|
||||
|
||||
If you have no idea what that means or what you would use this for; you probably don’t need this feature. Don’t worry about it.
|
||||
|
||||
# Defining
|
||||
Live Template Widgets follow the same pattern as other [[Templates]] with a few additional attributes:
|
||||
|
||||
* `tags`: should be set to `template` as for any other template
|
||||
* `type`: should be set to `widget:top` or `widget:bottom` depending on where you would like it to appear
|
||||
* `where`: should contain an [[Live Queries$expression]] that evaluates to true for the _pages_ you would like to apply this template to, usually this checks for a specific tag, but it can be any expression. Think of this as a `where` clause that should match for the pages this template is applied to.
|
||||
* `priority` (optional): in case you have multiple templates that have matching `where` expression, the one with the priority set to the lowest number wins.
|
||||
|
||||
# Example
|
||||
The following widget template applies to all pages tagged with `person` (see the `where`). It uses the [[!silverbullet.md/template/live/incoming]] template, to show all incomplete tasks that reference this particular page.
|
||||
|
||||
Indeed, you can use [[Live Queries]] and [[Live Templates]] here as well.
|
||||
|
||||
---
|
||||
tags: template
|
||||
type: frontmatter
|
||||
where: 'tags = "person"'
|
||||
---
|
||||
## Incoming tasks
|
||||
```template
|
||||
page: "[[!silverbullet.md/template/live/incoming]]"
|
||||
```
|
||||
|
||||
## Plug widget template
|
||||
This site uses the [[internal-template/plug-widget]] template for pages tagged with `plug`, such as [[Plugs/Editor]], [[Plugs/Github]] and [[Plugs/Mermaid]].
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
Live templates rendering [[Templates]] inline in a page.
|
||||
Live templates render [[Templates]] inline in a page. They’re called “Live” because their content updates dynamically.
|
||||
|
||||
## 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.
|
||||
@@ -16,7 +16,7 @@ template: |
|
||||
Today is {{today}}!
|
||||
```
|
||||
|
||||
To pass in a value to the template, you can specify the optional `value` attribute:
|
||||
To pass a literal value to the template, you can specify the optional `value` attribute:
|
||||
```template
|
||||
template: |
|
||||
Hello, {{name}}! Today is _{{today}}_
|
||||
@@ -24,6 +24,17 @@ value:
|
||||
name: Pete
|
||||
```
|
||||
|
||||
You can also pass in the result of a [[Live Queries|query]] as a value by setting the `query` attribute:
|
||||
|
||||
```template
|
||||
template: |
|
||||
{{#each .}}
|
||||
* #{{name}}
|
||||
{{/each}}
|
||||
query: |
|
||||
tag where parent = "page" select name
|
||||
```
|
||||
|
||||
If you just want to render the raw markdown without handling it as a handlebars template, set `raw` to true:
|
||||
```template
|
||||
template: |
|
||||
|
||||
@@ -1,28 +1,21 @@
|
||||
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.
|
||||
Code widgets are a SilverBullet-specific [[Markdown/Extensions|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 a few code widgets out of the box:
|
||||
|
||||
* `toc`: [[Table of Contents]]
|
||||
* `query`: [[Live Queries]]
|
||||
* `template`: [[Live Templates]]
|
||||
* `embed`
|
||||
* `markdown`
|
||||
|
||||
In addition, plugs like [[Plugs/KaTeX]] and [[Plugs/Mermaid]] add additional ones.
|
||||
|
||||
## Embed
|
||||
This allows you to embed internet content into your page inside of an iframe. This is useful to, for instance, embed youtube videos. In fact, there is specific support for those.
|
||||
|
||||
Two examples.
|
||||
|
||||
First, embedding the silverbullet.md website inside the silverbullet.md website (inception!):
|
||||
|
||||
```embed
|
||||
url: https://silverbullet.md
|
||||
height: 500
|
||||
```
|
||||
|
||||
## `embed`
|
||||
This allows you to embed internet content into your page inside of an iframe. This is useful to embed youtube videos or other websites.
|
||||
and a YouTube video:
|
||||
|
||||
```embed
|
||||
url: https://www.youtube.com/watch?v=VemS-cqAD5k
|
||||
url: https://youtu.be/BbNbZgOwB-Y
|
||||
```
|
||||
|
||||
Note, there is specific support for YouTube videos — it automatically sets the width and height, and replaces the URL with an embed URL.
|
||||
@@ -32,10 +25,3 @@ The body of an `embed` block is written in [[YAML]] and supports the following a
|
||||
* `url` (mandatory): the URL of the content to embed
|
||||
* `height` (optional): the height of the embedded page in pixels
|
||||
* `width` (optional): the width of the embedded page in pixels
|
||||
|
||||
## Markdown
|
||||
You can embed markdown inside of markdown and live preview it. Is this useful? 🤷 Not particularly, it’s more of a demo of how this works. Nevertheless, to each their own, here’s an example:
|
||||
|
||||
```markdown
|
||||
This is going to be **bold**
|
||||
```
|
||||
@@ -6,6 +6,7 @@ In addition to supporting [[Markdown/Basics|markdown basics]] as standardized by
|
||||
* Generically via [[Markdown/Code Widgets]]
|
||||
* [[Live Queries]]
|
||||
* [[Live Templates]]
|
||||
* [[Table of Contents]]
|
||||
* [[Anchors]]
|
||||
* [[Markdown/Admonitions]]
|
||||
* Hashtags, e.g. `#mytag`.
|
||||
|
||||
@@ -1,6 +1,4 @@
|
||||
---
|
||||
tags: plug
|
||||
---
|
||||
#plug
|
||||
|
||||
The `editor` plug implements foundational editor functionality for SilverBullet.
|
||||
|
||||
|
||||
@@ -4,16 +4,12 @@ tags: plug
|
||||
The [[Plugs/Template]] plug implements a few templating mechanisms.
|
||||
|
||||
# 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).
|
||||
|
||||
# Weekly Note
|
||||
|
||||
The {[Open Weekly Note]} command navigates (or creates) a weekly note prefixed
|
||||
with a 🗓️ emoji by default, but this is configurable via the `weeklyNotePrefix` setting in `SETTINGS`. If you have a page template (see above) named `template/page/Weekly Note` it will use this as a template, otherwise, the page will just be empty.
|
||||
The {[Open Weekly Note]} command navigates (or creates) a weekly note prefixed with a 🗓️ emoji by default, but this is configurable via the `weeklyNotePrefix` setting in `SETTINGS`. If you have a page template (see above) named `template/page/Weekly Note` it will use this as a template, otherwise, the page will just be empty.
|
||||
|
||||
# Quick Note
|
||||
|
||||
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.
|
||||
|
||||
# Built-in slash commands
|
||||
|
||||
@@ -1,3 +1,30 @@
|
||||
The Table of Contents widget, when enabled, shows a table of contents at the start of the page for any page with 3 headers or more. It is updated whenever hovering the mouse cursor over it. Clicking any of the headers will navigate there within the page.
|
||||
You can add a table of contents to a page using the `toc` [[Markdown/Code Widgets|Code Widget]].
|
||||
|
||||
You can enable/disable this feature via {[Table of Contents: Toggle]}.
|
||||
In its most basic form it looks like this (click the edit button to see the code):
|
||||
|
||||
```toc
|
||||
```
|
||||
|
||||
You can use it in two ways:
|
||||
|
||||
1. _Manually_, by adding a `toc` widget to the pages where you’d like to render a ToC
|
||||
2. _Automatically_, using a [[Live Template Widgets|Live Template Widget]]
|
||||
|
||||
To have a ToC added to all pages with a larger (e.g. 3) number of headings, it is recommended to use [[template/widget/toc|this template widget]]. You can do this by either copy and pasting it into your own space, or by using [[Federation]] and have it included in your space that way:
|
||||
|
||||
```yaml
|
||||
federation:
|
||||
- uri: silverbullet.md/template/widget/toc
|
||||
```
|
||||
|
||||
## Configuration
|
||||
In the body of the `toc` code widget you can configure a few options:
|
||||
|
||||
* `header`: by default a “Table of Contents” header is added to the ToC, set this to `false` to disable rendering this header
|
||||
* `minHeaders`: only renders a ToC if the number of headers in the current page exceeds this number, otherwise render an empty widget
|
||||
|
||||
Example:
|
||||
```toc
|
||||
header: false
|
||||
minHeaders: 1
|
||||
```
|
||||
|
||||
@@ -54,3 +54,13 @@ where type = "query"
|
||||
order by order
|
||||
render [[template/documented-template]]
|
||||
```
|
||||
|
||||
# Live Widget Templates
|
||||
Use these to add [[Table of Contents]] and [[Linked Mentions]] to your pages.
|
||||
|
||||
```query
|
||||
template
|
||||
where type =~ /^widget:/ and name =~ /^template\//
|
||||
order by order
|
||||
render [[template/documented-template]]
|
||||
```
|
||||
|
||||
@@ -5,7 +5,7 @@ There are two general uses for templates:
|
||||
1. _Live_ uses, where page content is dynamically updated based on templates:
|
||||
* [[Live Queries]]
|
||||
* [[Live Templates]]
|
||||
* [[Live Frontmatter Templates]]
|
||||
* [[Live Template Widgets]]
|
||||
2. _One-off_ uses, where a template is instantiated once and inserted into an existing or new page:
|
||||
* [[Slash Templates]]
|
||||
* [[Page Templates]]
|
||||
@@ -25,7 +25,7 @@ Tagging a page with a `#template` tag (either in the [[Frontmatter]] or using a
|
||||
[[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 Frontmatter Templates]]
|
||||
* `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.
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
---
|
||||
tags: template
|
||||
type: frontmatter
|
||||
type: widget:top
|
||||
where: 'tags = "plug"'
|
||||
---
|
||||
{{#if author}}This page documents a [[Plugs|plug]] created by **{{author}}**. [Repository]({{repo}}).{{else}}This page documents a [[Plugs|plug]] built into SilverBullet.{{/if}}
|
||||
@@ -0,0 +1,19 @@
|
||||
---
|
||||
description: Adds Linked Mentions to all pages
|
||||
tags: template
|
||||
type: widget:bottom
|
||||
where: 'true'
|
||||
---
|
||||
```template
|
||||
# We need to escape handlebars directives here, since we're embedding
|
||||
# this template into a template (INCEPTION)
|
||||
template: |
|
||||
{{escape "#if ."}}
|
||||
# Linked Mentions
|
||||
{{escape "#each ."}}
|
||||
* [[{{escape "ref"}}]]: `{{escape "snippet"}}`
|
||||
{{escape "/each"}}
|
||||
{{escape "/if"}}
|
||||
query: |
|
||||
link where toPage = "{{@page.name}}" and page != "{{@page.name}}"
|
||||
```
|
||||
@@ -0,0 +1,9 @@
|
||||
---
|
||||
description: Adds a Table of Contents to all pages
|
||||
tags: template
|
||||
type: widget:top
|
||||
where: 'true'
|
||||
---
|
||||
```toc
|
||||
minHeaders: 3
|
||||
```
|
||||
Reference in New Issue
Block a user