Awesome frontmatter (#617)

Live Frontmatter Templates
2024-01-04 20:08:12 +01:00
parent 9040993232
commit 91027af5fe
53 changed files with 646 additions and 342 deletions
@@ -6,6 +6,8 @@ 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}}.

 ---

@@ -1,10 +1,14 @@
+---
+status: Complete
+tags: meta
+---
 Frontmatter is a common format to attach additional metadata (data about data) to markdown documents.

 In SilverBullet, there are multiple ways to attach [[Metadata]] to a page; frontmatter is one of them.

-You create it by starting your markdown document with `---` followed by [[YAML]] encoded attributes and then ending with `---` again. Followed by the regular body of your document.
+You create it by starting your markdown document with `---` followed by [[YAML]] encoded attributes and then ending with `---` again. Followed by the regular body of your document. This very page contains some frontmatter, click on it to see the underlying code.

-Here is an example:
+Here is another example:

    ---
    status: Draft
@@ -0,0 +1,33 @@
+Live Frontmatter Templates allow you to override the default rendering of [[Frontmatter]] at the top of your pages with a custom template.
+
+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]].
+
+
@@ -1,4 +1,6 @@
-#plug
+---
+tags: plug
+---

 The `editor` plug implements foundational editor functionality for SilverBullet.

@@ -1,3 +1,4 @@
-#plug
-
+---
+tags: plug
+---
 The Emoji plug provides support for auto-completion of the `:emoji:` style syntax. It currently has support for the [15.1 emoji unicode standard](https://emojipedia.org/emoji-15.1). 🎉
@@ -2,8 +2,10 @@
 uri: github:silverbulletmd/silverbullet-github/github.plug.js
 repo: https://github.com/silverbulletmd/silverbullet-github
 author: Zef Hemel
+shareSupport: true
+tags: plug
 ---
-#plug #share-support
+
 ```template
 page: "[[!raw.githubusercontent.com/silverbulletmd/silverbullet-github/main/README]]"
 raw: true
@@ -1,5 +1,6 @@
-#plug
-
+---
+tags: plug
+---
 SilverBullet has a generic indexing infrastructure for [[Objects]]. Pages are automatically index upon save, so about every second. 

 The [[Plugs/Index]] plug also defines syntax for [[Tags]].
@@ -1,5 +1,7 @@
-#share-support #plug
-
+---
+tags: plug
+shareSupport: true
+---
 The Markdown plug provides support for various advanced Markdown features, specifically:

 * {[Markdown Preview: Toggle]} preview
@@ -2,9 +2,9 @@
 uri: github:silverbulletmd/silverbullet-mattermost/mattermost.plug.json
 repo: https://github.com/silverbulletmd/silverbullet-mattermost
 author: Zef Hemel
+shareSupport: true
+tags: plug
 ---
-#plug #share-support
-
 > **warning** Unmaintained
 > This plug is currently not being maintained, it may break at any time

@@ -5,7 +5,6 @@ uri: github:silverbulletmd/silverbullet-mermaid/mermaid.plug.js
 repo: https://github.com/silverbulletmd/silverbullet-mermaid
 author: Zef Hemel
 ---
-
 Example use:
 ```mermaid
 flowchart TD
@@ -2,8 +2,9 @@
 uri: github:m1lt0n/silverbullet-serendipity/serendipity.plug.json
 repo: https://github.com/m1lt0n/silverbullet-serendipity
 author: Pantelis Vratsalis
+tags: plug
 ---
-#plug
+
 ```template
 page: "[[!raw.githubusercontent.com/m1lt0n/silverbullet-serendipity/main/README]]"
 raw: true
@@ -1,13 +1,12 @@
 ---
 repo: https://github.com/silverbulletmd/silverbullet
+tags: plug
 ---
-#plug
-
 The Share plug provides infrastructure for sharing pages outside of your space. It standardizes the {[Share: Publish]} (bound to `Cmd-s` or `Ctrl-s`) to publish the current page to all share providers specified under the `$share` key in [[Frontmatter]].

 See the [original RFC](https://github.com/silverbulletmd/silverbullet/discussions/117) for implementation details.

 Specific implementations for sharing are implemented in other plugs, specifically:
 ```query
-share-support render [[template/page]] 
+plug where shareSupport = true render [[template/page]] 
 ```
@@ -1,5 +1,6 @@
-#plug
-
+---
+tags: plug
+---
 The Tasks plug implements task support in SilverBullet.

 ## Task states
@@ -1,5 +1,6 @@
-#plug
-
+---
+tags: plug
+---
 The [[Plugs/Template]] plug implements a few templating mechanisms.

 # Daily Note
@@ -5,6 +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]]
 2. _One-off_ uses, where a template is instantiated once and inserted into an existing or new page:
  * [[Slash Templates]]
  * [[Page Templates]]
@@ -24,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]]
+* `type` (optional): should be set to `page` for [[Page Templates]] and to `frontmatter` for [[Live Frontmatter 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.
@@ -0,0 +1,7 @@
+---
+tags: template
+type: frontmatter
+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}}
+{{#if shareSupport}}_This plug supports [[Plugs/Share]]_{{/if}}