diff --git a/client/boot.ts b/client/boot.ts index cf89751b..7360d1b6 100644 --- a/client/boot.ts +++ b/client/boot.ts @@ -27,7 +27,7 @@ safeRun(async () => { .all([ cachedFetch(".config"), // Some minimal bootstrap Lua: schema definition - cachedFetch(".fs/Library/Std/Schema.md"), + cachedFetch(".fs/Library/Std/APIs/Schema.md"), // Configuration option definitions and defaults cachedFetch(".fs/Library/Std/Config.md"), // Custom configuration diff --git a/libraries/Library/Std.md b/libraries/Library/Std.md index a80e68df..192061a1 100644 --- a/libraries/Library/Std.md +++ b/libraries/Library/Std.md @@ -1,8 +1,63 @@ #meta -This is the standard library distributed as part of SilverBullet core. All pages under this prefix are read-only and cannot be modified directly. +Welcome to SilverBullet’s standard library. This library (all pages under `Library/Std`) ship with SilverBullet itself. Therefore, you will not find these pages in your space folder, even though they _appear_ to be located there. These pages are all read-only, so you cannot (directly) modify them. + +The goal of the standard library is provide a base-level of useful commands, slash commands, page templates and scripts. + +The remainder of this page documents what's included. + +# Config +SilverBullet is configured via the [config APIs](https://silverbullet.md/API/config). Built-in configuration options and their default values are defined in [[^Library/Std/Config]]. + +# Page templates +Page templates can be triggered via the ${widgets.commandButton "Page: From Template"} command (some of them have command or keyboard shortcuts) and provide a convenient way to create pages of a certain type. You can create your own page templates using the [[^Library/Std/Page Templates/Page Template]] template. + +The following page templates are part of the standard library: +${template.each(query[[ + from index.tag "page" + where name:startsWith("Library/Std/Page Templates/") +]], template.new[==[ + * [[${_.name}]]: ${_.description} +]==])} + +# Slash templates +Slash templates provide a quick way to insert frequently used snippets of code. You can create your own using the [[^Library/Std/Page Templates/Slash Template]] page template. + +The following slash templates are part of the standard library: +${template.each(query[[ + from index.tag "page" + where name:startsWith("Library/Std/Slash Templates/") +]], template.new[==[ + * [[${_.name}]]: ${_.description} +]==])} + +# Meta pages +The SilverBullet ships with a few generally useful meta pages (pages tagged with `#meta`) you can use: ${template.each(query[[ from index.tag "page" - where name:startsWith("Library/Std/") -]], templates.pageItem)} \ No newline at end of file + where name:startsWith("Library/Std/Pages/") +]], templates.pageItem)} + +# Infrastructure +Core functionality that is implemented using Space Lua: +${template.each(query[[ + from index.tag "page" + where name:startsWith("Library/Std/Infrastructure/") +]], template.new[==[ + * [[${_.name}]]: ${_.description} +]==])} + +# APIs +Whereas a lot of APIs in SilverBullet are built in, some of them have been implemented Space Lua: +${template.each(query[[ + from index.tag "page" + where name:startsWith("Library/Std/APIs/") +]], templates.pageItem)} + +# Editor support +Some editor features have been implemented in Space Lua: +${template.each(query[[ + from index.tag "page" + where name:startsWith("Library/Std/Editor/") +]], templates.pageItem)} diff --git a/libraries/Library/Std/Action Button.md b/libraries/Library/Std/APIs/Action Button.md similarity index 93% rename from libraries/Library/Std/Action Button.md rename to libraries/Library/Std/APIs/Action Button.md index ca26e8b9..1fd35aa8 100644 --- a/libraries/Library/Std/Action Button.md +++ b/libraries/Library/Std/APIs/Action Button.md @@ -1,4 +1,7 @@ -#meta +--- +description: APIs to define custom action buttons +tags: meta/api +--- APIs to more conveniently define action buttons (alternative to setting them via regular [[^Library/Std/Config]]). @@ -36,4 +39,4 @@ function actionButton.define(spec) local actionButtonConfig = config.get("actionButtons", {}) table.insert(actionButtonConfig, spec) end -``` \ No newline at end of file +``` diff --git a/libraries/Library/Std/Command.md b/libraries/Library/Std/APIs/Command.md similarity index 74% rename from libraries/Library/Std/Command.md rename to libraries/Library/Std/APIs/Command.md index 723236b0..43591765 100644 --- a/libraries/Library/Std/Command.md +++ b/libraries/Library/Std/APIs/Command.md @@ -1,4 +1,7 @@ -#meta +--- +description: APIs to define custom commands and slash commands +tags: meta/api +--- APIs to define and patch commands and slash commands. @@ -50,8 +53,28 @@ command.update { } ``` +## slashCommand.define(spec) +Defines a custom slash command. + +Supported keys in the spec: + +* `name`: name of the command +* `description`: Description of the command +* `run`: The callback function that will be invoked once the command is run. + +Example: + +```lua +slashCommand.define { + name = "hello-world", + run = function() + editor.insertAtCursor("Hello |^| world!", false, true) + end +} +``` + # Implementation -Most of the heavy lifting happens in SB itself. +Most of the heavy lifting happens in SB itself. These are just wrappers around the config object API. ```space-lua -- priority: 99 @@ -76,4 +99,4 @@ end function slashCommand.define(def) config.set({"slashCommands", def.name}, def) end -``` \ No newline at end of file +``` diff --git a/libraries/Library/Std/DOM.md b/libraries/Library/Std/APIs/DOM.md similarity index 97% rename from libraries/Library/Std/DOM.md rename to libraries/Library/Std/APIs/DOM.md index eddf37f9..770a5cf2 100644 --- a/libraries/Library/Std/DOM.md +++ b/libraries/Library/Std/APIs/DOM.md @@ -1,4 +1,4 @@ -#meta +#meta/api A library to easily build DOM objects through the magic of Lua meta tables. @@ -28,6 +28,8 @@ ${widget.html(dom.marquee{ # Implementation ```space-lua +-- priority: 50 + dom = setmetatable({}, { __index = function(self, tag) return function(spec) diff --git a/libraries/Library/Std/Date.md b/libraries/Library/Std/APIs/Date.md similarity index 71% rename from libraries/Library/Std/Date.md rename to libraries/Library/Std/APIs/Date.md index d72d7fb3..be83b349 100644 --- a/libraries/Library/Std/Date.md +++ b/libraries/Library/Std/APIs/Date.md @@ -1,7 +1,17 @@ -#meta +#meta/api -Date and time APIs +Useful date and time APIs as well as slash commands by default in `YYYY-MM-dd` format with times in `HH:mm:ss` (24h) format. +Included slash commands: + +* `/today` for today's date. +* `/tomorrow` for tomorrow's date. +* `/yesterday` for yesterday's date. + +# Examples +Today: ${date.today()} and ${date.time()} + +# Implementation ```space-lua -- priority: 10 @@ -49,7 +59,3 @@ slashCommand.define { end } ``` - -# Examples - -Today: ${date.today()} and ${date.time()} \ No newline at end of file diff --git a/libraries/Library/Std/Schema.md b/libraries/Library/Std/APIs/Schema.md similarity index 93% rename from libraries/Library/Std/Schema.md rename to libraries/Library/Std/APIs/Schema.md index 94229dd6..b863303f 100644 --- a/libraries/Library/Std/Schema.md +++ b/libraries/Library/Std/APIs/Schema.md @@ -1,6 +1,6 @@ -#meta +#meta/api -Utilities to succinctly define JSON schema types. +Utilities to succinctly define JSON schema types in Lua. ```space-lua -- priority: 101 @@ -73,4 +73,4 @@ end function schema.func() return {} end -``` \ No newline at end of file +``` diff --git a/libraries/Library/Std/Tag.md b/libraries/Library/Std/APIs/Tag.md similarity index 65% rename from libraries/Library/Std/Tag.md rename to libraries/Library/Std/APIs/Tag.md index 47e206b2..99f42912 100644 --- a/libraries/Library/Std/Tag.md +++ b/libraries/Library/Std/APIs/Tag.md @@ -1,4 +1,4 @@ -#meta +#meta/api Implements convenience functions for accessing tag objects. @@ -14,6 +14,14 @@ ${#query[[from tags.page]]} ```space-lua -- priority: 50 +tag = tag or {} + +-- For future use +function tag.define(spec) + config.set("tagDefinitions", spec.name, spec) +end + +-- Set up tags.* short cut via meta tables tags = setmetatable({}, { __index = function(self, tag) return index.tag(tag) diff --git a/libraries/Library/Std/Template.md b/libraries/Library/Std/APIs/Template.md similarity index 99% rename from libraries/Library/Std/Template.md rename to libraries/Library/Std/APIs/Template.md index 8e674d8d..3fe1a58f 100644 --- a/libraries/Library/Std/Template.md +++ b/libraries/Library/Std/APIs/Template.md @@ -1,4 +1,4 @@ -#meta +#meta/api Implements useful template functions @@ -55,4 +55,4 @@ function template.fromPage(name, raw) end return template.new(templateText, false), fm.frontmatter end -``` \ No newline at end of file +``` diff --git a/libraries/Library/Std/Widget.md b/libraries/Library/Std/APIs/Widget.md similarity index 99% rename from libraries/Library/Std/Widget.md rename to libraries/Library/Std/APIs/Widget.md index 51f6eeda..0961cf9a 100644 --- a/libraries/Library/Std/Widget.md +++ b/libraries/Library/Std/APIs/Widget.md @@ -1,4 +1,4 @@ -#meta +#meta/api This implements the widget API. For a Lua Directive to be rendered as a widget, you need to return it via `widget.new`. diff --git a/libraries/Library/Std/Config.md b/libraries/Library/Std/Config.md index d3ed018f..b0179e04 100644 --- a/libraries/Library/Std/Config.md +++ b/libraries/Library/Std/Config.md @@ -1,6 +1,15 @@ -#meta +--- +description: Defines the schemas and built-in values of built-in configuration options +tags: meta +--- -SilverBullet's configuration can be tweaked using the `config.set` Space Lua API. This page defines all built-in configurations available. Individual Plugs and Space Lua scripts may define their own. +SilverBullet uses the [config APIs](https://silverbullet.md/API/config) to manage its runtime configuration. You can set most of these anywhere in your space, but the convention is to use your [[CONFIG]] page for this purpose. + +This meta page defines the JSON Schema of all built-in configuration settings, as well as their default values. You can override them by e.g. putting the following in your CONFIG page (use `space-lua` instead of `lua` in your actual page): + +```lua +config.set("sync.documents", true) +``` # Built-in options (schema) @@ -8,6 +17,7 @@ This defines the [JSON schema](https://json-schema.org/) for built-in configurat ```space-lua -- priority: 100 + config.define("sync", { description = "Configure sync", type = "object", @@ -71,6 +81,8 @@ config.define("plugs", { }, }) + +-- Editor configuration options config.define("autoCloseBrackets", { description = "List of brackets to auto close", type = "string", @@ -87,58 +99,6 @@ config.define("emoji", { } }) -config.define("commands", { - type = "object", - additionalProperties = { - type = "object", - properties = { - name = schema.string(), - contexts = schema.nullableArray "string", - priority = schema.nullable "number", - key = schema.nullable "string", - mac = schema.nullable "string", - hid = schema.nullable "boolean", - requireMode = schema.nullable { - type = "string", - enum = {"rw", "ro"}, - }, - requireEditor = schema.nullable("string"), - run = schema.func(), - }, - }, -}) - -config.define("slashCommands", { - type = "object", - additionalProperties = { - type = "object", - properties = { - name = schema.string(), - description = schema.nullable "string", - priority = schema.nullable "number", - onlyContexts = schema.nullableArray "string", - exceptContexts = schema.nullableArray "string", - run = schema.func(), - }, - }, -}) - -config.define("eventHandlers", { - type = "object", - additionalProperties = schema.array(schema.func()), -}) - -config.define("tagDefinitions", { - type = "object", - additionalProperties = { - type = "object", - properties = { - schema = { type = "object" }, - metatable = { }, - }, - }, -}) - config.define("smartQuotes", { description = "Configure smart quotes", type = "object", @@ -183,34 +143,6 @@ config.define("mobileMenuStyle", { type = "string", }) -config.define("actionButtons", { - type = "array", - items = { - type = "object", - properties = { - icon = { - type = "string", - description = "Icon for the action button, from https://feathericons.com" - }, - description = { - type = "string", - description = "Optional description of the action button" - }, - priority = { - type = "number", - description = "Optional priority: the higher the earlier the button will appear in the list" - }, - mobile = { - type = "boolean", - description = "Optional boolean indicating if the action button is applicable for mobile" - }, - run = schema.func(), - }, - required = {"icon", "run"}, - additionalProperties = false - } -}) - config.define("vim", { description = "Vim mode configuration", type = "object", @@ -287,6 +219,7 @@ config.define("vim", { additionalProperties = false }) +-- Query specific configuration options config.define("queryCollation", { description = "Configure string ordering in queries", type = "object", @@ -307,9 +240,97 @@ config.define("queryCollation", { }, additionalProperties = false }) + +-- Configuration for internal use mostly + +-- Don't use directly, use command.define instead +config.define("commands", { + type = "object", + additionalProperties = { + type = "object", + properties = { + name = schema.string(), + contexts = schema.nullableArray "string", + priority = schema.nullable "number", + key = schema.nullable "string", + mac = schema.nullable "string", + hid = schema.nullable "boolean", + requireMode = schema.nullable { + type = "string", + enum = {"rw", "ro"}, + }, + requireEditor = schema.nullable("string"), + run = schema.func(), + }, + }, +}) + +-- Don't use directly, use slashCommands.define instead +config.define("slashCommands", { + type = "object", + additionalProperties = { + type = "object", + properties = { + name = schema.string(), + description = schema.nullable "string", + priority = schema.nullable "number", + onlyContexts = schema.nullableArray "string", + exceptContexts = schema.nullableArray "string", + run = schema.func(), + }, + }, +}) + +-- Don't use directly, use event.listen instead +config.define("eventHandlers", { + type = "object", + additionalProperties = schema.array(schema.func()), +}) + +-- Don't use directly, WIP +config.define("tagDefinitions", { + type = "object", + additionalProperties = { + type = "object", + properties = { + schema = { type = "object" }, + metatable = { }, + }, + }, +}) + +-- Don't use directly, use actionButton.define instead +config.define("actionButtons", { + type = "array", + items = { + type = "object", + properties = { + icon = { + type = "string", + description = "Icon for the action button, from https://feathericons.com" + }, + description = { + type = "string", + description = "Optional description of the action button" + }, + priority = { + type = "number", + description = "Optional priority: the higher the earlier the button will appear in the list" + }, + mobile = { + type = "boolean", + description = "Optional boolean indicating if the action button is applicable for mobile" + }, + run = schema.func(), + }, + required = {"icon", "run"}, + additionalProperties = false + } +}) ``` # Default values +Default values for built-in configuration options. ```space-lua -- priority: 99 diff --git a/libraries/Library/Std/Lua.md b/libraries/Library/Std/Editor/Lua.md similarity index 100% rename from libraries/Library/Std/Lua.md rename to libraries/Library/Std/Editor/Lua.md diff --git a/libraries/Library/Std/Table.md b/libraries/Library/Std/Editor/Table.md similarity index 100% rename from libraries/Library/Std/Table.md rename to libraries/Library/Std/Editor/Table.md diff --git a/libraries/Library/Std/Export.md b/libraries/Library/Std/Infrastructure/Export.md similarity index 96% rename from libraries/Library/Std/Export.md rename to libraries/Library/Std/Infrastructure/Export.md index 9fa1b860..e31dcc36 100644 --- a/libraries/Library/Std/Export.md +++ b/libraries/Library/Std/Infrastructure/Export.md @@ -1,5 +1,7 @@ -#meta - +--- +description: Implements the infrastructure of the Export commands. +tags: meta +--- Provides infrastructure for exporting pages outside of your space. It standardizes the ${widgets.commandButton("Export: Page Or Selection")} to export the current page or selection in various ways. # Architecture diff --git a/libraries/Library/Std/Gist.md b/libraries/Library/Std/Infrastructure/Gist.md similarity index 97% rename from libraries/Library/Std/Gist.md rename to libraries/Library/Std/Infrastructure/Gist.md index 73cf1604..7f57aa2c 100644 --- a/libraries/Library/Std/Gist.md +++ b/libraries/Library/Std/Infrastructure/Gist.md @@ -1,6 +1,6 @@ #meta -[[^Library/Std/Import]] and [[^Library/Std/Export]] support for [Github Gists](https://gist.github.com/). +[[^Library/Std/Infrastructure/Import]] and [[^Library/Std/Infrastructure/Export]] support for [Github Gists](https://gist.github.com/). # Configuration If you only want to _import_ from Gist URLs, no configuration is required. @@ -180,4 +180,4 @@ event.listen { end end } -``` \ No newline at end of file +``` diff --git a/libraries/Library/Std/Github.md b/libraries/Library/Std/Infrastructure/Github.md similarity index 96% rename from libraries/Library/Std/Github.md rename to libraries/Library/Std/Infrastructure/Github.md index 5a53f692..ec174e10 100644 --- a/libraries/Library/Std/Github.md +++ b/libraries/Library/Std/Infrastructure/Github.md @@ -1,11 +1,11 @@ #meta -[[^Library/Std/Import]] and [[^Library/Std/Export]] support for [Github repo files](https://github.com). +[[^Library/Std/Infrastructure/Import]] and [[^Library/Std/Infrastructure/Export]] support for [Github repo files](https://github.com). # Configuration If you only want to _import_ from Github URLs, no configuration is required. -To _export_ got a Github repo, you need to get a [personal Github token](https://github.com/settings/personal-access-tokens) (with repo permissions). Configure your token somewhere in Space Lua (use a `space-lua` block), ideally a `SECRETS` page. This configuration is shared with [[^Library/Std/Gist]]. +To _export_ got a Github repo, you need to get a [personal Github token](https://github.com/settings/personal-access-tokens) (with repo permissions). Configure your token somewhere in Space Lua (use a `space-lua` block), ideally a `SECRETS` page. This configuration is shared with [[^Library/Std/Infrastructure/Gist]]. ```lua config.set("github.token", "your token") @@ -200,4 +200,4 @@ event.listen { end end } -``` \ No newline at end of file +``` diff --git a/libraries/Library/Std/Import.md b/libraries/Library/Std/Infrastructure/Import.md similarity index 97% rename from libraries/Library/Std/Import.md rename to libraries/Library/Std/Infrastructure/Import.md index 246281f3..c5e57d38 100644 --- a/libraries/Library/Std/Import.md +++ b/libraries/Library/Std/Infrastructure/Import.md @@ -1,5 +1,7 @@ -#meta - +--- +description: Implements the infrastructure of the Import commands. +tags: meta +--- Provides infrastructure for importing pages outside of your space. It standardizes the ${widgets.commandButton("Import: URL")} to export the current page or selection in various ways. # Technical architecture @@ -104,4 +106,4 @@ event.listen { editor.setText(updated) end } -``` \ No newline at end of file +``` diff --git a/libraries/Library/Std/Page Templates.md b/libraries/Library/Std/Infrastructure/Page Templates.md similarity index 98% rename from libraries/Library/Std/Page Templates.md rename to libraries/Library/Std/Infrastructure/Page Templates.md index 5badc61f..60da5e16 100644 --- a/libraries/Library/Std/Page Templates.md +++ b/libraries/Library/Std/Infrastructure/Page Templates.md @@ -1,5 +1,7 @@ -#meta - +--- +description: Implements the infrastructure of Page Templates. +tags: meta +--- Page templates can be used to automate or simplify the creation of pages based on a template. # Creating a page template diff --git a/libraries/Library/Std/Query Templates.md b/libraries/Library/Std/Infrastructure/Query Templates.md similarity index 94% rename from libraries/Library/Std/Query Templates.md rename to libraries/Library/Std/Infrastructure/Query Templates.md index 5acf652e..b4d1319c 100644 --- a/libraries/Library/Std/Query Templates.md +++ b/libraries/Library/Std/Infrastructure/Query Templates.md @@ -1,5 +1,7 @@ -#meta - +--- +description: Implements generally useful query templates. +tags: meta +--- A work-in-progress library of generally useful templates for rendering queries. ```space-lua diff --git a/libraries/Library/Std/Slash Templates.md b/libraries/Library/Std/Infrastructure/Slash Templates.md similarity index 94% rename from libraries/Library/Std/Slash Templates.md rename to libraries/Library/Std/Infrastructure/Slash Templates.md index 9a595c1f..5cde97bf 100644 --- a/libraries/Library/Std/Slash Templates.md +++ b/libraries/Library/Std/Infrastructure/Slash Templates.md @@ -1,5 +1,7 @@ -#meta - +--- +description: Implements the infrastructure of Slash Templates. +tags: meta +--- Allows for quick definition of slash commands based on templates. # Creating slash templates diff --git a/libraries/Library/Std/Tag Page.md b/libraries/Library/Std/Infrastructure/Tag Page.md similarity index 96% rename from libraries/Library/Std/Tag Page.md rename to libraries/Library/Std/Infrastructure/Tag Page.md index fd50bfa9..1ba10d43 100644 --- a/libraries/Library/Std/Tag Page.md +++ b/libraries/Library/Std/Infrastructure/Tag Page.md @@ -1,4 +1,7 @@ -#meta +--- +description: Implements the tag page +tags: meta +--- Implements a tag page, that renders when navigating to a hashtag: #meta based on the `tag:` prefix, by piggy backing on the `editor:pageCreating` event that triggers for non-existing pages. diff --git a/libraries/Library/Std/Page Templates/Page Template.md b/libraries/Library/Std/Page Templates/Page Template.md index 5f2e60e3..1d39f16a 100644 --- a/libraries/Library/Std/Page Templates/Page Template.md +++ b/libraries/Library/Std/Page Templates/Page Template.md @@ -1,5 +1,6 @@ --- suggestedName: "Library/Page Templates/" +description: A page template to create your own page templates confirmName: true tags: meta/template/page frontmatter: | diff --git a/libraries/Library/Std/Page Templates/Quick Note.md b/libraries/Library/Std/Page Templates/Quick Note.md index 926efaf2..9001a689 100644 --- a/libraries/Library/Std/Page Templates/Quick Note.md +++ b/libraries/Library/Std/Page Templates/Quick Note.md @@ -1,8 +1,9 @@ --- command: Quick Note +description: A page template to create a quick note key: "Alt-Shift-n" suggestedName: "Inbox/${os.date('%Y-%m-%d/%H-%M-%S')}" confirmName: false tags: meta/template/page priority: 10 ---- \ No newline at end of file +--- diff --git a/libraries/Library/Std/Page Templates/Slash Template.md b/libraries/Library/Std/Page Templates/Slash Template.md index 54b24f14..41e934c4 100644 --- a/libraries/Library/Std/Page Templates/Slash Template.md +++ b/libraries/Library/Std/Page Templates/Slash Template.md @@ -1,5 +1,6 @@ --- suggestedName: "Library/Slash Templates/" +description: A page template to create a custom slash command confirmName: true tags: meta/template/page frontmatter: | diff --git a/libraries/Library/Std/Slash.md b/libraries/Library/Std/Slash Commands/Slash.md similarity index 100% rename from libraries/Library/Std/Slash.md rename to libraries/Library/Std/Slash Commands/Slash.md diff --git a/libraries/Library/Std/Embed.md b/libraries/Library/Std/Widgets/Embed.md similarity index 96% rename from libraries/Library/Std/Embed.md rename to libraries/Library/Std/Widgets/Embed.md index 34559322..83bafac7 100644 --- a/libraries/Library/Std/Embed.md +++ b/libraries/Library/Std/Widgets/Embed.md @@ -1,13 +1,12 @@ #meta -Implements useful embeds +Implements useful embed widgets. # Youtube ## Example ${embed.youtube "https://youtu.be/t1oy_41bDAY?si=X76FvJEUlJnApwEg"} -## Implementation - +# Implementation ```space-lua -- Schema local youtubeSpecSchema = { diff --git a/libraries/Library/Std/Widgets.md b/libraries/Library/Std/Widgets/Widgets.md similarity index 100% rename from libraries/Library/Std/Widgets.md rename to libraries/Library/Std/Widgets/Widgets.md diff --git a/website/API/command.md b/website/API/command.md index 4c421727..d88c56d7 100644 --- a/website/API/command.md +++ b/website/API/command.md @@ -1 +1 @@ -See [[^Library/Std/Command]] \ No newline at end of file +See [[^Library/Std/APIs/Command]] \ No newline at end of file diff --git a/website/API/slashCommand.md b/website/API/slashCommand.md index 39b17a6a..ee3f442c 100644 --- a/website/API/slashCommand.md +++ b/website/API/slashCommand.md @@ -1,4 +1,4 @@ -APIs to create [[Slash Commands]]. For simple cases it is recommended to use [[Library/Std/Slash Templates]] instead. +APIs to create [[Slash Commands]]. For simple cases it is recommended to use [[Library/Std/Infrastructure/Slash Templates]] instead. ## slashCommand.define(spec) diff --git a/website/CHANGELOG.md b/website/CHANGELOG.md index 30eeba5d..67223007 100644 --- a/website/CHANGELOG.md +++ b/website/CHANGELOG.md @@ -3,7 +3,10 @@ An attempt at documenting the changes/new features introduced in each release. ## Edge These are changes live on the edge builds: -* _Nothing yet since 2.1.6_ +* Restructure of the `Library/Std` library, added some more (self) documentation. See [[^Library/Std]] as an entry point. +* Readded `page:saved` event that was removed in 2.1 +* Fixed infinite item index loop in obscure cases +* When the clipboard API is used in Safari, will now give a proper error (Safari restriction) by ([Noah Stanley](https://github.com/silverbulletmd/silverbullet/pull/1575)) ## 2.1.4 - 2.1.6 * Fixed broken auth in Safari @@ -12,7 +15,7 @@ These are changes live on the edge builds: * Fixed docker user and group creation issues * Removed `file:deleted` triggering when checking for `getFileMeta` (causing an infinite indexing loop in SilverSearch) * Server: HTTP Gzip compression is now enabled for sensible content types -* Nicer syntax to query tag objects from the index: `tags.page` becomes an alias for `index.tag "page"` (implemented here: [[^Library/Std/Tag]]) +* Nicer syntax to query tag objects from the index: `tags.page` becomes an alias for `index.tag "page"` (implemented here: [[^Library/Std/APIs/Tag]]) * Hidden files and folders (starting with `.`) are no longer synced, as well as files without a file extension (those were not support anyway) ## 2.1.2 diff --git a/website/Command Palette.md b/website/Command Palette.md index c375377f..5690eef5 100644 --- a/website/Command Palette.md +++ b/website/Command Palette.md @@ -5,4 +5,4 @@ The UI and its operation is largely the same as the [[Page Picker]]‘s, with a * If a keyboard shortcut is configured for the given command, it is listed along the command name to the right. * The ordering is decided based on two factors: * The last time the command was invoked via the [[Command Palette]] in this client session. - * The `priority` configured for the command (in the plug, or via [[^Library/Std/Config]] under `shortcuts`). \ No newline at end of file + * The `priority` configured for the command (in the plug, or via [[^Library/Std/Config]] under `shortcuts`). diff --git a/website/Commands.md b/website/Commands.md index 621225d3..4657d7a1 100644 --- a/website/Commands.md +++ b/website/Commands.md @@ -4,4 +4,4 @@ SilverBullet ships with a lot of commands built in, but custom ones can also be Beside the list below, all commands available commands appear in the [[Command Palette]] but may have key bindings as well (these key bindings appear in the [[Command Palette]] and are configurable in [[^Library/Std/Config]]). -You can create custom command using the [[^Library/Std/Command]] API. +You can create custom command using the [[^Library/Std/APIs/Command]] API. diff --git a/website/Frontmatter.md b/website/Frontmatter.md index 76a6edb3..59f74a0b 100644 --- a/website/Frontmatter.md +++ b/website/Frontmatter.md @@ -51,4 +51,4 @@ While SilverBullet allows arbitrary metadata to be added to pages, there are a f - "#tag2" ``` -For specific use cases, like [[^Library/Std/Page Templates]] or [[^Library/Std/Slash Templates]], frontmatter may have specific meaning. +For specific use cases, like [[^Library/Std/Infrastructure/Page Templates]] or [[^Library/Std/Infrastructure/Slash Templates]], frontmatter may have specific meaning. diff --git a/website/Libraries.md b/website/Libraries.md index e36e3430..6225897d 100644 --- a/website/Libraries.md +++ b/website/Libraries.md @@ -1,18 +1,18 @@ A lot of useful functionality in SilverBullet is implemented through [[Space Lua]] embedded in [[Meta Pages]]. Some of these you will create yourself for your own specific use, but many are generic and generally useful. -By default SilverBullet is distributed with the [[^Library/Std]] library containing some generally useful features. In addition, you can download more libraries via the [[^Library/Std/Import]] mechanism. While this is in no way enforced, it is good practice to store your libraries under `Library/`. +By default SilverBullet is distributed with the [[^Library/Std]] library containing some generally useful features. In addition, you can download more libraries via the [[^Library/Std/Infrastructure/Import]] mechanism. While this is in no way enforced, it is good practice to store your libraries under `Library/`. # What’s in a library Here are some things that a library may provide: * Various [[Slash Commands]], such as `/today`, `/task`, `/table`. * Useful [[Page Templates]] -* Useful [[^Library/Std/Widgets]] +* Useful [[^Library/Std/Widgets/Widgets]] * Useful pages that help you perform maintenance on your space, like detecting broken links, such as [[^Library/Std/Pages/Maintenance]]. # Distribution and Importing -We’re still figuring out the best way to distribute libraries. However, one that works already is through SilverBullet’s [[^Library/Std/Import]] mechanism, which enables e.g. importing a library from a Github Gist. +We’re still figuring out the best way to distribute libraries. However, one that works already is through SilverBullet’s [[^Library/Std/Infrastructure/Import]] mechanism, which enables e.g. importing a library from a Github Gist. -Similarly [[^Library/Std/Export]] can be use to export your library to a Github Gist. +Similarly [[^Library/Std/Infrastructure/Export]] can be use to export your library to a Github Gist. # Can I change libraries locally? Libraries you manually imported (see previous section) can be freely changed. Do note that if you import them again, you will override your changes. diff --git a/website/Linked Mentions.md b/website/Linked Mentions.md index 2f1f97cd..a8f0f5e6 100644 --- a/website/Linked Mentions.md +++ b/website/Linked Mentions.md @@ -1,3 +1,3 @@ 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. -Implementation: [[^Library/Std/Widgets#Linked mentions]] \ No newline at end of file +More details: [[^Library/Std/Widgets/Widgets]] \ No newline at end of file diff --git a/website/Linked Tasks.md b/website/Linked Tasks.md index fd00a358..4217daa4 100644 --- a/website/Linked Tasks.md +++ b/website/Linked Tasks.md @@ -11,4 +11,4 @@ Below are two tasks that mention this very page (this is not the general pattern * [ ] [[Linked Tasks]] This is a task * [x] [[Linked Tasks]] This is a completed task -**Implementation:** [[^Library/Std/Widgets]] \ No newline at end of file +**Implementation:** [[^Library/Std/Widgets/Widgets]] \ No newline at end of file diff --git a/website/Meta Pages.md b/website/Meta Pages.md index e5d9e084..ba7c690d 100644 --- a/website/Meta Pages.md +++ b/website/Meta Pages.md @@ -1,6 +1,6 @@ Meta pages are pages not core to your content, but function as a way to configure, or extend your [[Spaces|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/Slash Templates]]. +The most obvious examples are part of SilverBullet’s [[^Library/Std]] library and include generally useful [[Library/Std/Infrastructure/Slash Templates]]. If you use [[Space Lua]] or [[Space Style]], you may want to put those on separate pages and tag them as `#meta` as well, so they don’t mingle with your main content. diff --git a/website/Migrate from v1.md b/website/Migrate from v1.md index 2da5c5d2..168d3b76 100644 --- a/website/Migrate from v1.md +++ b/website/Migrate from v1.md @@ -31,11 +31,11 @@ event.listen { } ``` -See [[^Library/Std/Widgets]] for some examples. +See [[^Library/Std/Widgets/Widgets]] for some examples. -_Snippets_ can be implemented as follows: [[Library/Std/Slash Templates]]. +_Snippets_ can be implemented as follows: [[Library/Std/Infrastructure/Slash Templates]]. -_Page templates_ now work slightly differently: [[^Library/Std/Page Templates]]. +_Page templates_ now work slightly differently: [[^Library/Std/Infrastructure/Page Templates]]. # Plugs Many existing plugs _should_ keep working, but some may need updating. @@ -58,7 +58,7 @@ Certain features have been removed: * Online mode: v2 is sync mode only, meaning all your content will be synced into your browser. A simpler Online mode may be added back later. If you like to wipe your local content at any time, use the `System: Wipe Client` command. * [Federation](https://v1.silverbullet.md/Federation) -* [Share](https://v1.silverbullet.md/Plugs/Share) replaced by [[^Library/Std/Export]] +* [Share](https://v1.silverbullet.md/Plugs/Share) replaced by [[^Library/Std/Infrastructure/Export]] * Space Script: replaced by [[Space Lua]] * Space Config: replaced by the [[API/config]] APIs. * Command link syntax (`{[...]})`) replaced by the `${widgets.commandButton(...)}` API. diff --git a/website/Page Decorations.md b/website/Page Decorations.md index 0e06f95c..c5cf3234 100644 --- a/website/Page Decorations.md +++ b/website/Page Decorations.md @@ -13,7 +13,7 @@ Page decorations allow you to “decorate” pages in various fun ways. # Supported decorations * `prefix`: A (visual) string prefix (often an emoji) to add to all page names. This prefix will appear in the top bar as well as in (live preview) links to this page. For example, the name of this page is actually “Page Decorations”, but when you link to it, you’ll see it’s prefixed with a 🎄: [[Page Decorations]] * `cssClasses`: (list of strings) Attaches one or more CSS classes the page's `` tag, wiki links, auto complete items and [[Page Picker]] entries for more advanced styling through a [[Space Style]] (see [[#Use case: pimp my page]] for an example). -* `disableTOC` (not technically built-in, but a feature of the [[^Library/Std/Widgets|Table of Content]] widget): disable the TOC for this particular page. +* `disableTOC` (not technically built-in, but a feature of the [[^Library/Std/Widgets/Widgets|Table of Content]] widget): disable the TOC for this particular page. # Apply with [[Frontmatter]] This is demonstrated in the [[Frontmatter]] at the top of this page, by using the special `pageDecoration` attribute. This is how we get the fancy tree (🎄) in front of the page name. Sweet. diff --git a/website/Page Templates.md b/website/Page Templates.md index e3a6c751..8e56d979 100644 --- a/website/Page Templates.md +++ b/website/Page Templates.md @@ -1 +1 @@ -![[^Library/Std/Page Templates]] \ No newline at end of file +![[^Library/Std/Infrastructure/Page Templates]] \ No newline at end of file diff --git a/website/Slash Commands.md b/website/Slash Commands.md index a70c3262..edcf8a30 100644 --- a/website/Slash Commands.md +++ b/website/Slash Commands.md @@ -1,4 +1,4 @@ -Slash commands are quick ways to perform repetitive tasks. 99% of the time this will mean using a [[^Library/Std/Slash Templates]], but you can also create them more manually using [[Space Lua#Slash commands]]. +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 more manually using [[Space Lua#Slash commands]]. # 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). diff --git a/website/Space Lua/Widgets.md b/website/Space Lua/Widgets.md index 2bfab28a..206a2702 100644 --- a/website/Space Lua/Widgets.md +++ b/website/Space Lua/Widgets.md @@ -3,7 +3,7 @@ The `${lua expression}` syntax can be used to implement custom widgets. If the L 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/DOM]] API. +* `html`: Renders a HTML string as a widget. This is somewhat brittle. Therefore, it’s preferred to use the [[^Library/Std/APIs/DOM]] API. * `display`: Render the value either `inline` or as a `block` (defaults to `inline`) For convenience there are `widget.markdown` and `widget.html` wrappers available, see below for examples. @@ -11,7 +11,7 @@ For convenience there are `widget.markdown` and `widget.html` wrappers available ## Markdown widgets ## DOM widgets -To render a custom HTML-based widget, use the [[^Library/Std/DOM]] API: +To render a custom HTML-based widget, use the [[^Library/Std/APIs/DOM]] API: ```space-lua function marquee(text)