From b69f6916fc73ae307e5330b62208fc219f8649e4 Mon Sep 17 00:00:00 2001 From: Zef Hemel Date: Thu, 15 Aug 2024 16:39:17 +0200 Subject: [PATCH] Website updates with leveling --- website/Attachments.md | 2 + website/Attributes.md | 2 + website/CHANGELOG.md | 1 + website/Frontmatter.md | 1 + website/Links.md | 2 + website/Live Queries.md | 2 + website/Live Template Widgets.md | 2 + website/Live Templates.md | 2 + website/Manual.md | 3 +- website/Markdown.md | 2 + website/Markdown/Admonitions.md | 2 + website/Markdown/Basics.md | 2 + website/Meta Pages.md | 2 + website/Object Decorators.md | 2 + website/Objects.md | 10 ++-- website/Outlines.md | 2 + website/Page Decorations.md | 2 + website/Page Templates.md | 2 + website/Pages.md | 2 + website/SETTINGS.md | 6 +- website/Schema.md | 99 ++++++++++++++++++++++++++++++++ website/Shortcuts.md | 2 + website/Slash Commands.md | 2 + website/Snippets.md | 2 + website/Space Script.md | 2 + website/Space Style.md | 2 + website/Spaces.md | 2 + website/Templates.md | 2 + website/example/contact/Jane.md | 6 ++ website/example/contact/Joe.md | 8 +++ 30 files changed, 168 insertions(+), 10 deletions(-) create mode 100644 website/Schema.md create mode 100644 website/example/contact/Jane.md create mode 100644 website/example/contact/Joe.md diff --git a/website/Attachments.md b/website/Attachments.md index bf9f5e1c..2abfd5e5 100644 --- a/website/Attachments.md +++ b/website/Attachments.md @@ -1,3 +1,5 @@ +#level/beginner + While SilverBullet for sure is aimed at primarily text-based content, life can not fully be represented in text always. Therefore, SilverBullet supports attachments. Attachments, like [[Pages]] ultimately are — once again — just files on disk. # Uploading diff --git a/website/Attributes.md b/website/Attributes.md index 6508f70c..06a15e02 100644 --- a/website/Attributes.md +++ b/website/Attributes.md @@ -1,3 +1,5 @@ +#level/intermediate + Attribute syntax can contribute additional [[Metadata]] to various [[Objects]], including: * Pages diff --git a/website/CHANGELOG.md b/website/CHANGELOG.md index 9c6973dd..b0d0fa47 100644 --- a/website/CHANGELOG.md +++ b/website/CHANGELOG.md @@ -5,6 +5,7 @@ An attempt at documenting the changes/new features introduced in each release. ## Edge _These features are not yet properly released, you need to use [the edge builds](https://community.silverbullet.md/t/living-on-the-edge-builds/27) to try them._ +* Initial version of [[Schema]] support * Widget buttons for [[Transclusions]] (by [onespaceman](https://github.com/silverbulletmd/silverbullet/pull/1013)) * SETTINGS is now first indexed, when a full space reindex needs to happen. * Internal refactor, and more leverage of [JSR](https://jsr.io/). The SilverBullet [plug API](https://jsr.io/@silverbulletmd/silverbullet) is now published on JSR as well, and soon this will be the preferred way of importing the plug APIs. diff --git a/website/Frontmatter.md b/website/Frontmatter.md index d9d3e0d6..ff1f1cfb 100644 --- a/website/Frontmatter.md +++ b/website/Frontmatter.md @@ -1,5 +1,6 @@ --- status: Complete +tags: level/beginner --- Frontmatter is a common format to attach additional metadata (data about data) to markdown documents. diff --git a/website/Links.md b/website/Links.md index 8177e7f7..560cf3b6 100644 --- a/website/Links.md +++ b/website/Links.md @@ -1,3 +1,5 @@ +#level/beginner + You can create three types of links in SilverBullet: * External links, using the `[title](URL)` syntax, for instance: [SilverBullet community](https://community.silverbullet.md). diff --git a/website/Live Queries.md b/website/Live Queries.md index f44b2088..f5cfb4d9 100644 --- a/website/Live Queries.md +++ b/website/Live Queries.md @@ -1,3 +1,5 @@ +#level/intermediate + Live Queries are a [[Blocks|block]] that generates a (quasi) live view on various data sources, usually [[Objects]], and renders their results inline via [[Live Preview]] either as a table or using [[Templates]]. The syntax used is: diff --git a/website/Live Template Widgets.md b/website/Live Template Widgets.md index aed51d7e..4084ff5c 100644 --- a/website/Live Template Widgets.md +++ b/website/Live Template Widgets.md @@ -1,3 +1,5 @@ +#level/hardcore + Live Template Widgets allow you to automatically render templated markdown widgets at the top or bottom of pages matching specific criteria. > **warning** Warning diff --git a/website/Live Templates.md b/website/Live Templates.md index 42f4345c..3a12b37a 100644 --- a/website/Live Templates.md +++ b/website/Live Templates.md @@ -1,3 +1,5 @@ +#level/intermediate + Live Templates are a type of [[Blocks|block]] that render [[Templates]] written in [[Template Language]] inline in a page. There are two variants of Live Templates: diff --git a/website/Manual.md b/website/Manual.md index 54c314c8..95404056 100644 --- a/website/Manual.md +++ b/website/Manual.md @@ -9,7 +9,6 @@ However, that is all unlikely to happen unless you understand what SilverBullet The biggest hurdle to get over with SilverBullet is that you need to get this thing running. And as of yet, the only way to do that is to install and deploy it yourself. 🤷 * [[Install]]: Installation instructions for various setups -* [[Authelia]]: configuring SilverBullet with [Authelia](https://www.authelia.com/) authentication. For more additional guides, check out [our community guides](https://community.silverbullet.md/c/guides/6). @@ -63,7 +62,7 @@ The main ways to roam your space, beside following page links, are: * [[Space Script]] & [[Space Style]] # Customization -* [[SETTINGS]] +* [[SETTINGS]] and [[Space Config]] * [[Shortcuts]] * [[Page Decorations]] * [[Space Style]] diff --git a/website/Markdown.md b/website/Markdown.md index e68ead92..aae97fd8 100644 --- a/website/Markdown.md +++ b/website/Markdown.md @@ -1,3 +1,5 @@ +#level/beginner + Markdown is a plain text formatting system [originally developed by John Gruber](https://daringfireball.net/projects/markdown/). It has since been standardized into [CommonMark](https://commonmark.org/), which is what SilverBullet uses (with [[Markdown/Extensions]]). While a bit more technical than [WYSIWYG](https://pl.wikipedia.org/wiki/WYSIWYG)-style editing (like MS Word), the nice thing about markdown is that it is a (relatively) easy-to-implement standard, and you can read files even without special tools (like SilverBullet). This means that _you will always have access to the content_ even if you switch tools. It also means that you can use multiple tools at the same time to edit these files. You don’t have to use SilverBullet exclusively. diff --git a/website/Markdown/Admonitions.md b/website/Markdown/Admonitions.md index 8c818a79..3aaf6b91 100644 --- a/website/Markdown/Admonitions.md +++ b/website/Markdown/Admonitions.md @@ -1,3 +1,5 @@ +#level/intermediate + Silverbullet supports [admonitions](https://github.com/community/community/discussions/16925) using GitHub syntax (`note` and `warning`). > **note** This is a diff --git a/website/Markdown/Basics.md b/website/Markdown/Basics.md index 3db56c28..53503cf3 100644 --- a/website/Markdown/Basics.md +++ b/website/Markdown/Basics.md @@ -1,3 +1,5 @@ +#level/beginner + The idea of markdown is that you write plain text with some additional markup that even without further processing (like rendering it to HTML, or [[Live Preview]]) you could just read and understand. It was inspired by conventions used in plain-text e-mails, before e-mail supported rich formatting. # Basic markup diff --git a/website/Meta Pages.md b/website/Meta Pages.md index 09bc15f3..e5252da1 100644 --- a/website/Meta Pages.md +++ b/website/Meta Pages.md @@ -1,3 +1,5 @@ +#level/intermediate + Meta pages are pages not core to your content, but function as a way to configure your [[Spaces|space]]. You can think of them as “tooling” pages. The most obvious example is [[SETTINGS]], which is not really a page that you care about day-to-day, but only want to tweak when you’re working on your space as a tool. diff --git a/website/Object Decorators.md b/website/Object Decorators.md index 8ace7b8d..10650ffc 100644 --- a/website/Object Decorators.md +++ b/website/Object Decorators.md @@ -1,3 +1,5 @@ +#level/hardcore + Object decorators are an **advanced technique** that can be used to add attributes to [[Objects]] dynamically whose values are _calculated dynamically_ (on-the-fly) based on an [[Expression Language|expression]]. > **warning** Warning diff --git a/website/Objects.md b/website/Objects.md index 44bb119d..0df4dc66 100644 --- a/website/Objects.md +++ b/website/Objects.md @@ -1,3 +1,5 @@ +#level/intermediate + SilverBullet automatically builds and maintains an index of _objects_ extracted from all markdown pages in your space. It subsequently allows you to [[Live Queries|query]] this database in (potentially) useful ways. By design, the truth remains in the markdown: all data indexed as objects will have a representation in markdown text as well. This index can be flushed at any time and be rebuilt from its source markdown files kept in your space (and you can do so on demand if you like using the {[Space: Reindex]} command). @@ -23,9 +25,7 @@ Every object has a main `tag`, which signifies the type of object being describe Here are the currently built-in tags: ## page -Every page in your space is available via the `page` tag. You can attach _additional_ tags to a page, by either specifying them in the `tags` attribute [[Frontmatter]], or by putting additional [[Tags]] in a stand alone paragraph with no other (textual) content in them, e.g.: - -#example-tag #another-tag +Every page in your space is available via the `page` tag. You can attach _additional_ tags to a page, by either specifying them in the `tags` attribute [[Frontmatter]], or by putting additional [[Tags]] in a stand alone paragraph with no other (textual) content in them, for instance check the very first line of this page that says `#level/intermediate`. In addition to `ref` and `tags`, the `page` tag defines a bunch of additional attributes as can be seen in this example query: @@ -33,10 +33,10 @@ In addition to `ref` and `tags`, the `page` tag defines a bunch of additional at page where name = @page.name ``` -Note that you can also query this page using the `example-tag` directly: +Note that you can also query this page using the `level/intermediate` directly: ```query -example-tag +level/intermediate ``` ## table diff --git a/website/Outlines.md b/website/Outlines.md index d07542ce..957059c3 100644 --- a/website/Outlines.md +++ b/website/Outlines.md @@ -1,3 +1,5 @@ +#level/intermediate + While SilverBullet is not a “proper” outliner, it does offer a number of useful commands to manage outlines. An outline is simply a (nested) bulleted list, for instance: diff --git a/website/Page Decorations.md b/website/Page Decorations.md index 964ee52b..1d19c836 100644 --- a/website/Page Decorations.md +++ b/website/Page Decorations.md @@ -5,6 +5,8 @@ pageDecoration: cssClasses: - christmas-decoration --- +#level/intermediate + Page decorations allow you to “decorate” pages in various fun ways. > **warning** Warning diff --git a/website/Page Templates.md b/website/Page Templates.md index 76e9f314..8941ebfa 100644 --- a/website/Page Templates.md +++ b/website/Page Templates.md @@ -1,3 +1,5 @@ +#level/intermediate + Page templates enable you to define templates for creating new pages. They can be invoked in a few ways: * Explicitly using the {[Page: From Template]} command diff --git a/website/Pages.md b/website/Pages.md index b7b0b935..9b18319f 100644 --- a/website/Pages.md +++ b/website/Pages.md @@ -1,3 +1,5 @@ +#level/beginner + The primary thing you’ll be doing in SilverBullet (hopefully) is creating and editing pages. Pages are written in [[Markdown]], can contain [[Metadata]] and are kept on the server as text files. Page _names_ are relatively free-form, but have to adhere to a few [[Page Name Rules]]. diff --git a/website/SETTINGS.md b/website/SETTINGS.md index 86fad13d..51e8da8e 100644 --- a/website/SETTINGS.md +++ b/website/SETTINGS.md @@ -9,9 +9,9 @@ libraries: # The "Core" library is recommended for all users - import: "[[!silverbullet.md/Library/Core/*]]" # You can exclude items from the import using exclude (also supports wildcards): - # exclude: - # - [[!silverbullet.md/Table of Contents]] - # - [[!silverbullet.md/Library/Core/Widget/*]] + #exclude: + # - "[[!silverbullet.md/Table of Contents]]" + # - "[[!silverbullet.md/Library/Core/Widget/*]]"" ## UI TWEAKS # Hide the sync button diff --git a/website/Schema.md b/website/Schema.md new file mode 100644 index 00000000..84e3789d --- /dev/null +++ b/website/Schema.md @@ -0,0 +1,99 @@ +#level/hardcore + +> **warning** Warning +> This feature is **experimental**, it may evolve over time. + +SilverBullet allows you to define schema for custom [[Space Config]] settings as well as for [[Objects|object]] [[Tags|tags]]. Both are defined using [[Space Config]] and use a [[YAML]] encoding of [JSON Schema](https://json-schema.org/). + +# Object Schemas +The general format to define schemas for specific [[Tags]] is as follows: + +~~~ +```space-config +schema.tag.<>: <> +``` +~~~ + +## Example +Let’s say you use pages tagged with `#contact` to represent your contacts: + +```template +{{#each {contact}}} +* [[{{name}}]] ([{{email}}](mailto:{{email}})): + * First name: _{{firstName}}_ + * Last name: _{{lastName}}_ +{{/each}} +``` + +To ensure you always attach the required meta data in [[Frontmatter]] for your contacts, you’d like to do some checking. Specifically you would like to enforce that: + +* `firstName` should always be a `string` and is _required_ +* `lastName` should always be a `string` and is _required_ +* `email` should be an e-mail address, if specified + +You can achieve this using the following [[Space Config]]: + +```space-config +schema.tag.contact: + properties: + firstName.type: string + lastName.type: string + email: + type: string + format: email + required: + - firstName + - lastName +``` + +> **note** Note +> To reload changes to your schema, be sure to run {[System: Reload]} + +# Config schema +[[Space Config]] allows you to define arbitrary configuration keys for your own use cases. This is primarily useful for [[Libraries]], but perhaps you find your own use cases too. + +The general format is: + +~~~ +```space-config +schema.config: <> +``` +~~~ + +## Example +Let’s say you find it useful to make your full name globally configurable: + +```space-config +myFullName: "Steve Hanks" +``` + +This can be useful, because you can reference this configuration key in any query or template, e.g.: + +```template +My full name is: {{@config.myFullName}} +``` + +However, you would like to make sure that this `myFullName` configuration is always a string. You can achieve this with the following config schema definition: + +```space-config +schema.config.properties.myFullName.type: string +``` + +Now, if you would accidentally change `myFullName` into a number or boolean value, you would get a validation error. + +# Validation +At the moment, validation only occurs in the editor in [[Space Config]] and [[Frontmatter]] blocks and shows any violations as highlighted errors. + +Even if data does not pass validation, it is still stored in the data store so it does not (currently) _enforce_ the format. + +This may change in the future. + +# Supported types +All standard JSON Schema types are supported. Likely you are interested in: +* `string` + * With custom formats (specified via `format`): + * `email` + * `page-ref` (for page references, e.g. `[[something]]`) +* `number` +* `array` +* `object` \ No newline at end of file diff --git a/website/Shortcuts.md b/website/Shortcuts.md index 1c576ceb..3debb9b5 100644 --- a/website/Shortcuts.md +++ b/website/Shortcuts.md @@ -1,3 +1,5 @@ +#level/intermediate + SilverBullet enables you to configure some custom shortcuts in [[SETTINGS]] via the `shortcuts` attribute that trigger [[Commands]] in various ways. Supported types of shortcuts: diff --git a/website/Slash Commands.md b/website/Slash Commands.md index 6758f1c9..5b803117 100644 --- a/website/Slash Commands.md +++ b/website/Slash Commands.md @@ -1,3 +1,5 @@ +#level/beginner + Slash commands are quick ways to perform repetitive tasks. 99% of the time this will mean inserting a [[Snippets|snippet]], but they can also be configured to trigger commands (see [[Shortcuts]]). # Invoking a slash command diff --git a/website/Snippets.md b/website/Snippets.md index 28a78476..2a52f8cf 100644 --- a/website/Snippets.md +++ b/website/Snippets.md @@ -1,3 +1,5 @@ +#level/intermediate + Snippets allow you to define custom [[Commands]] and [[Slash Commands]] that expand snippet-style templates inline. # Definition diff --git a/website/Space Script.md b/website/Space Script.md index 4c831c2d..30085a9c 100644 --- a/website/Space Script.md +++ b/website/Space Script.md @@ -1,3 +1,5 @@ +#level/hardcore + Space Script allows you to extend SilverBullet with JavaScript from within your space using `space-script` [[Blocks]]. It’s script... in (your) [[Spaces|space]]. Get it? > **warning** **Security** diff --git a/website/Space Style.md b/website/Space Style.md index 57c48c73..693a8613 100644 --- a/website/Space Style.md +++ b/website/Space Style.md @@ -1,3 +1,5 @@ +#level/hardcore + Space Style is [[Space Script]]’s stylish sibling. It enables you to add your own styling to SilverBullet with `space-style` [[Blocks]]. This can be used to achieve various things, such as overriding the default editor font or setting wider page widths. It is also possible to develop custom themes this way. diff --git a/website/Spaces.md b/website/Spaces.md index ab54549e..81385133 100644 --- a/website/Spaces.md +++ b/website/Spaces.md @@ -1,3 +1,5 @@ +#level/beginner + A _space_ is SilverBullet terminology for a workspace, or project. [Obsidian](https://obsidian.md/) calls this a vault, [LogSeq](https://logseq.com/) calls it a graph. You may think of it as a [[Folders|folder]] or a directory — because in practical terms, that’s all it is. Feel free to back-up or manipulate your space’s folder and its files with whatever tool you like — you don’t have to use SilverBullet exclusively. You may want to turn your space’s folder into a git repository, for instance, and do version control and back-ups that way — in which case you may appreciated the [[Plugs/Git]] plug. diff --git a/website/Templates.md b/website/Templates.md index dfcc01c8..118256c7 100644 --- a/website/Templates.md +++ b/website/Templates.md @@ -1,3 +1,5 @@ +#level/intermediate + Templates are pieces of (markdown) text that contain placeholders (named _directives_) that are replaced once instantiated. Templates are written in SilverBullet’s [[Template Language]]. Like everything else, templates are kept in your space. They’re effectively regular [[Pages]], and are [[Tags|tagged]] with the `template` tag. diff --git a/website/example/contact/Jane.md b/website/example/contact/Jane.md new file mode 100644 index 00000000..1bd26ef0 --- /dev/null +++ b/website/example/contact/Jane.md @@ -0,0 +1,6 @@ +--- +firstName: Jane +lastName: Doe +email: jane@doe.family +--- +#contact \ No newline at end of file diff --git a/website/example/contact/Joe.md b/website/example/contact/Joe.md new file mode 100644 index 00000000..df437109 --- /dev/null +++ b/website/example/contact/Joe.md @@ -0,0 +1,8 @@ +--- +firstName: Joe +lastName: Doe +email: joe@doe.family +--- +#contact + +Joe is a stand up guy. \ No newline at end of file