Oh boy, this is a big one. This release brings you the following:
* [[Objects]]: a more generic system to indexing and querying content in your space, including the ability to define your own custom object “types” (dubbed [[Tags]]). See the referenced pages for examples.
* [[Live Queries]] and [[Live Templates]]: ultimately will replace [[🔌 Directive]] in future versions and **[[🔌 Directive]] is now deprecated.** They differ from directives in that they don’t materialize their output into the page itself, but rather render them on the fly so only the query/template instantiation is kept on disk. All previous directive examples on this website how now been replaced with [[Live Templates]] and [[Live Queries]]. To ease the conversion there is {[Directive: Convert Query to Live Query]} command: just put your cursor inside of an existing (query) directive and run it to auto-convert.
* The query syntax used in [[Live Queries]] (but also used in [[🔌 Directive]]) has been significantly expanded, although there may still be bugs. There’s still more value to be unlocked here in future releases.
* The previous “backlinks” plug is now built into SilverBullet as [[Linked Mentions]] and appears at the bottom of every page (if there are incoming links). You can toggle linked mentions via {[Mentions: Toggle]}.
* A whole bunch of [[PlugOS]] syscalls have been updated, I’ll do my best update known existing plugs, but if you built existing ones some things may have broken. Please report anything broken in [Github issues](https://github.com/silverbulletmd/silverbullet/issues).
* This release effectively already removes the `#eval` [[🔌 Directive]] (it’s still there, but likely not working), this directive needs some rethinking. Join us on [Discord](https://discord.gg/EvXbFucTxn) if you have a use case for it and how you use/want to use it.
* If you have plugs such as “backlinks” or “graphview” installed, please remove them (or to be safe: all plugs) from the `_plug` folder in your space after the upgrade. Then, also remove them from your [[PLUGS]] page. The backlinks plug is now included by default (named [[Linked Mentions]]), and GraphView still needs to be updated (although it’s been kind of abandoned by the author).
Due to significant changes in how data is stored, likely your space will be resynced to all your clients once you upgrade. Just in case you may also want to {[Space: Reindex]} your space. If things are really broken, try the {[Debug: Reset Client]} command.
The big change in this release is that SilverBullet now supports two [[Client Modes|client modes]]: _online_ mode and _sync_ mode. Read more about them here: [[Client Modes]].
* Removed [[Cloud Links]] support in favor of [[Federation]]. If you still have legacy cloud links, simply replace the 🌩️ with a `!` and things should work as before.
* Cookies set when using SilverBullet's built-in [[Authentication]] are now per domain + port, allowing you to run multiple instances of SB on a single host with different ports without the authentication interfering.
* Page references in [[SETTINGS]] now use double-bracket notation (optionally) which is nicer, because you’ll get completion. See [[SETTINGS]] for examples.
* It is now possible to override [[🔌 Plugs]] manifests. The primary use case for this is to be able to _override keyboard shortcuts_. This feature may still change over time, but you can try it out. See [[SETTINGS]] for an example.
* When the PWA starts, it will now send you back to the last opened page instead of the index page (you may have to reinstall the PWA for this change to take effect).
* Various heavy-weight commands (such as {[Space: Reindex]} and {[Directives: Update Entire Space]}) now use an internal message queue, allowing to continue the processing even when interrupted or crashing.
* [[Metadata]] both in [[Frontmatter]] and [[Attributes]] names are now indexed (scoped to whether they apply to pages, items or tasks) and code completed, e.g in front matter, attribute syntax and queries.
* When pressing `Shift-Enter` rather than regular `Enter` in the page navigator, the input is now used literally to create a new page with that name. For example, typing in “my page” and hitting `Shift-Enter` will always create a page with that name (rather than defaulting to the best match, which is what `Enter` would navigate to).
* **Important bug fix:** under specific circumstances an initial sync (of a new device) could result in the initial page (when opening SB) being deleted. Not good. Please upgrade to this version ASAP. And continue making backups of your space.
* New {[Refactor: Batch Rename Page Prefix]} command to rename a page prefix to something else, can be used to achieve the effect of renaming a folder (e.g. from `topics/` to `my topics/`) while updating all links properly.
* Update to [[Attributes]] syntax
* Fix: Renaming a template page now also updates references to it (e.g. in `render` clauses)
* Scroll position is now retained when switching between pages
* [Mobile view improvements](https://github.com/silverbulletmd/silverbullet/pull/452) for tables and directives (vertical spacing) by [vuau](https://github.com/vuau)
* Internal work on [color theming](https://github.com/silverbulletmd/silverbullet/pull/455) by [TheLD6978](https://github.com/TheLD6978)
* Backlinks (as queried via the `link` data source) now contains richer data, namely `inDirective` (if the link appears in the context of a directive) and `alias` (if the backlink has an alias name). This also fixes not updating page references inside directives. This introduced a backwards incompatible data. To update your indexes, please run {[Space: Reindex]} on your clients (once).
* **Removal of all real-time collaboration features**: this was causing too many edge cases, and complicated the code too much. To simplify the product as well as the code, we completely removed all real-time collaboration features for now. We may introduce this at some point in the future when the demand and focus is there.
* **Change of APIs**: This is mostly internal, but will likely have effects on the first load after the upgrade: you may see errors or a message around “the path has changed”, or your page may not properly load. Don’t freak out, just reload once or twice and all should resync and be fine. There’s a beginning of documenting the server [[API]] now.
* **Breaking change (for some templates):** Template in various places allowed you to use `{{variables}}` and various handlebars functions. There also used to be a magic `{{page}}` variable that you could use in various places, but not everywhere. This has now been unified. And the magical `{{page}}` now has been replaced with the global `@page` which does not just expose the page’s name, but any page meta data. More information here: [[🔌 Template@vars]]. You will now get completion for built-in handlebars helpers after typing `{{`.
* **Breaking change** (for [[STYLES]] users). The [[STYLES]] page is now no longer “magic” and hardcoded. It can (and must) now be specified in [[SETTINGS]] (see example on that page) for styles to be loaded from it.
* Folding is here (at least with commands, not much UI): {[Fold: Fold]}, {[Fold: Unfold]}, {[Fold: Toggle Fold]}, {[Fold: Fold All]} and {[Fold: Unfold All]}.
* REMOVED: **Real-time collaboration support** between clients: Open the same page in multiple windows (browser tabs, mobile devices) and within a few seconds you should get kicked into real-time collaboration mode, showing other participants cursors, selections and edits in real time (Google doc style). This only works when a connection with the server can be established.
* [[Authentication|Multi-user authentication]]: you can now allow multiple user accounts authenticate, which makes the real-time collaboration support actually useful. This feature is still experimental and will likely evolve over time.
This is another big architectural shift warranting a major minor version bump 😉.
A detailed description of what happened [can be found in this PR](https://github.com/silverbulletmd/silverbullet/pull/403), the TL;DR is this:
* SilverBullet in this version is going **_all in_ on being an offline-capable [PWA](https://web.dev/progressive-web-apps/)**. This means the desktop and mobile applications will no longer be maintained. However, the value those applications brought (offline capability) has now been built right into the “regular web” version without the burden of having to maintain a desktop app for three platforms, and a mobile app for two.
* Upon first launch in a modern browser, SilverBullet will now _sync a full copy of your entire space locally_ (into your browser’s IndexedDB database). When a network connection to the server is available, it will sync files with it. On the server, files are still kept as regular files, nothing changes here.
* To avoid accidentally syncing ginormous (that’s a technical term) files to your browser, by default files > 20MB are not exposed. This puts an effective **file size limit of 20MB on files** in your space, this limit is configurable with the `--maxFileSize` flag (file a file size in MB) when running `silverbullet`.
* After the first launch, you can disconnect from your network and your application should still be available: reload the page; restart the browser;reboot your machine, and everything still works. Note that while you’re offline, your title bar will appear in yellow to indicate this “offline” state.
* All processing (all [[🔌 Plugs]] logic) is now running in the browser. Previously, some of this work was offloaded to the server. No more, the server is now a dumb file store. You can (and probably should) delete your `data.db` file, which was previously used to store state on the server side.
* From a UI perspective little changes, except for a few things related to sync:
* While SB is in an out-of-sync state, the title bar will appear yellow. This will also happen when it cannot reach the server. SB is still fully functional in this state. Once the connection is restored, all changes while offline are synced back to the server.
* Upon initial load, a full sync will take place, which — depending on the size of your space —may take some time. Or even blow up completely, if you have a big amount of data there.
* To reset your browser state (flush out your entire space, caches and data stores) visit the `/.client/logout.html` page, e.g. at http://localhost:3000/.client/logout.html and push the button. Note that any unsynced changes will be wiped.
Besides these architectural changes, a few other breaking changes were made to seize the moment:
* **In plugs**:
* Plugs are now distributed as `.plug.js` files instead of `.plug.json` files. This greatly improves debugability (when you compile with `--debug` you get source maps, and can even set breakpoints) and drastically decreases their file size. All existing plugs need to be recompiled using the `silverbullet plug:compile` command, and the resulting `.plug.js` file commited. Then update your [[PLUGS]] page to point to the resulting `.plug.js` files.
* **Breaking change** in URLs (if you bookmarked them before): spaces in page names used to be replaced with `_` to look nicer, however, this was causing too many issues for people, so they’re no longer replaced and will appear as `%20` (regular URI encoding) now.
* On mobile, you can now tap with two fingers on the editor to open the page picker, and with three fingers to open the command palette.
* Internal note: to avoid page/file name clashes in URLs, various internal URLs have changed, FS requests are now served from `/.fs` instead of `/fs`, and all client static files from `/.client` (was root before).
* Added support to override CSS styles on a per-space basis. This replaces the previous `fontFamily` setting. See [[STYLES]] for hints on how to use this new experimental feature.
* Reverted behavior of using up/down arrow keys to move between the page title and page content (and rename based on it). This resulted in undesirable behavior too often. You can now rename a page by clicking/tapping on the title, changing the name and hitting Enter or clicking anywhere outside the page title to apply the rename.
* Documentation updates (on https://silverbullet.md):
* [[Special Pages]]
* [[SETTINGS]]
* Support template variables in a page template's `$name`
* ~~Ability to set the editor font via the `fontFamily` setting~~ in [[SETTINGS]] (restart the app/reload the page to make it go into effect). **Update**: now done via [[STYLES]]
* Clicking the URL (inside of an image `` or link `[text](link)`) no longer navigates there, you need to click on the anchor text to navigate there now (this avoids a lot of weird behavior).
* Most areas where you enter text (e.g. the page name, page switcher, command palette and filter boxes) now use a CodeMirror editor. This means a few things:
1. If you have vim mode enabled, this mode will also be enabled there.
2. You can now use the emoji picker (`:party` etc.) in those places, in fact, any plug implementing the `minieditor:complete` event —right now just the emoji picker — will work.
* Added support for plugs to extend fenced code blocks with custom languages and rendering live-preview widgets for them. As a demo of this, have a look at markdown support (mostly for demo purposes):
```markdown
# Header
1. Item 1
2. Item 2
```
Two more plugs are now available that add [[🔌 Mermaid]] and [[🔌 KaTeX]] (LaTeX formula) support using this functionality.
* Moving up from the first line of the page will now move your cursor to the page title for you to rename it, and moving down from there puts you back in the document.
* Note for plug authors: The (misnamed) `page:complete` event has been renamed to `editor:complete`. There's also a new `minieditor:complete` that's only used for "mini editors" (e.g. in the page switcher, command palette, and page name editor).
* The `--user` authentication flag is now no longer powered by BasicAuth, but through a simple login form asking for a username and password and storing it in a cookie (that persists for 1 week). This gives the same level of security, but works around various browser bugs with basic auth.
* Vim mode is here! This mode can be enabled on a per-client basis (its state is stored in the browser). To toggle Vim mode on or off use the {[Editor: Toggle Vim Mode]} command.
* Security update: SB now binds to `127.0.0.1` by default, allowing just connections via `localhost`. To allow outside connections, pass the `--hostname 0.0.0.0` flag (and ideally combine it with a `--user username:password` flag to add basic authentication).
* Replaced the `--password` flag with `--user` taking a basic auth combination of username and password, e.g. `--user pete:1234`. Authentication now uses standard basic auth. This should fix attachments not working with password-protected setups.
* Enable configuration of IP to bind to (via `--host` flag) by [Jouni K. Seppänen](https://github.com/silverbulletmd/silverbullet/pull/138)
* Markdown enhancements:
* Added support for ~~strikethrough~~ syntax.
* Added support for [admonitions](https://github.com/community/community/discussions/16925) using Github syntax (`note` and `warning`) by [Christian Schulze](https://github.com/silverbulletmd/silverbullet/pull/186)
* Directives have been heavily reworked, and are now "properly" parsed. This is visible in two ways:
* There's now syntax highlighting for queries
* Once the cursor is placed within a directive, it shows the whole block as a "capsule" enclosed in the opening and close tag, when the cursor is outside, it just subtly highlights what parts of a page are directive generated.
* Fix for the {[Page: Rename]} command by [Chris Zarate](https://github.com/silverbulletmd/silverbullet/pull/190)
* Empty query result set rendered as a table now shows “No results” instead of an empty markdown table — fix by [ItzNesbro](https://github.com/silverbulletmd/silverbullet/pull/192).
* New page link aliasing syntax (Obsidian compatible) is here: `[[page link|alias]]` e.g. [[CHANGELOG|this is a link to this changelog]]. Also supported for command links: `{[Plugs: Add|add a plug]}`
* Less "floppy" behavior when clicking links (regular, wiki and command): just navigates there right away. Note: use `Alt-click` to move the cursor inside of a link.
* The editor is now in "live preview" mode where a lot of markdown is hidden unless the cursor is present. This will take some getting used to, but results in a much more distraction free look.
* Clicking on the page name in the top bar now allows you to quickly rename pages, hit enter to apply the change.
* The previous behavior of opening the page switcher, has now moved to its own action button (the folder one)
* **Breaking change:** task and item tags are [now indexed without the prefixing `#`](https://github.com/silverbulletmd/silverbullet/issues/124), this means that any queries, such as `#query task where tags = "#mytag"` need to be rewritten to `#query task where tags = "mytag"`. This will go into effect after a space reindex.
* Rich text paste: paste content from web pages, google docs, including tables and SB will make a best effort to convert it to Markdown. Implemented using [turndown](https://github.com/mixmark-io/turndown). Probably can use some tweaking, but it's something.
* Breaking change (for those who used it): the named anchor syntax has changed from `@anchorname` to `$anchorname`. This is to avoid conflicts with potential future use of `@` for other purposes (like mentioning people). Linking to an anchor still uses the `[[page@anchorname]]` syntax. So, you create an anchor $likethis you can then reference it [[@likethis]].
* The `query` plug has been renamed to `directive` (because it supports many other features now) and significantly refactored. New docs: [[🔌 Directive]]
* New directive `#eval` see [[🔌 Directive@eval]]
* New PlugOS feature: redirecting function calls. Instead of specifying a `path` for a function, you can now specify `redirect` pointing to another function name, either in the same plug using the `plugName.functionName` syntax.
* New {[Open Weekly Note]} command (weeks start on Sunday by default, to allow for planning, but you can change this to Monday by setting the `weeklyNoteMonday` to `true` in [[SETTINGS]]). Like for {[Open Daily Note]} you can create a template in `template/page/Weekly Note`.
