From 59c271131b3b7522a177197933fcbb6bcf8e9e25 Mon Sep 17 00:00:00 2001 From: Zef Hemel Date: Wed, 4 Mar 2026 13:31:27 +0100 Subject: [PATCH] Big website content iteration --- libraries/Library/Std/APIs/Schema.md | 50 ++++++++++- libraries/Library/Std/APIs/Template.md | 61 ++++++++++++- website/API.md | 10 ++- website/API/codeWidget.md | 2 + website/API/dom.md | 2 + website/API/event.md | 2 +- website/API/service.md | 14 ++- website/API/taskState.md | 2 +- website/API/widget.md | 12 +++ website/Architecture.md | 9 ++ website/Aspiring Pages.md | 5 ++ website/Attribute.md | 5 ++ website/Authentication.md | 30 ++++++- website/CONFIG.md | 11 +++ website/Command Palette.md | 4 + website/Command.md | 4 + website/Development.md | 2 + website/Document.md | 4 + website/Event.md | 83 ++++++++++++------ website/Extensions.md | 28 +++++- website/Frontmatter.md | 2 + website/Full Text Search.md | 13 ++- website/Install.md | 2 + website/Install/Binary.md | 2 + website/Install/Configuration.md | 4 +- website/Install/Docker.md | 2 + website/Install/Network and Internet.md | 4 +- website/Keyboard Shortcuts.md | 2 + website/LLM Use.md | 44 +++------- website/Library Manager.md | 7 +- website/Library.md | 5 +- website/Library/Development.md | 2 + website/Link.md | 5 ++ website/Linked Mention.md | 39 ++++++++- website/Linked Tasks.md | 28 +++++- website/Live Preview.md | 17 +++- website/Manual.md | 33 +++++-- website/Markdown/Admonition.md | 5 +- website/Markdown/Fenced Code Block.md | 7 +- website/Markdown/Hashtags.md | 5 ++ website/Meta Page.md | 5 ++ website/Metadata.md | 6 +- website/Object Index.md | 7 +- website/Object.md | 5 ++ website/PWA.md | 26 +++++- website/Page Decorations.md | 3 +- website/Page Picker.md | 4 + website/Page Template.md | 5 ++ website/Page.md | 4 + website/Schema.md | 50 +++++++++-- website/Service.md | 17 ++-- website/Share.md | 6 +- website/SilverBullet.md | 1 + website/Slash Command.md | 41 ++++++++- website/Slash Templates.md | 41 ++++++++- website/Space Lua.md | 6 +- website/Space Lua/Lua Integrated Query.md | 4 + website/Space Lua/Widget.md | 101 ++++++++++++++++++++-- website/Space Style.md | 5 ++ website/Space.md | 4 + website/Sync.md | 5 ++ website/TLS.md | 2 + website/Tag.md | 5 ++ website/Task.md | 5 ++ website/Template.md | 52 ++++++++++- website/Transclusions.md | 5 ++ website/Troubleshooting.md | 26 ++++-- website/Vim.md | 2 + 68 files changed, 859 insertions(+), 152 deletions(-) diff --git a/libraries/Library/Std/APIs/Schema.md b/libraries/Library/Std/APIs/Schema.md index 19568322..fa5d2886 100644 --- a/libraries/Library/Std/APIs/Schema.md +++ b/libraries/Library/Std/APIs/Schema.md @@ -1,6 +1,52 @@ -#meta/api +--- +description: Helper functions for building JSON Schema objects in Lua +tags: meta/api +--- -Utilities to succinctly define JSON schema types in Lua. +Helper functions for succinctly defining JSON Schema types in Lua. Used with [[API/tag#tag.define(spec)]] and [[API/config#config.define(key, schema)]]. + +# API + +## schema.string() +Returns `{type = "string"}`. + +## schema.number() +Returns `{type = "number"}`. + +## schema.boolean() +Returns `{type = "boolean"}`. + +## schema.null() +Returns `{type = "null"}`. + +## schema.array(typ) +Returns an array schema with items of the given type. `typ` can be a type string (e.g. `"string"`) or a full schema table. + +Example: + +```lua +schema.array("string") -- {type = "array", items = {type = "string"}} +schema.array { + type = "object", + properties = { + name = {type = "string"} + } +} +``` + +## schema.nullable(typ) +Allows the given type or null. `typ` can be a type string or a schema table. + +## schema.nullableArray(typ) +An array of the given type, or null. + +## schema.func() +Marker for function-typed values. + +## schema.schema() +Marker for schema-typed values. + +# Implementation ```space-lua -- priority: 101 diff --git a/libraries/Library/Std/APIs/Template.md b/libraries/Library/Std/APIs/Template.md index 3fe1a58f..202e5652 100644 --- a/libraries/Library/Std/APIs/Template.md +++ b/libraries/Library/Std/APIs/Template.md @@ -1,6 +1,61 @@ -#meta/api +--- +description: APIs to create and render templates +tags: meta/api +--- -Implements useful template functions +APIs to create templates from strings or pages, and render query collections using templates. + +# API + +## template.new(templateStr, stripIndent) +Creates a template function from a string. The template string can contain `${expression}` placeholders that will be interpolated when the template is called. Conventionally, template strings typically use `[==[` and `]==]` as delimiters. + +If `stripIndent` is `true` or omitted, leading 4-space indentation is stripped from each line. + +Example: + +```lua +-- the `templates` global table is available for custom templates +templates.greet = template.new [==[Hello ${name}!]==] +``` + +Which elsewhere can be used, either directly: + +```lua +${templates.greet {name = "Pete"}} +``` + +or together with `template.each` (see below): + +```lua +${template.each(query[[from tags.page limit 3]], templates.greet)} +``` + +Resulting in something along the lines of `Hello index!Hello CONFIG!...` + + +## template.each(collection, fn) +Iterates over a collection and applies a template to each element, concatenating the results. Commonly used to render query results. + +Example: + +```lua +${template.each(query[[from index.tag "page" limit 3]], template.new [==[ + * [[${name}]] +]==])} +``` + +# Pre-built templates +The `templates` table contains ready-made templates for common query rendering patterns. These are defined in [[^Library/Std/Infrastructure/Query Templates]]. + +* **`templates.pageItem`** — renders a page as `* [[name]]` +* **`templates.fullPageItem`** — renders a page as `* [[name|name]]` (full path) +* **`templates.taskItem`** — renders a task as a togglable `* [state] [[ref]] name` +* **`templates.itemItem`** — renders an item as `* [[ref]] name` +* **`templates.paragraphItem`** — renders a paragraph as `* [[ref]] text` +* **`templates.tagItem`** — renders a tag as `* [[tag:name|#name]]` + +# Implementation ```space-lua -- priority: 50 @@ -22,7 +77,7 @@ end -- Creates a new template function from a string template function template.new(templateStr, stripIndent) -- Preprocess: strip indentation - if stripIndent == nil or strpIndent == true then + if stripIndent == nil or stripIndent == true then local lines = {} local splitLines = string.split(templateStr, "\n") for _, line in ipairs(splitLines) do diff --git a/website/API.md b/website/API.md index e8895c47..c4ce0bc4 100644 --- a/website/API.md +++ b/website/API.md @@ -1,2 +1,10 @@ This describes the APIs available in [[Space Lua]]: -${widgets.subPages("API")} + +## Syscall APIs +${template.each(query[[ from p = tags["api/syscall"] where p.tag == "page" order by p.name ]], templates.pageItem)} + +## Space Lua APIs +${template.each(query[[ from p = tags["api/space-lua"] where p.tag == "page" order by p.name ]], templates.pageItem)} + +## Lua Standard Library +${template.each(query[[ from p = tags["api/lua"] where p.tag == "page" order by p.name ]], templates.pageItem)} diff --git a/website/API/codeWidget.md b/website/API/codeWidget.md index 83ceeaef..2c4f7921 100644 --- a/website/API/codeWidget.md +++ b/website/API/codeWidget.md @@ -1,3 +1,5 @@ +#api/syscall + The Code Widget API provides functions for managing code widgets in the editor. ### codeWidget.refreshAll() diff --git a/website/API/dom.md b/website/API/dom.md index 12836fad..70a3455c 100644 --- a/website/API/dom.md +++ b/website/API/dom.md @@ -1,3 +1,5 @@ +#api/space-lua + An API to easily build DOM objects through the magic of Lua meta tables. # Usage diff --git a/website/API/event.md b/website/API/event.md index d8af53d0..e5a578c3 100644 --- a/website/API/event.md +++ b/website/API/event.md @@ -25,7 +25,7 @@ Example: event.dispatch("custom.event", {message = "Hello"}) -- Event dispatch with timeout and response handling -local responses = event.dispatchEvent("data.request", {id = 123}, 5000) +local responses = event.dispatch("data.request", {id = 123}, 5000) for _, response in ipairs(responses) do print(response) end diff --git a/website/API/service.md b/website/API/service.md index bfaab554..9ac91798 100644 --- a/website/API/service.md +++ b/website/API/service.md @@ -2,7 +2,15 @@ Exposes a simple service registry API leveraged by various parts of SilverBullet, see [[Service]]. -## Example +# Architecture +Services are built on top of [[Event|Events]]. When a service is defined, it registers two event listeners: + +1. `discover:<>` — for service discovery +2. `service:<>` — for invocation + +Discovery broadcasts on the event bus and collects all matches, sorted by priority. Invocation calls the specific service's `run` callback. + +# Example ```space-lua service.define { selector = "greeter-service", @@ -31,7 +39,7 @@ service.define { To invoke: ${service.invokeBestMatch("greeter-service", "Pete")} and ${service.invokeBestMatch("greeter-service", "Hank")} -## API +# API ### service.define(spec) Defines a service matching a selector. @@ -50,5 +58,5 @@ Return value is a list of tables (can be empty) with keys: ### service.invoke(match, data) Invokes a service match (as returned by [[#service.discover(selector, options)]]). -### service.invokeBest(selector, options) +### service.invokeBestMatch(selector, data) Performs a `discover` based on the selector, then immediately performs and `invoke` on the best match (based on priority). \ No newline at end of file diff --git a/website/API/taskState.md b/website/API/taskState.md index 214a9bd6..e33d3e82 100644 --- a/website/API/taskState.md +++ b/website/API/taskState.md @@ -1,4 +1,4 @@ -#maturity/beta +#maturity/experimental #api/space-lua APIs to define [[Task#Custom states]]. diff --git a/website/API/widget.md b/website/API/widget.md index 4a81a664..b6f6ebef 100644 --- a/website/API/widget.md +++ b/website/API/widget.md @@ -1,3 +1,5 @@ +#api/space-lua + APIs to define widgets in SilverBullet, often used through [[Space Lua#Expressions]]. # Widget types @@ -56,3 +58,13 @@ Shortcut for `widget.new { markdown = text }` Shortcut for `widget.new { html = htmlOrDOM }` Usually used in conjunction with [[API/dom]]. + +## widget.htmlBlock(htmlOrDOM) +Shortcut for `widget.new { html = htmlOrDOM, display = "block" }` + +Block-level version of `widget.html`. + +## widget.markdownBlock(text) +Shortcut for `widget.new { markdown = text, display = "block" }` + +Block-level version of `widget.markdown`. Useful for content that needs to render as a block element (lists, tables, headings, etc.). diff --git a/website/Architecture.md b/website/Architecture.md index 7ded8863..60b06c11 100644 --- a/website/Architecture.md +++ b/website/Architecture.md @@ -1,3 +1,5 @@ +#development + Here is a big-picture (conceptual) architecture of SilverBullet: ```excalidraw url:architecture.excalidraw @@ -27,7 +29,14 @@ Syscalls (system calls) are the abstraction used in SilverBullet to cleanly crea [[Event]] ## Datastore +The DataStore is an (IndexedDB-backed) key-value store that lives in the browser. It serves as the local persistence layer for everything the client needs to keep track of: +* **Object index**: All indexed objects (pages, tasks, items, links, tags, etc.) are stored here, enabling fast local queries via [[Space Lua/Lua Integrated Query]]. +* **File cache**: The [[Sync]] engine stores a local copy of all space files, enabling offline access. +* **Configuration**: Runtime configuration and state. +* **Message queue**: An internal message queue (MQ) used for asynchronous operations. + +The DataStore wraps lower-level `KvPrimitives` (IndexedDB operations) in a user-friendly API with `get`, `set`, `delete`, and batch variants. The [[API/datastore]] syscall API exposes this to Space Lua and plugs. The client interacts with the service worker and server primarily via the [[HTTP API]], which exposes CRUD-style operations on files. diff --git a/website/Aspiring Pages.md b/website/Aspiring Pages.md index f0cabeb1..d6988aef 100644 --- a/website/Aspiring Pages.md +++ b/website/Aspiring Pages.md @@ -1,3 +1,8 @@ +--- +description: An aspiring page is a page that does not yet exist, but is already linked to. +tags: glossary +--- + An aspiring page is a [[Page|page]] that does not yet exist, but is already linked to. Aspiring pages appear in the [[Page Picker]] (with a `Create page` hint) as well as in auto complete when creating [[Link]]. \ No newline at end of file diff --git a/website/Attribute.md b/website/Attribute.md index 329a900e..8ba58414 100644 --- a/website/Attribute.md +++ b/website/Attribute.md @@ -1,3 +1,8 @@ +--- +description: A key-value pair attached to a page or object, used for querying and filtering. +tags: glossary +--- + Attribute syntax can contribute additional [[Metadata]] to various [[Object|Objects]], including: * Pages (although the preferred way is [[Frontmatter]]) diff --git a/website/Authentication.md b/website/Authentication.md index 77954abb..39b0b0fa 100644 --- a/website/Authentication.md +++ b/website/Authentication.md @@ -1,13 +1,35 @@ +#getting-started + SilverBullet supports simple authentication for a single user. -By setting the `SB_USER` environment variable with a username:password combination, you enable authentication for a single user. For instance: +# User authentication +Set the `SB_USER` environment variable with a `username:password` combination to enable authentication: ```shell docker run -e SB_USER=pete:1234 ... ``` -Will let `pete` authenticate with password `1234`. +This allows `pete` to log in with password `1234`. When authentication is enabled, SilverBullet shows a login page on first access. -For more options see [[Install/Configuration]]. +# Remember me +The login page has a "Remember me" checkbox. When checked, the session persists across browser restarts. The session duration defaults to 7 days and can be configured: -Alternatively, or in addition, you can also use an [[Authentication Proxy]]. \ No newline at end of file +* `SB_REMEMBER_ME_HOURS`: Sets session duration in hours (default: 168, i.e. 7 days) + +# Lockout protection +To prevent brute-force attacks, SilverBullet locks out clients after too many failed login attempts: + +* `SB_LOCKOUT_LIMIT`: Number of failed attempts before lockout (default: 10) +* `SB_LOCKOUT_TIME`: Duration of lockout in seconds (default: 60) + +# API authentication +For programmatic access via the [[HTTP API]], you can use bearer token authentication: + +* `SB_AUTH_TOKEN`: Sets a token for `Authorization: Bearer ` style authentication + +This is useful for scripts, automation, or integrating SilverBullet with other tools. + +# Authentication proxy +Alternatively, or in addition, you can use an [[Authentication Proxy]] to delegate authentication to an external system (like Authelia, Authentik, or a reverse proxy's built-in auth). This is common in more complex self-hosted setups. + +For all authentication-related configuration options, see [[Install/Configuration#Authentication]]. diff --git a/website/CONFIG.md b/website/CONFIG.md index 94c34439..bb8c3c05 100644 --- a/website/CONFIG.md +++ b/website/CONFIG.md @@ -67,6 +67,17 @@ config.set { # Custom tag definitions (further detailed in [[API/tag#Use cases]]) ```space-lua +tag.define { + name = "glossary", + schema = { + type = "object", + properties = { + description = { type = "string" }, + }, + required = { "description" }, + }, +} + tag.define { name = "person", transform = function(o) diff --git a/website/Command Palette.md b/website/Command Palette.md index 5c65a2d8..bcf93da9 100644 --- a/website/Command Palette.md +++ b/website/Command Palette.md @@ -1,3 +1,7 @@ +--- +description: The searchable popup for running commands. +tags: glossary +--- The Command Palette is used to explore SilverBullet’s numerous [[Command]] as well as execute them. The UI and its operation is largely the same as the [[Page Picker]]‘s, with a few differences: diff --git a/website/Command.md b/website/Command.md index 4657d7a1..b76faa78 100644 --- a/website/Command.md +++ b/website/Command.md @@ -1,3 +1,7 @@ +--- +description: A named action you can invoke from the command palette or bind to a key. +tags: glossary +--- Commands define actions that SilverBullet can perform. They range from simple edit commands, such as `Text: Bold`, but may be more elaborate such as `Page: Rename`. SilverBullet ships with a lot of commands built in, but custom ones can also be defined using [[Space Lua]] and [[Plugs]]. diff --git a/website/Development.md b/website/Development.md index 6229f802..04fab12c 100644 --- a/website/Development.md +++ b/website/Development.md @@ -1,3 +1,5 @@ +#development + SilverBullet development can happen at various level. At its most basic level, you can do a lot using [[Space Lua]]. If this does not give enough power, you can upgrade to [[Plugs]]. If _that_ doesn’t suffice, you can contribute to SilverBullet’s core (see below). diff --git a/website/Document.md b/website/Document.md index a166506d..fb7d02d4 100644 --- a/website/Document.md +++ b/website/Document.md @@ -1,3 +1,7 @@ +--- +description: A non-page file (such as an image, PDF, or other attachment) stored in your space. +tags: glossary +--- While SilverBullet is aimed at primarily text-based content, life can not fully be represented in text always. Therefore, SilverBullet supports documents. Documents, like [[Page]] ultimately are — once again — just files on disk. Using plugs, documents of specific file types can also be viewed and edited. # Uploading diff --git a/website/Event.md b/website/Event.md index f5bf4dd0..5b8bb096 100644 --- a/website/Event.md +++ b/website/Event.md @@ -1,32 +1,63 @@ -SilverBullet has its own event bus. +--- +description: A named signal that plugs and Lua scripts can listen to and react to. +tags: glossary +--- +SilverBullet has its own event bus that allows different parts of the system to communicate. Events are the foundation for much of SilverBullet's extensibility — features like [[Service]], [[Virtual Pages]], widgets, and custom indexing are all built on top of events. -Events can be subscribed to and dispatched via the [[API/event]] API. Other features, such as [[Service]] are built on top of Events. +# Subscribing to events +Use `event.listen` to subscribe to an event: + +```lua +event.listen { + name = "editor:pageLoaded", + run = function(e) + print("Loaded page: " .. e.data.name) + end +} +``` + +The `run` callback receives an event object with a `data` field containing event-specific information. To see what data an event provides, add a `print` call and check the [[Log|logs]]. + +# Dispatching events +You can dispatch your own custom events: + +```lua +event.dispatch("my-custom-event", {message = "Hello!"}) +``` + +Other scripts can then listen for `my-custom-event`. # Built-in events -Here is a list of built-in events (triggered by SilverBullet’s core). -To use them, simply subscribe to them via [[API/event#event.listen(listenerDef)]], and do a `print` to see what data you receive. Alternatively, grep the code base to see exactly where they are triggered. +Here is a list of built-in events triggered by SilverBullet's core: -* `page:click`: user clicks a location on the page -* `page:index`: page has changed and requested to be indexed (used by [[Object]] indexing) -* `editor:complete`: editor completion triggered, returns completion results -* `slash:complete`: slash completion triggered, returns completion results -* `editor:lint`: request to lint, returns errors -* `editor:init`: editor initialized -* `editor:pageLoaded`: page has loaded in the editor -* `editor:pageReloaded`: page reloaded in the editor (e.g. when it was changed on disk) -* `editor:pageSaving`: page is about to save -* `editor:pageSaved`: page has saved -* `editor:pageCreating`: page is creating (can return a page content object) -* `editor:pageModified`: a change was made to the document (real-time) -* `editor:documentSaving`: a document is about to be saved -* `editor:documentSaved`: a document was saved -* `editor:modeswitch`: triggered between vim mode and non-vim mode -* `editor:fold`: code was folded in the editor -* `editor:unfold`: code was unfolded in the editor -* `plugs:loaded`: plugs were loaded -* `cron:secondPassed`: a second has passed (useful to implement cron-like features) -* `hooks:renderTopWidgets`: top widgets have requested to render (return widgets) -* `hooks:renderBottomWidgets`: bottom widgets have requested to render (return widgets) +## Editor events +* `editor:init`: Editor has initialized +* `editor:pageLoaded`: A page has been loaded in the editor +* `editor:pageReloaded`: A page was reloaded (e.g. after being changed on disk) +* `editor:pageSaving`: A page is about to be saved +* `editor:pageSaved`: A page has been saved +* `editor:pageCreating`: A page is being created (can return content — used by [[Virtual Pages]]) +* `editor:pageModified`: A change was made to the document (fires in real-time) +* `editor:documentSaving`: A document (non-page file) is about to be saved +* `editor:documentSaved`: A document was saved +* `editor:modeswitch`: Toggled between [[Vim]] mode and normal mode +* `editor:fold`: Code was folded in the editor +* `editor:unfold`: Code was unfolded in the editor + +## Interaction events +* `page:click`: User clicked a location on the page +* `editor:complete`: Editor completion triggered — return completion results to extend [[Completion]] +* `slash:complete`: Slash completion triggered — return completion results +* `editor:lint`: Lint request — return errors to show in the editor + +## System events +* `page:index`: A page has changed and needs to be indexed (used by [[Object]] indexing) +* `plugs:loaded`: Plugs were loaded +* `cron:secondPassed`: One second has passed (useful for implementing periodic behavior) + +## Widget events +* `hooks:renderTopWidgets`: Top widgets requested to render — return widgets to display above the page content +* `hooks:renderBottomWidgets`: Bottom widgets requested to render — return widgets to display below the page content # All subscribed events Here’s a dynamically generated list of events that this SilverBullet instance has subscribed to, to give a sense of what’s there: @@ -35,3 +66,5 @@ ${query[[ where not _:startsWith("service:") order by _ ]]} + +See [[API/event]] for the full API reference. diff --git a/website/Extensions.md b/website/Extensions.md index db756f36..aadb27c8 100644 --- a/website/Extensions.md +++ b/website/Extensions.md @@ -1,4 +1,26 @@ -There are various ways the functionality of SilverBullet can be extended: +--- +description: A plug or library that adds functionality to SilverBullet. +tags: glossary +--- -* [[Library]] -* [[Plugs]] +There are several ways to extend the functionality of SilverBullet: + +# Libraries +[[Library|Libraries]] are collections of [[Space Lua]] scripts, templates, and pages that you can install into your space via the [[Library Manager]]. They are the primary extension mechanism and the easiest way to add new features. Libraries can define: + +* Custom [[Command|commands]] +* [[Slash Templates]] +* [[Page Template|Page templates]] +* [[API/widget|Widgets]] +* [[Space Style]] customizations +* [[Virtual Pages]] + +Libraries are distributed as SilverBullet spaces themselves (typically via Git repositories), and managed through the [[Library Manager]]. + +# Space Lua +[[Space Lua]] is SilverBullet's embedded scripting language. You can write scripts directly in `space-lua` fenced code blocks on any page. These scripts are active across your entire space and can define functions, commands, widgets, event handlers, and more. + +Space Lua is the foundation that libraries are built on. See [[Space Lua]] for a full guide. + +# Plugs +[[Plugs]] are the lower-level extension mechanism, written in TypeScript and compiled to WebAssembly. SilverBullet's core functionality (editing, indexing, syncing) is itself implemented as plugs. While more powerful than Space Lua, plugs are harder to develop and distribute. Most users will not need to write plugs — Space Lua and libraries cover the vast majority of use cases. diff --git a/website/Frontmatter.md b/website/Frontmatter.md index 55302413..34ee247d 100644 --- a/website/Frontmatter.md +++ b/website/Frontmatter.md @@ -1,5 +1,7 @@ --- +description: A YAML block at the top of a page that sets page-level attributes. status: Complete +tags: glossary --- Frontmatter is a common format to attach additional metadata (data about data) to markdown documents. Many tools support it as a markdown [[Markdown/Extensions|extension]]. diff --git a/website/Full Text Search.md b/website/Full Text Search.md index cec94c85..2920c591 100644 --- a/website/Full Text Search.md +++ b/website/Full Text Search.md @@ -1,3 +1,12 @@ -While, honestly not amazing, SilverBullet does have full-text search support. +Full-text search is not built into SilverBullet's core distribution. It is available as a library you can install. -To use it, run the ${widgets.commandButton("Search Space")} command. \ No newline at end of file +# Search libraries +Two community search libraries are available: +* **[Silversearch](https://github.com/MrMugame/silversearch)** (recommended) — a more capable search implementation +* **[basic-search](https://github.com/silverbulletmd/basic-search)** — a simpler search that was previously built into SilverBullet + +Install either one via the [[Library Manager]]. + +# Tips +* For structured queries over metadata and objects, use [[Space Lua/Lua Integrated Query]] instead — it's much more powerful for querying attributes, tags, and relationships +* The [[Page Picker]] (`Cmd-k` / `Ctrl-k`) also searches page _names_ and can be faster for finding pages you know the name of \ No newline at end of file diff --git a/website/Install.md b/website/Install.md index 0e805536..3c1f613c 100644 --- a/website/Install.md +++ b/website/Install.md @@ -1,3 +1,5 @@ +#getting-started + Excited to use SilverBullet? Here are three ways for you to deploy it. Also have a look at the note on [[#File systems]] at the end. # localhost (desktop, laptop) diff --git a/website/Install/Binary.md b/website/Install/Binary.md index da4aa512..aef6d53b 100644 --- a/website/Install/Binary.md +++ b/website/Install/Binary.md @@ -1,3 +1,5 @@ +#getting-started + SilverBullet is distributed as a single server binary available for the following platforms: * macOS (Intel and Apple Silicon) (platform name “darwin”) diff --git a/website/Install/Configuration.md b/website/Install/Configuration.md index 3d4386b6..56f81955 100644 --- a/website/Install/Configuration.md +++ b/website/Install/Configuration.md @@ -1,3 +1,5 @@ +#getting-started + SilverBullet is primarily configured via environment variables. This page gives a comprehensive overview of all configuration options. You can set these ad-hoc when running the SilverBullet server, or e.g. in your [[Install/Docker|docker-compose file]]. # General configuration @@ -18,7 +20,7 @@ SilverBullet supports basic authentication for a single user. * `SB_USER`: Sets single-user credentials, e.g. `SB_USER=pete:1234` allows you to login with username “pete” and password “1234”. * `SB_AUTH_TOKEN`: Enables `Authorization: Bearer ` style authentication on the [[HTTP API]]. * `SB_LOCKOUT_LIMIT`: Specifies the number of failed login attempt before locking the user out (for a `SB_LOCKOUT_TIME` specified amount of seconds), defaults to `10` -* `SB_LOCKOUT_TIME`: Specifies the amount of time (in seconds) a client will be blocked until attempting to log back in. +* `SB_LOCKOUT_TIME`: Specifies the amount of time (in seconds) a client will be blocked until attempting to log back in, defaults to `60`. * `SB_REMEMBER_ME_HOURS`: Sets the session duration in hours when "Remember me" is checked during login, defaults to 7 days. # Storage diff --git a/website/Install/Docker.md b/website/Install/Docker.md index c07fdc5a..78f2a8c2 100644 --- a/website/Install/Docker.md +++ b/website/Install/Docker.md @@ -1,3 +1,5 @@ +#getting-started + [Docker](https://www.docker.com/) is a convenient and secure way to install server applications either locally or on a server you control. If you don’t have docker already running on your machine and are macOS user, consider giving [OrbStack](https://orbstack.dev/) a try — it’s a super nice docker experience. Conveniently, SilverBullet is published as a [docker image on GHCR](https://github.com/silverbulletmd/silverbullet/pkgs/container/silverbullet). The image comes in two flavors: diff --git a/website/Install/Network and Internet.md b/website/Install/Network and Internet.md index f429c506..17c22def 100644 --- a/website/Install/Network and Internet.md +++ b/website/Install/Network and Internet.md @@ -1,4 +1,6 @@ -Running SilverBullet locally on your machine is nice, but you likely want to access it from elsewhere as well (other machines on your network, your mobile device), perhaps even from outside your home. +#getting-started + +Running SilverBullet locally on your machine is nice, but you likely want to access it from elsewhere as well (other machines on your network, your mobile device), perhaps even from outside your home. > **note** IMPORTANT > To use SilverBullet from anywhere other than localhost, you have to set up [[TLS]]. SilverBullet does not work (other than via localhost) on URLs other than `https://` ones. diff --git a/website/Keyboard Shortcuts.md b/website/Keyboard Shortcuts.md index 69989867..227d611c 100644 --- a/website/Keyboard Shortcuts.md +++ b/website/Keyboard Shortcuts.md @@ -1,3 +1,5 @@ +#customization + SilverBullet uses [CodeMirror](https://codemirror.net) under the hood, which does the majority of the keyboard handling. In addition, it allows to for customization of (most) keys on a per-command basis. When you open the [[Command Palette]], you will see the currently assigned keyboard shortcut(s). # Modifier keys diff --git a/website/LLM Use.md b/website/LLM Use.md index 58a714be..71228d7c 100644 --- a/website/LLM Use.md +++ b/website/LLM Use.md @@ -1,49 +1,27 @@ -**TL;DR:** Please do not (heavily) use LLM-based coding tools to contribute code to the [main SilverBullet code base](https://github.com/silverbulletmd/silverbullet). Also don’t heavily rely on LLMs to contribute to issues or community discussions (except for language support, if you need it). +**TL;DR:** Please apply caution when using LLM-based coding tools to contribute code to the [main SilverBullet code base](https://github.com/silverbulletmd/silverbullet). Please do not heavily rely on LLMs to contribute to issues or community discussions. -The topic of how to deal with (largely) LLM generated contributions comes up from time to time in SilverBullet. Different open source project take different approaches: some allow them because “it’s the future,” some [decidedly do not](https://ziglang.org/code-of-conduct/). After much deliberation, I decided that for now I’ll put SilverBullet in the latter camp, as in: no thank you. +--- -There are two main reasons for this, the first is _moral_, a second more _practical_. +There is a bubble of people that believe a simple prompt given to an LLM will produce work that is consistently good. This not my experience. While LLM-based agents _can_ be skillfully steered into producing good quality work, there is big population of people without these skills that cause a lot of confusion and noise, also in the SilverBullet community. -# The moral reason -I have been open sourcing code for over 25 years. My goals for doing so include helping people solve similar problems that I have, enjoy and benefit from the software I build, to allow them to adapt, improve, change and learn from it, and to build community. I have always distributed code under the most liberal of licenses (usually MIT), and have been lucky enough that those licenses were not exploited. Until recently, when LLMs came around. +From time to time people “contribute” to issues or the community forums with largely LLM generated text and “analysis.” In the best case this results in a lot of text easily detected as LLM slop and ignored, but at worst it contains inaccurate information that simply detracts the conversation or results in investing time in things (e.g. verifying fake bugs) that are simply hallucinated. This is not helping anybody. -Specifically _not_ on my list of goals was allowing companies to take my code (or content in general) as input to a _ridiculously_ resource-intensive (money, energy, cheap labor) algorithm, and have the result be sold back to me in the form of tokens. Yet, here we are. And while some may have the sentiment that this is fine, and perhaps even legal, I’m not too happy about it. +In the context of code contributions, while sloppy work is not unique to LLMs, the pace and ease in which it is produced definitely is. Since the quality of the work produced by LLMs is all over the place, I have to take it upon myself to carefully review every contribution, not knowing what prompts (if any) or level of understanding (if any) was behind it. -There are various areas in my life where I have to make more pragmatic choices, but in my open source work I feel I can afford to take a stand. +With humans, even in an open source setting, you build some level of relationship and trust over time with people. In the SilverBullet community I have a few contributors from whom I’ve seen the work: I know they can be trusted to do great, and I don’t have to zoom in on every single change. This is vital, and is one of the reasons why a project with the scope size of SilverBullet can still be operated by a single person. When I invest time in giving a detailed code review, I think _learning_ can happen. The person on the other end, or so I would like to believe, considers things they hadn’t considered before, learns more about the internal workings of SilverBullet and future directions I have in mind. -Therefore, the first reason to ask you not to contribute to SilverBullet using AI tools is a **moral** one: these tools are built by scraping all text (natural and code) LLM companies can get their hands on (often in sketchy ways), use scarce resources to train and operate them, and disproportionally benefit companies with highly questionable morals. This is not a cause I am interested in associating or supporting in my leisure time. +The ease and pace at which an AI agent produces a full pull request with meticulous sounding description and thousands of lines of code added is impressive. However, reviewing and commenting on this code can take me _hours or even days_ whereas producing it may only have taken _minutes_. A common approach for “drive by” LLM contributors is to simply copy & paste my well-considered comments back into the chatbot and see what happens. -# The practical reason -The second reason is more practical. While there is a bubble of people that claim that the quality of the work produced by LLMs is amazing, this has not been my experience based on using these tools myself and reviewing the work of these tools done by others. Too often, it is _sloppy_. - -From time to time people “contribute” to issues or the community forums with largely LLM generated text. At best it’s just a lot of text easily detected as LLM slop and ignored, at worst it contains inaccurate information that simply detracts the conversation or results in investing time in things that are simply hallucinated. This is not helpful. - -In the context of code contributions, while sloppy work is not unique to LLMs, the pace and ease in which it produces it definitely is. If I would have enough faith in LLMs to either feel I do not have to do code reviews, or I can delegate all reviews to LLMs — this could _hypothetically_ be ok. However, again, this is not my experience. The work produced by LLMs if often bad, and I have little reason to believe that an LLM code review would detect it. - -This means that _I still have to review everything myself._ - -There is an important difference in reviewing code produced by an LLM and a human. - -With humans, even in an open source setting, you build some level of relationship over time. You build trust. In the SilverBullet project I have a few people where I’ve seen their work, I know they can be trusted to do great, and I don’t have to zoom in on every single change. This is great, and is one of the reasons why a project with the scope size of SilverBullet can still be run by a single person. When I invest time in giving a detailed code review, I think _learning_ can happen. The person on the other end, or so I would like to believe, considers things they hadn’t considered before, learns more about the internal workings of SilverBullet, or potentially about how to write code in general. - -This is not the case with an LLM. Sure, in “best practice” scenarios, the LLM output is first reviewed by a skilled human before being submitted for a code review. My lived experience (also observing my own behavior) is that people get lazy quickly. I have had a period in which I was more trusting of AI coding agents and let them go rampant on the SilverBullet code base. I’m still cleaning up the technical debt and mess that it produced in just a few months, _and I completely missed it at the time_. If I cannot trust _myself_ to do this — and I definitely have an incentive — how can I trust random _others_ to do this? - -This means that I have to review every single line of LLM produced code and never get lazy. I have seen cases where a _comment_ produced by the LLM “documented” a certain behavior, and implemented the opposite. I’ve seen LLMs make mistakes a human could not conceivably make. I’ve seen LLMs making code more “robust” by simply littering it with null checks rather than reasoning about why those may actually happen. The level of attention I have to pay in an LLM generated pull request is _higher_ than when it is produced by a human. There is often a disorienting big discrepancy between how it _looks_ and what it actually _is_. - -The ease and pace at which an AI agent produces a full pull request with meticulous sounding description and thousands of lines of code added (many of which are “tests”) is impressive. However, because of reasons listed before, now _my part starts_. I now have to go through this code for _hours or even days_ that only took _minutes_ to produce. - -This is not a fair game, and I’m not here for it. I’m sure your intention is good, but it’s often simply counter productive. +This is not helpful, nor is it fair game. I’ll assume people’s intentions are good, but the reality is that these contributions are simply counter productive. At scale, they can (and do) kill open source projects. # Enforcement I’m not the type of person that is interested in strict rules and policing. My approach is always to focus on explaining the _why_ and giving context so that people can draw their own conclusions. -If I suspect that your contribution is AI generated, I will likely close it pointing to this policy. I may get it wrong sometimes, I’m sorry about that. I’m only human, consider being the same. +If I suspect that your contribution is AI driven, I will likely close it pointing to this policy. I may get it wrong sometimes, I’m sorry about that. I’m only human, consider remaining the same. # What this means for you -So, is the target audience of SilverBullet just #NoAI people, then? No. _Especially_ a tool like SilverBullet is all about self-expression: your notes, your thoughts, your system, your crazy experiments. I know that people use LLMs to write [[Space Lua]] scripts, and I’m happy for them. I know that LLMs help people do things that they could not do before, and even learn things in the process. That’s great. Open source is all about freedom. Do with it what you like, use it as you like. There is a solid [SilverBullet AI library](https://github.com/justyns/silverbullet-ai) if you’re interested. +Tools like SilverBullet is all about self-expression: your notes, your thoughts, your system, your crazy experiments. I know that people use LLMs to write [[Space Lua]] scripts, and I’m happy for them. I know that LLMs help people do things that they could not do before, and even learn things in the process. That’s great. Open source is all about freedom. Do with it what you like, use it as you like. There is a solid [SilverBullet AI library](https://github.com/justyns/silverbullet-ai). -This policy only applies to the SilverBullet code base itself and its community. It is the code that I feel I should be able to understand and own, and the conversations that I decide to spend my time on contributing to. I have to make decisions that keep the project going and sustainable long term, and excessive use of AI tools in contributions puts that at risk. - -I hope that makes sense. +This policy only applies to the SilverBullet code base itself and its community. It is the code that I feel I should be able to understand and own, and the conversations that I decide to spend my time on contributing to. I have to make decisions that keep the project going and sustainable long term, and unproductively leveraging AI tools in contributions puts that at risk. — [[Zef]] diff --git a/website/Library Manager.md b/website/Library Manager.md index e9e726fd..585c8a58 100644 --- a/website/Library Manager.md +++ b/website/Library Manager.md @@ -1,5 +1,8 @@ -#maturity/beta +--- +description: The UI for browsing and importing libraries. +tags: maturity/beta glossary +--- The library manager makes it easy to manage (install, update, remove) [[Library]]. -The library is accessed via the ${widgets.commandButton "Library: Manager"} command. \ No newline at end of file +The library is accessed via the ${widgets.commandButton "Library: Manager"} command. diff --git a/website/Library.md b/website/Library.md index 85845503..6ec076a1 100644 --- a/website/Library.md +++ b/website/Library.md @@ -1,4 +1,7 @@ -#maturity/beta +--- +description: A collection of reusable Space Lua scripts, templates, and pages that can be imported into your space. +tags: maturity/beta glossary +--- SilverBullet is designed to be [[Extensions|extensible]]. In fact, a lot of functionality in SilverBullet is implemented through [[Space Lua]] embedded in [[Meta Page]], other functionality is implemented using [[Plugs]]. diff --git a/website/Library/Development.md b/website/Library/Development.md index 9c2f9106..18a64b4a 100644 --- a/website/Library/Development.md +++ b/website/Library/Development.md @@ -1,3 +1,5 @@ +#development + To develop your own SilverBullet library follow these steps: # Decorate your library with frontmatter diff --git a/website/Link.md b/website/Link.md index 1203a902..ae6dd8ff 100644 --- a/website/Link.md +++ b/website/Link.md @@ -1,3 +1,8 @@ +--- +description: A wiki-link or Markdown link connecting pages in your space. +tags: glossary +--- + In SilverBullet, you can create links to pages or documents inside your space as well as to external resources, using different link formats. # External links diff --git a/website/Linked Mention.md b/website/Linked Mention.md index a8f0f5e6..e6bc602f 100644 --- a/website/Linked Mention.md +++ b/website/Linked Mention.md @@ -1,3 +1,38 @@ -On this site you see a section “Linked Mentions” appear along the bottom of every page that has incoming links. 👇🏻 This section lists all pages that contain a _link to_ the current page. This allows for easy navigation, and may help you discover linked concepts through these links. +--- +description: A backlink reference showing everywhere a page is linked from. +tags: glossary +--- +Linked mentions (also known as backlinks) show all pages that contain a [[Link|link]] to the current page. They appear as a "Linked Mentions" section at the bottom of every page that has incoming links. -More details: [[^Library/Std/Widgets/Widgets]] \ No newline at end of file +# How? +SilverBullet's [[Object Index]] tracks all links between pages. The Linked Mentions widget queries this index to find pages that link _to_ the page you're currently viewing, then displays them with a snippet of the surrounding context. + +This allows for easy navigation and helps you discover connections between concepts through these bi-directional links. + +# Why? +In a traditional notes app, links are one-directional: page A links to page B, but page B has no idea. With linked mentions, every link becomes bi-directional. This means: + +* You can give a person, project, or concept its own page, and the linked mentions section will automatically collect every reference to it +* You discover unexpected connections between ideas +* Your knowledge graph builds itself as you write + +# Configuration +You can enable or disable the Linked Mentions widget in [[CONFIG]]: + +```lua +-- Disable linked mentions widget +config.set("std.widgets.linkedMentions.enabled", false) +``` + +# Programmatic access +You can query linked mentions directly using [[Space Lua/Lua Integrated Query]]: + +```lua +query[[ + from l = tags.link + where l.toPage == "Some Page" + order by l.pageLastModified desc +]] +``` + +See also: [[Link]], [[Linked Tasks]], [[Object/link]] diff --git a/website/Linked Tasks.md b/website/Linked Tasks.md index 05e8cc8f..c1e8960b 100644 --- a/website/Linked Tasks.md +++ b/website/Linked Tasks.md @@ -1,14 +1,34 @@ +--- +description: Tasks that reference a specific page using a link. +tags: glossary +--- + It is a common SilverBullet pattern to give people, groups of people and places dedicated pages so you can easily reference them. It then becomes very convenient to mention these pages elsewhere in your space, and using [[Linked Mention]] you can easily find what _pages_ link back to that page. -The equivalent of this idea the context of [[Task]] is Linked Tasks. These are tasks that _mention_ a particular page. +The equivalent of this idea in the context of [[Task]] is Linked Tasks. These are tasks that _mention_ a particular page. # Example workflow -Let’s say you keep notes of 1-on-1 meetings with people. You have a page for each person where you keep notes for each of your sessions. As you talk to person _A_, something comes up that you need to discuss with person _B_. B _also_ has their own page. What you can do is simply create a task on your note page with _A_ (so you don’t have to context switch) that includes a [[Link|link]] to _B_. +Let's say you keep notes of 1-on-1 meetings with people. You have a page for each person where you keep notes for each of your sessions. As you talk to person _A_, something comes up that you need to discuss with person _B_. B _also_ has their own page. What you can do is simply create a task on your note page with _A_ (so you don't have to context switch) that includes a [[Link|link]] to _B_. + +The next time you open B's page, you'll see the task from your meeting with A listed in the "Linked Tasks" widget at the top. + +# Behind the scenes +The Linked Tasks widget appears at the top of a page and shows all incomplete tasks from _other_ pages that contain a link to the current page. This is powered by a query that finds tasks where `ilinks` (inherited links) includes the current page name. + +When you complete a linked task (by checking the checkbox), the task is updated on its source page — the state change propagates across pages. + +# Configuration +You can enable or disable the Linked Tasks widget via configuration: + +```lua +-- Disable linked tasks widget +config.set("std.widgets.linkedTasks.enabled", false) +``` # Example -Below are two tasks that mention this very page (this is not the general pattern, just for demonstration purposes). Note that the not completed task is listed at the top of this page as well in the “Linked Tasks” widget. +Below are two tasks that mention this very page (this is not the general pattern, just for demonstration purposes). Note that the not completed task is listed at the top of this page as well in the "Linked Tasks" widget. * [ ] [[Linked Tasks]] This is a task * [x] [[Linked Tasks]] This is a completed task -**Implementation:** [[^Library/Std/Widgets/Widgets]] \ No newline at end of file +**Implementation:** [[^Library/Std/Widgets/Widgets]] diff --git a/website/Live Preview.md b/website/Live Preview.md index e11b3e66..7b9bf858 100644 --- a/website/Live Preview.md +++ b/website/Live Preview.md @@ -1,5 +1,16 @@ -SilverBullet uses a “live preview” markdown editor. This mechanism is heavily inspired by [Obsidian’s live preview mode](https://help.obsidian.md/Live+preview+update). +--- +description: The inline rendering of Markdown formatting as you type. +tags: glossary +--- +SilverBullet uses a “live preview” markdown editor. This mechanism is heavily inspired by [Obsidian's live preview mode](https://help.obsidian.md/Live+preview+update). -It reduces visual noise by not constantly showing [[Markdown]] codes such as `[SilverBullet website](https://silverbullet.md)`, only showing the underlying Markdown formatting code when the cursor is placed inside. +It reduces visual noise by not constantly showing [[Markdown]] formatting codes such as `[SilverBullet website](https://silverbullet.md)`, only showing the underlying Markdown formatting when the cursor is placed inside. -In SilverBullet, you can always see the underlying format by moving your cursor “inside.” **Alt-clicking** on any piece of formatted text will move your cursor there and reveal the underlying (markdown) code, or you can reveal it permanently with the `Toggle Markdown Syntax Rendering` command. +# Revealing the source +In SilverBullet, you can always see the underlying format by moving your cursor "inside" any formatted element with the keyboard, or by **Alt-clicking** (or Option-clicking on Mac) on any piece of formatted text. + +# Toggling live preview +If you prefer to see the raw markdown at all times, run the ${widgets.commandButton("Editor: Toggle Markdown Syntax Rendering")} command. This switches between live preview mode and raw markdown mode. + +# Widget rendering +[[Space Lua#Expressions]] (`${...}`) are rendered inline as live widgets. The underlying code is hidden until you move your cursor into the expression. This is what makes SilverBullet pages feel dynamic — queries, templates, and widgets all render seamlessly within the document. diff --git a/website/Manual.md b/website/Manual.md index 26cf9bb2..08f0cea8 100644 --- a/website/Manual.md +++ b/website/Manual.md @@ -1,6 +1,15 @@ Welcome to the wonderful world of SilverBullet. The goal of this manual is to give you a broad sense of how to use this tool and what it’s capable of. However, its full capabilities are yet to be discovered. You too may find new and creative ways to use the various SilverBullet features in ways nobody previously thought of. -However, that is all unlikely to happen unless you understand what SilverBullet can actually do. So let’s give you a bit of a sense. +However, that is all unlikely to happen unless you understand what SilverBullet can actually do. So let's give you a bit of a sense. + +**New here?** Start with the [[Quick Start]], which will walk through the basics in just a few minutes. + +# Guides +Practical walkthroughs for common workflows: + +* [[Guide/Knowledge Base]] — build a personal knowledge base +* [[Guide/Task Management]] — track projects and tasks +* [[Guide/People Notes]] — keep track of people and conversations # Videos ${embed.youtube "https://youtu.be/bb1USz_cEBY"} @@ -14,16 +23,16 @@ ${embed.youtube "https://youtu.be/qkLJ3viVq8I"} * [[CHANGELOG]]: what’s new in SilverBullet? This page will give you the latest details. It’s worth monitoring this page. # Installation and deployment -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 +* [[Authentication]]: Securing your instance * [[TLS]]: the part where we walk through options to expose SilverBullet via HTTPS. +* [[Troubleshooting]]: When things don't go as planned For additional guides, check out [our community guides](https://community.silverbullet.md/c/guides/6). # Core Concepts These are the core concepts used in SilverBullet: - +* [[Glossary]] * [[Space]] * [[Page]] (and [[Meta Page]]) * [[Frontmatter]] @@ -36,7 +45,7 @@ SilverBullet’s UI is minimalist by design. Let’s look at the few UI elements * The [[Top Bar]] contains: * [[Page Namer]] - * [[Index Page]] (the 🏠 button) + * [[Index Page]] (the home button) * [[Page Picker]] * [[Command Palette]] * The main [[Editor]] component contains your currently selected page’s text @@ -52,6 +61,7 @@ SilverBullet’s UI is minimalist by design. Let’s look at the few UI elements * [[Markdown/Fenced Code Block]] * [[Slash Command]] * [[Outlines]] +* [[Completion]] # Navigation The main ways to roam your space, beside following page links, are: @@ -66,14 +76,20 @@ The main ways to roam your space, beside following page links, are: * [[Frontmatter]] * [[Attribute]] * [[Space Lua]] + * [[Space Lua/Standard Library]] + * [[Space Lua/Lua Integrated Query]] + * [[Space Lua/DOM]] + * [[Space Lua/JavaScript Interop]] +* [[Template]] +* [[Virtual Pages]] * [[Library]] -* [[Space Style]] * [[Troubleshooting]] # Customization * [[^Library/Std/Config]] * [[Page Decorations]] * [[Space Style]] +* [[Keyboard Shortcuts]] # Extending SilverBullet SilverBullet’s implementation is built on three things: @@ -82,8 +98,9 @@ SilverBullet’s implementation is built on three things: * A lot of core functionality is implemented in [[Plugs]]. * An increasing amount of additional functionality is now being implemented in “native” [[Space Lua]]. -# Contributing +See [[Extensions]] for an overview. +# Contributing SilverBullet is free and open-source software. You can contribute to it [via Github](https://github.com/silverbulletmd/silverbullet). For some details on how to do this, have a look -at [[Development]]. +at [[Development]]. Another way to contribute is through [[Funding]]. diff --git a/website/Markdown/Admonition.md b/website/Markdown/Admonition.md index 91618cc7..62214bc2 100644 --- a/website/Markdown/Admonition.md +++ b/website/Markdown/Admonition.md @@ -1,4 +1,7 @@ -#level/intermediate +--- +description: A callout block rendered from a special blockquote syntax. +tags: level/intermediate glossary +--- Silverbullet supports [admonitions](https://github.com/community/community/discussions/16925) using GitHub syntax (`note` and `warning`). diff --git a/website/Markdown/Fenced Code Block.md b/website/Markdown/Fenced Code Block.md index 3cecd7c3..260289ab 100644 --- a/website/Markdown/Fenced Code Block.md +++ b/website/Markdown/Fenced Code Block.md @@ -1,3 +1,8 @@ +--- +description: A triple-backtick block that can render widgets, queries, or syntax-highlighted code. +tags: glossary +--- + Blocks use the fenced code block notation of [[Markdown]], and assign special behavior to it. The general syntax is: @@ -11,4 +16,4 @@ These are the block types that ship with SilverBullet, but [[Plugs]] can define * `space-lua`: [[Space Lua]] * `space-style`: [[Space Style]] -The fenced code block syntax is also used to get [[Markdown/Syntax Highlighting]] for numerous programming languages. \ No newline at end of file +The fenced code block syntax is also used to get [[Markdown/Syntax Highlighting]] for numerous programming languages. diff --git a/website/Markdown/Hashtags.md b/website/Markdown/Hashtags.md index ff7e6e17..6c2179aa 100644 --- a/website/Markdown/Hashtags.md +++ b/website/Markdown/Hashtags.md @@ -1,3 +1,8 @@ +--- +description: "An inline #tag that annotates a page or object for categorisation and querying." +tags: glossary +--- + Hashtag syntax (`#my-tag`) can be used to explicitly assign a [[Tag]] to an [[Object]]. # Scope rules diff --git a/website/Meta Page.md b/website/Meta Page.md index 5e12dea6..62560899 100644 --- a/website/Meta Page.md +++ b/website/Meta Page.md @@ -1,3 +1,8 @@ +--- +description: "A page tagged with #meta that serves as tooling (configuration, extensions, templates) rather than regular content." +tags: glossary +--- + Meta pages are pages not core to your content, but function as a way to configure, or extend your [[Space]]. You can think of them as “tooling” pages. The most obvious examples are part of SilverBullet’s [[^Library/Std]] library and include generally useful [[Library/Std/Infrastructure/Slash Templates]]. diff --git a/website/Metadata.md b/website/Metadata.md index 4412b3c5..cac4854a 100644 --- a/website/Metadata.md +++ b/website/Metadata.md @@ -1,5 +1,5 @@ -Metadata is data about data. Most [[Object]] have a set of default attributes that can be augmented in a few additional ways: +Metadata is data about data. Most [[Object|objects]] have a set of default attributes that can be augmented in a few additional ways: * [[Tag]]: to tag the object (and add to the `tags` attribute directly) -* [[Frontmatter]]: at the top of [[Page]], a [[YAML]] encoded block can be used to define additional attributes to a page -* [[Attribute]] syntax +* [[Frontmatter]]: at the top of a [[Page]], a [[YAML]] encoded block defines additional attributes +* [[Attribute]] syntax: inline key-value pairs within your content diff --git a/website/Object Index.md b/website/Object Index.md index 251bd37d..8eaf758d 100644 --- a/website/Object Index.md +++ b/website/Object Index.md @@ -1,3 +1,8 @@ +--- +description: The local index that makes objects queryable. +tags: glossary +--- + The Object Index stores [[Object|Objects]] found in your [[Space]]. You interact with it in a few ways: @@ -39,4 +44,4 @@ Entry points are: * [[API/index#index.tag(name)]], e.g.: `index.tag "page"` * `tags.*`: as a convenience — `tags.page` is equivalent to `index.tag "page"` -If a `metatable` is defined for a particular tag with [[API/tag#tag.define(spec)]], the metatable is set for each object for the tag. \ No newline at end of file +If a `metatable` is defined for a particular tag with [[API/tag#tag.define(spec)]], the metatable is set for each object for the tag. diff --git a/website/Object.md b/website/Object.md index f684794c..af8a77d3 100644 --- a/website/Object.md +++ b/website/Object.md @@ -1,3 +1,8 @@ +--- +description: A structured, queryable unit of data extracted from your pages (e.g. tasks, items, paragraphs). +tags: glossary +--- + SilverBullet automatically maintains an [[Object Index]] extracted from all [[Markdown]] [[Page|pages]] in your [[Space|Space]]. Objects are a feature that powers a lot of SilverBullet functionality, including the [[Page Picker]], [[Linked Mention|Linked Mentions]] and many others. They can also be queried by the user directly, typically via [[Space Lua/Lua Integrated Query]]. diff --git a/website/PWA.md b/website/PWA.md index c82557b7..fb9c8283 100644 --- a/website/PWA.md +++ b/website/PWA.md @@ -1,3 +1,25 @@ -SilverBullet is developed as a [Progressive Web App](https://web.dev/progressive-web-apps/), a web application that is fully offline capable. +--- +description: "SilverBullet's installable web-app mode for offline access and native-like experience." +tags: glossary +--- -After your first load and sync, (practically) all functionality is available even without a network connection. \ No newline at end of file +SilverBullet is built as a [Progressive Web App](https://web.dev/progressive-web-apps/) (PWA) — a web application that works fully offline. + +# What the PWA gives you +* **Offline access**: After your first load and sync, all functionality is available without a network connection. Edits are stored locally and synced when you're back online. +* **App-like experience**: Install SilverBullet as a standalone app on your device — it gets its own window, icon, and feels like a native application. +* **Instant loading**: Since your content is synced to your browser's local storage, pages load instantly without network requests. + +# How to install +* **Chrome / Edge / Chromium-based**: Click the install icon in the address bar, or use the browser menu to "Install SilverBullet" +* **Safari (iOS / macOS)**: Use "Add to Home Screen" from the share menu +* **Android**: Use "Add to Home Screen" or "Install app" from the browser menu + +Once installed, SilverBullet appears in your app launcher / dock / home screen like any other app. + +# How offline works +SilverBullet's [[Sync]] engine keeps a full copy of your space in the browser's IndexedDB. When online, changes are continuously synced between the browser and the server. When offline, you work against the local copy. On reconnection, the sync engine reconciles any changes. + +A service worker caches the application code itself, so even the SilverBullet UI loads without a network connection. + +See also: [[Sync]], [[Architecture]] diff --git a/website/Page Decorations.md b/website/Page Decorations.md index 2041b603..c1c0fd5d 100644 --- a/website/Page Decorations.md +++ b/website/Page Decorations.md @@ -1,5 +1,6 @@ --- -tags: maturity/beta +description: Visual customization (icons, prefixes, CSS) applied to pages matching certain criteria. +tags: maturity/beta glossary pageDecoration: prefix: "🎄 " disableTOC: true diff --git a/website/Page Picker.md b/website/Page Picker.md index 542727e8..add3bf4b 100644 --- a/website/Page Picker.md +++ b/website/Page Picker.md @@ -1,3 +1,7 @@ +--- +description: The quick-open dialog for navigating to any page. +tags: glossary +--- The page picker has two main functions: 1. Enables quick navigation between [[Page]] diff --git a/website/Page Template.md b/website/Page Template.md index b2bea47c..e34fa1b0 100644 --- a/website/Page Template.md +++ b/website/Page Template.md @@ -1,3 +1,8 @@ +--- +description: A template used to pre-populate new pages. +tags: glossary +--- + Page templates can be used to automate or simplify the creation of pages based on a template. # Creating a page template diff --git a/website/Page.md b/website/Page.md index 62d9a17b..3c0674b9 100644 --- a/website/Page.md +++ b/website/Page.md @@ -1,3 +1,7 @@ +--- +description: A single Markdown document in your space. +tags: glossary +--- 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 [[Names#Rules]]. diff --git a/website/Schema.md b/website/Schema.md index 4ba57dca..8bb796d2 100644 --- a/website/Schema.md +++ b/website/Schema.md @@ -1,17 +1,49 @@ -SilverBullet relies on [JSON Schema](https://json-schema.org) for various types of validation, specifically: +--- +description: A definition that validates and constrains the shape of object attributes. +tags: glossary +--- -* [[Tag#Custom tags]] -* [[^Library/Std/Config]] options +SilverBullet uses [JSON Schema](https://json-schema.org) for validation of structured data. Schemas ensure that [[Frontmatter]] attributes, [[Tag#Custom tags|custom tag]] fields, and configuration options conform to expected types and shapes. -Often these schemas are encoded using [[Space Lua]], so take the shape of: +# Where schemas are used +## Custom tag definitions +When you define a custom tag with `tag.define`, you can provide a schema that describes the expected attributes. SilverBullet validates objects against this schema and surfaces errors in the editor: ```lua -local schema = { - type = "object", - properties = { - -- ... +tag.define { + name = "contact", + schema = { + type = "object", + properties = { + email = schema.string(), + phone = schema.nullable("string"), + priority = schema.number(), + } } } ``` -There are is the [[^Library/Std/APIs/Schema]] API for convenience. \ No newline at end of file +Pages or objects tagged with `#contact` will be validated against this schema — if a field has the wrong type, you'll see a lint warning in the editor. + +## Configuration definitions +The `config.define` function uses schemas to validate configuration values: + +```lua +config.define("myLibrary.config", { + type = "object", + properties = { + enabled = schema.boolean(), + maxItems = schema.number(), + } +}) +``` + +This ensures that `config.set("myLibrary.config", ...)` only accepts values matching the schema. + +# Schema helper functions +The [[^Library/Std/APIs/Schema]] library provides convenience functions like `schema.string()`, `schema.number()`, `schema.array(typ)`, etc. for building JSON Schema objects in Lua. See the API page for the full list. + +# How validation surfaces +When schema validation fails for page and attributes, SilverBullet shows the error as a lint warning in the editor. + +See also: [[Tag#Custom tags]], [[API/jsonschema]], [[API/config]] diff --git a/website/Service.md b/website/Service.md index 6b299e34..cc0b5ce9 100644 --- a/website/Service.md +++ b/website/Service.md @@ -1,14 +1,9 @@ -The SilverBullet service bus is an extension mechanism built into SilverBullet. +The SilverBullet service bus is an extension mechanism for defining and discovering pluggable behavior. It lets you register named services that can be discovered and invoked by other parts of SilverBullet or your own scripts. This enables a plugin-like architecture where multiple implementations can compete for the same operation, with the best match winning. # Concepts -* Discovery: the process of discovering available services based on a _selector_. -* Selector: a string (possibly with a wildcard `*`) used to advertise as well as discover services. -* Service: defined via [[API/service#service.define(spec)]]), implements a service advertised via a selector. -* Invocation: running a discovered service. +* **Service**: A named handler defined via `service.define`. It advertises itself under a _selector_ and provides a `run` callback. +* **Selector**: A string used to advertise and discover services. Can contain wildcards (e.g. `export:*`). +* **Discovery**: The process of finding all services matching a selector. Each service's `match` function determines if it applies and at what priority. +* **Invocation**: Running a discovered service's `run` callback. -# Architecture -Services are an abstraction built on top of [[Event]]. When a new service is defined, it registers itself listening to the `discover:<>` event (to be discovered), and under `service:<>` to be invoked. - -Service discovery happens by broadcasting an event on the event bus with the given selector, returning a list of services that are a match, ordered by (self assigned) priority. One (or all) of these services can then be invoked based on their returned ID. - -See [[API/service]] for API details. \ No newline at end of file +See [[API/service]] for more information on how to use and define your own services. diff --git a/website/Share.md b/website/Share.md index 5126d91a..681d52ad 100644 --- a/website/Share.md +++ b/website/Share.md @@ -1,5 +1,7 @@ -#maturity/beta - +--- +description: The mechanism for publishing or sharing individual pages. +tags: maturity/beta glossary +--- SilverBullet is aimed for single-user, private use. Nevertheless, many have the need to _share_ some content kept in SilverBullet with the outside world: to push content out, pull it in, or even sync between different locations. This is where SilverBullet _share_ functionality comes in. **Note:** If you are interested in one-off ways to get content out, have a look at [[Export]]. diff --git a/website/SilverBullet.md b/website/SilverBullet.md index 9cfc9cb5..6d755599 100644 --- a/website/SilverBullet.md +++ b/website/SilverBullet.md @@ -71,6 +71,7 @@ Learn more about SilverBullet’s technical [[Architecture]]. SilverBullet has been in development since early 2022, but is ever evolving. The current iteration is **SilverBullet v2**. We had a little bit of a reboot, rebuilding some of the foundations, and replacing some of the previous ([v1](https://v1.silverbullet.md)) features. # What’s next? +* [[Quick Start]]: Get up and running in five minutes. * [[Manual]]: SilverBullet’s official manual. * [[CHANGELOG]]: we’re in active development, so things change rapidly. Watch this page to keep up. * [Community](https://community.silverbullet.md): join our community: ask questions, share your experiences. diff --git a/website/Slash Command.md b/website/Slash Command.md index 9ebe5bbb..17c4b196 100644 --- a/website/Slash Command.md +++ b/website/Slash Command.md @@ -1,6 +1,39 @@ -Slash commands are quick ways to perform repetitive tasks. 99% of the time this will mean using a [[^Library/Std/Infrastructure/Slash Templates]], but you can also create them in a more low-level way using [[Space Lua#Slash commands]]. +--- +description: "A /-triggered shortcut in the editor for inserting content or running actions." +tags: glossary +--- +Slash commands are quick ways to perform repetitive tasks. You trigger them by typing `/` in your text (after whitespace) followed by the command name — autocompletion will help you find the right one. -# Invoking a slash command -You can trigger a slash command by typing a `/` in your text (after some white space) followed by its name (this will auto complete). +# Built-in slash commands +[[^Library/Std#Slash templates]] provides many useful ones out of the box. -Technically, no slash commands ship with SilverBullet directly. However, you can easily add useful ones via [[Library]]. +**Editing** +* `/h1`, `/h2`, `/h3`, `/h4` — convert the current line into a heading of the given level +* `/task` — convert the current line into a task (`* [ ] ...`) +* `/frontmatter` — insert a YAML frontmatter block at the top of the page +* `/space-lua` — insert a `space-lua` fenced code block + +**Dates** +* `/today` — insert today's date (e.g. `2026-03-04`) +* `/yesterday` — insert yesterday's date +* `/tomorrow` — insert tomorrow's date + +# Slash templates +Most slash commands are implemented as [[Slash Templates]] — pages tagged with `#meta/template/slash` whose content is inserted at the cursor. The standard library includes slash templates for: + +* `/query` — insert a LIQ query block +* `/lua-query` — insert a Lua query expression +* `/code` — insert a fenced code block +* `/table` — insert a Markdown table +* `/hr` — insert a horizontal rule +* `/note-admonition`, `/warning-admonition`, `/success-admonition`, `/danger-admonition` — insert admonition blocks +* `/tpl` — insert a template expression +* `/func` — insert a Lua function definition +* `/lua-command` — insert a command definition +* `/lua-slash-command` — insert a slash command definition + +# Defining your own +There are two ways to create custom slash commands: + +1. **Slash templates** (recommended): Create a page tagged `#meta/template/slash`. See [[Slash Templates]] for details. +2. **`slashCommand.define`**: For slash commands that need logic beyond simple text insertion. See [[API/command#slashCommand.define(spec)]]. diff --git a/website/Slash Templates.md b/website/Slash Templates.md index 91f7e425..a8bea7de 100644 --- a/website/Slash Templates.md +++ b/website/Slash Templates.md @@ -1 +1,40 @@ -See [[^Library/Std/Infrastructure/Slash Templates]] \ No newline at end of file +--- +description: Templates invoked via slash commands to insert pre-defined content. +tags: glossary +--- +Slash templates are a quick way to define [[Slash Command|slash commands]] that insert templated content at the cursor position. They are defined as pages tagged with `#meta/template/slash`. + +# Creating a slash template +1. Create a new page. The last component of the page name (after the `/` if any) will be used as the slash command's name. For example, a page named `Library/Slash Template/action-items` creates a `/action-items` slash command. +2. Tag the page with `#meta/template/slash` in its [[Frontmatter]]. +3. Write the template content in the page body. Lua directives (`${...}`) are supported and will be evaluated when the template is inserted. + +## Example +A page named `Library/Slash Template/action-items` with this content: + +~~~ +--- +tags: meta/template/slash +description: Insert a standard action items section +--- +# Action items +* [ ] |^| +~~~ + +Creates a `/action-items` slash command that inserts an action items section. + +# Configuration +You can configure these optional [[Frontmatter]] keys: + +* `description`: The description shown in the slash command completion menu +* `priority`: Higher priority commands appear earlier in the list +* `onlyContexts` (advanced): Only show the command in certain AST node contexts +* `exceptContexts` (advanced): Show the command everywhere _except_ in these AST node contexts + +# Currently active slash templates +${template.each(query[[ + from index.tag "meta/template/slash" + where _.tag == "page" +]], templates.fullPageItem)} + +See also: [[Slash Command]], [[Template]], [[Page Template]] diff --git a/website/Space Lua.md b/website/Space Lua.md index e7f14c05..bb81badc 100644 --- a/website/Space Lua.md +++ b/website/Space Lua.md @@ -1,3 +1,7 @@ +--- +description: "SilverBullet's embedded Lua scripting environment for extending functionality." +tags: glossary +--- Space Lua is a custom dialect and implementation of the [Lua programming language](https://lua.org/), embedded in SilverBullet. It aims to be a largely complete Lua implementation, but adds a few non-standard features while remaining syntactically compatible with “real” Lua. In its essence, Space Lua adds two features to SilverBullet’s [[Markdown]] language: @@ -29,7 +33,7 @@ Your `space-lua` definitions are constantly being indexed as part of the [[Objec When your client boots, or if you explicitly run the `System: Reload` command, all these scripts are executed in sequence. -It is possible to **control load order** of space lua scripts using the special `-- priority: ` comment in Space Lua code. For instance: +It is possible to **control load order** of Space Lua scripts using the special `-- priority: ` comment in Space Lua code. For instance: ```space-lua -- priority: 10 diff --git a/website/Space Lua/Lua Integrated Query.md b/website/Space Lua/Lua Integrated Query.md index 7b439dbf..5b8269e4 100644 --- a/website/Space Lua/Lua Integrated Query.md +++ b/website/Space Lua/Lua Integrated Query.md @@ -1,3 +1,7 @@ +--- +description: A Lua-embedded query syntax for selecting and transforming objects. +tags: glossary +--- Lua Integrated Query (LIQ) is a SilverBullet specific Lua extension. It adds a convenient query syntax to the language in a backwards compatible way. It does so by overloading Lua’s default function call + single argument syntax when using `query` as the function call. As a result, Lua programs using LIQ are still syntactically valid Lua. The syntax for LIQ is `query[[my query]]`. In regular Lua `[[my query]]` is just another way of writing `"my query"` (it is an alternative string syntax). Function calls that only take a string argument can omit parentheses, therefore `query[[my query]]` is equivalent to `query("my query")`. diff --git a/website/Space Lua/Widget.md b/website/Space Lua/Widget.md index 194f6d39..4c12333c 100644 --- a/website/Space Lua/Widget.md +++ b/website/Space Lua/Widget.md @@ -1,17 +1,42 @@ +--- +description: A rendered UI component (markdown or HTML). +tags: glossary +--- The `${lua expression}` syntax can be used to implement custom widgets. If the Lua expression evaluates to a simple string, it will live preview as that string rendered as markdown. However, if the expression returns a `widget.new`-generated result value, you can do some fancier stuff. -To render a widget, call `widget.new` with a[text](https://meet.google.com/dtz-nbtq-wwf)ny of the following keys: +# Widget types +To render a widget, call `widget.new` with any of the following keys: * `markdown`: Renders the value as markdown -* `html`: Renders a HTML string as a widget. This is somewhat brittle. Therefore, it’s preferred to use the [[^Library/Std/APIs/DOM]] API. +* `html`: Renders an HTML string or DOM element as a widget * `display`: Render the value either `inline` or as a `block` (defaults to `inline`) +* `cssClasses`: Array of CSS class names to add to the widget container -For convenience there are `widget.markdown` and `widget.html` wrappers available, see below for examples. +# Convenience functions +For common cases, use these shortcuts instead of `widget.new` directly: -## Markdown widgets +| Function | Description | +|---|---| +| `widget.markdown(md)` | Inline markdown widget | +| `widget.markdownBlock(md)` | Block-level markdown widget | +| `widget.html(html)` | Inline HTML widget | +| `widget.htmlBlock(html)` | Block-level HTML widget | -## DOM widgets -To render a custom HTML-based widget, use the [[^Library/Std/APIs/DOM]] API: +# Markdown widgets +The simplest widget type renders markdown: + +```lua +${widget.markdown("**Bold** and *italic* text")} +``` + +For block-level content (like lists or tables), use `widget.markdownBlock`: + +```lua +${widget.markdownBlock("## A heading\n* Item 1\n* Item 2") +``` + +# HTML and DOM widgets +For full control over the rendered output, use HTML widgets with the [[Space Lua/DOM|DOM builder API]]: ```space-lua function marquee(text) @@ -33,5 +58,67 @@ We can combine this with some [[Space Style]] to style it: } ``` -Now, let’s use it (try clicking): +Now, let's use it (try clicking): ${marquee "Finally, marqeeeeeee!"} + +# Built-in widgets +The standard library provides several pre-built widgets in the `widgets` table: + +## Buttons +* `widgets.button(text, callback)` — a simple button that runs the callback when clicked +* `widgets.commandButton(commandName)` — a button for a command (button text is the command name) +* `widgets.commandButton(text, commandName)` — a button for a command with custom text +* `widgets.commandButton(text, commandName, args)` — a button for a command with arguments + +Example: +${widgets.button("Hello", function() + editor.flashNotification "Hi there!" +end)} + +${widgets.commandButton("System: Reload")} + +## Sub-pages widget +* `widgets.subPages(pageName?)` — renders a list of sub-pages (pages with the given prefix). Defaults to the current page. + +## Top and bottom widgets +These render automatically on every page and can be configured: + +* **Table of contents** — shows a table of contents at the top of the page +* **Linked mentions** — shows pages that link to the current page at the bottom +* **Linked tasks** — shows incomplete tasks that mention the current page at the top + +Configure them in your [[^Library/Std/Config]] page: + +```lua +-- Disable TOC altogether +config.set("std.widgets.toc.enabled", false) +-- Only render a TOC when there's >= 5 headers +config.set("std.widgets.toc.minHeaders", 5) +-- Disable linked mentions +config.set("std.widgets.linkedMentions.enabled", false) +-- Disable linked tasks +config.set("std.widgets.linkedTasks.enabled", false) +``` + +# Embed widgets +The `embed` namespace provides widgets for embedding external content: + +* `embed.youtube(url)` — embeds a YouTube video +* `embed.peertube(url)` — embeds a PeerTube video +* `embed.vimeo(url)` — embeds a Vimeo video + +# Creating custom top/bottom widgets +You can add your own widgets to the top or bottom of every page by listening to the rendering events: + +```lua +event.listen { + name = "hooks:renderTopWidgets", + run = function(e) + return widget.new { + markdown = "This appears at the top of every page!" + } + end +} +``` + +See also: [[Space Lua/DOM]], [[API/widget]], [[API/dom]] diff --git a/website/Space Style.md b/website/Space Style.md index 43472b76..a63e1565 100644 --- a/website/Space Style.md +++ b/website/Space Style.md @@ -1,3 +1,8 @@ +--- +description: Custom CSS applied across your space via a special page. +tags: customization glossary +--- + Space Style is [[Space Lua]]’s stylish sibling. It enables you to add your own styling to SilverBullet with `space-style` [[Markdown/Fenced Code Block]]. 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/Space.md b/website/Space.md index 1338e70c..59a9a99c 100644 --- a/website/Space.md +++ b/website/Space.md @@ -1,3 +1,7 @@ +--- +description: The top-level folder of Markdown files, assets, and configuration that SilverBullet serves. +tags: glossary +--- A _space_ is SilverBullet terminology for a workspace, or project, or instance. [Obsidian](https://obsidian.md/) calls this a vault, [LogSeq](https://logseq.com/) calls it a graph. You may think of it as a [[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. diff --git a/website/Sync.md b/website/Sync.md index 20738621..64b6e698 100644 --- a/website/Sync.md +++ b/website/Sync.md @@ -1,3 +1,8 @@ +--- +description: The bidirectional synchronisation between the client's local store and the server. +tags: glossary +--- + SilverBullet is an offline-first web application. Therefore it keeps a copy of your space locally in your browser. It implements a sync engine to continuously keep this local copy in sync with the server (for technical details, see [[Architecture]]). Sync happens: diff --git a/website/TLS.md b/website/TLS.md index bbd56552..cda8009f 100644 --- a/website/TLS.md +++ b/website/TLS.md @@ -1,3 +1,5 @@ +#getting-started + SilverBullet relies on a few advanced browser features to operate (specifically service workers, crypto APIs and clipboard APIs). These features are _only_ enabled by browsers when websites are accessed via `http://localhost` or via [TLS](https://en.wikipedia.org/wiki/Transport_Layer_Security), that is — a `https://` URL. This is not a limitation imposed by SilverBullet, it is a restriction encoded in web standards. Therefore, to use SilverBullet you need to either access it via `localhost` or put a TLS certificate on it. diff --git a/website/Tag.md b/website/Tag.md index df119920..7f383eba 100644 --- a/website/Tag.md +++ b/website/Tag.md @@ -1,3 +1,8 @@ +--- +description: A label applied to objects for grouping and querying. +tags: glossary +--- + Tags in SilverBullet are used to encode types of [[Object|Objects]], they’re similar to tables in relational databases, or classes in object-oriented programming. Every [[Object]] has a main `tag`, which signifies the type of object being described. In addition, any number of additional tags can be assigned as well via the `tags` attribute. You can use either the main `tag` or any of the `tags` as query sources in [[Space Lua/Lua Integrated Query]]. diff --git a/website/Task.md b/website/Task.md index 9d632270..e67e87d1 100644 --- a/website/Task.md +++ b/website/Task.md @@ -1,3 +1,8 @@ +--- +description: A checkbox item tracked as a queryable object. +tags: glossary +--- + The task notation syntax is a [[Markdown]] extension to write down tasks. Its most basic form is: diff --git a/website/Template.md b/website/Template.md index 97a777c9..740799b7 100644 --- a/website/Template.md +++ b/website/Template.md @@ -1,3 +1,51 @@ -A template in SilverBullet is simply a page or string using [[Space Lua#Expressions]]. +--- +description: Reusable content with placeholder expressions, used for page creation, slash commands, and more. +tags: glossary +--- +A template in SilverBullet is a string that contains `${expression}` placeholders, which get evaluated using [[Space Lua]]. Templates are a mechanism for dynamically rendering content in your pages. -They’re typically used to dynamically render parts of pages using [[Space Lua]] and in [[Page Template]] and [[Slash Templates]]. \ No newline at end of file +# Creating templates +Use `template.new` to create a template function from a string. By convention, template strings use `[==[` and `]==]` as delimiters: + +```lua +templates.greet = template.new[==[Hello, ${name}!]==] +``` + +Call the template with a table of values: + +```lua +${templates.greet {name = "World"}} +``` + +# Rendering collections with template.each +The most common pattern is using `template.each` to render a list of objects: + +```lua +template.each(query[[ + from index.tag "page" + order by lastModified desc + limit 5 +]], templates.pageItem) +``` + +`template.each` iterates over the collection and applies the template to each item, concatenating the results. + +# Pre-built templates +The standard library provides several commonly used templates in the `templates` table: + +| Template | Description | +|---|---| +| `templates.pageItem` | Renders a page as `* [[pageName]]` | +| `templates.fullPageItem` | Similar to `pageItem` but rendering the full page name (including folders) | +| `templates.taskItem` | Renders a task as a togglable checkbox item with a link to its source so that it can update | +| `templates.itemItem` | Renders a list item with a link to its source | +| `templates.paragraphItem` | Renders a paragraph with a link to its source | +| `templates.tagItem` | Renders a tag as a linked hashtag | + +# Page templates +[[Page Template|Page templates]] are pages tagged with `#meta/template/page`. They serve as blueprints for creating new pages — you can configure them with suggested names, keyboard shortcuts, and commands. + +# Slash templates +[[Slash Templates]] are pages tagged with `#meta/template/slash`. They define [[Slash Command|slash commands]] that insert templated content at the cursor position. The last component of the page name becomes the slash command name. + +See also: [[API/template]], [[Page Template]], [[Slash Templates]], [[Space Lua]] \ No newline at end of file diff --git a/website/Transclusions.md b/website/Transclusions.md index aff06e23..1b215ab0 100644 --- a/website/Transclusions.md +++ b/website/Transclusions.md @@ -1,3 +1,8 @@ +--- +description: Inline embedding of one page's content inside another. +tags: glossary +--- + Transclusions are an extension of the [[Markdown]] syntax enabling inline embedding of content. The general syntax is `![[path]]`. Two types of transclusions are currently supported: diff --git a/website/Troubleshooting.md b/website/Troubleshooting.md index fa41256d..7325d6f0 100644 --- a/website/Troubleshooting.md +++ b/website/Troubleshooting.md @@ -1,20 +1,34 @@ -Running into trouble? Sorry to hear it. Let’s figure this out. +#getting-started -Here are some things you can try when things don’t work, if you’re still stuck — ask the [community for help](https://community.silverbullet.md/). +Running into trouble? Sorry to hear it. Let's figure this out. + +Here are some things you can try when things don't work. If you're still stuck — ask the [community for help](https://community.silverbullet.md/). The starting point is always [[Log|Logs]] to see if you see anything suspicious. # Disable features Depending on the situation you may (temporarily) disable various client features by appending any of the following to any SilverBullet URL (e.g. `http://localhost:3000/?disableSpaceLua=1`): + * `?disableSync=1` disables synchronization with the server * `?disableSpaceLua=1` disables loading of all [[Space Lua]] scripts * `?disableSpaceStyle=1` disables loading of all [[Space Style]] * `?disablePlugs=1` disables loading of all non built-in [[Plugs]] -# Client reset -If all else fails, you may try to perform a full client reset, simply add `?resetClient=1` to any SilverBullet URL. +These can be combined: `?disableSpaceLua=1&disableSpaceStyle=1` -This will do the following: +# Client reset +If all else fails, you can perform a full client reset by adding `?resetClient=1` to any SilverBullet URL. + +This will: 1. Confirm you want to perform a full client reset 2. Wipe all data stored locally in your browser (IndexedDB, unregister the service worker) -3. Reload the client initiating a full resync +3. Reload the client, initiating a full resync + +> **warning** Warning +> A client reset wipes your local cache. Any unsynced local changes will be lost. Make sure your server is accessible before resetting, so the client can resync. + +# Server-side debugging +* `SB_HTTP_LOGGING`: Set this environment variable to enable HTTP request logging +* `SB_LOG_PUSH`: Set this to ask clients to push their logs to the server + +See [[Install/Configuration]] for all configuration options. diff --git a/website/Vim.md b/website/Vim.md index b594e447..dbf2b195 100644 --- a/website/Vim.md +++ b/website/Vim.md @@ -1,3 +1,5 @@ +#customization + SilverBullet has a basic Vim mode. You can toggle it using the ${widgets.commandButton("Editor: Toggle Vim Mode")} command. In addition, it supports various ex commands that you can run as you would expect, for instance: `:imap jj `.