A Space is a boundary: what lives in it sits on your server and stays there unless you decide otherwise. Often, though, some of that content needs to cross the boundary — to push it out into the world, 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.
Sharing may be desirable in different directions:
SilverBullet has infrastructural support to solve this problem in a general way. It leverages Frontmatter, specifically the following keys:
share.uri: specifies the external location to push, pull or sync your content with, represented as a URI.share.mode: specifies the mode this sharing should happen, options are: push, pull or syncshare.transform (optional): false to publish the page without any of the changes described in #What gets published.Pull and sync shares also write a share.hash key: the hash of the text agreed with the remote at the last pull or sync. Next time it tells which side changed since, and as it travels with the page, that works from any of your devices: nothing about a share is kept on the device. Push needs no such record: it compares the page with the remote.
In your writable space, open the page you want to share and run the Share: Page (bound to Cmd-p/Ctrl-p by default) command. This will pop up a list of enabled “Share providers”. Pick one and follow the provider-specific onboarding steps. At the end, your page will be shared and the share.* frontmatter keys automatically set.
Subsequent shares can be done simply by running the Share: Page command again.
For the current page, these commands exist:
Share: Unshare: stops sharing the page, removing its share.* keys. The shared copy stays where it is.In push mode the page is not sent as it is. Its share.* keys are always removed (the rest of its frontmatter is published as it is), and these steps run first, switched on or off depending on where it goes:
links: a page is shared on its own, so wiki links to other pages turn into plain text and transclusions of them are removed: no dead links are published. Links to a header on the same page stay links, in the form the location understands (for GitHub a Markdown link to the anchor). Gists and other locations reduce all links to text.
comments: HTML comments (<!-- ... -->, both whole blocks and inline) are removed, apart from the markers of baked sections. The text around a removed comment keeps its paragraphs apart.
bake: live content such as queries and templates is replaced by its current result, when the place you publish to can’t run it. It is evaluated as the page being shared, whichever page is open.
SilverBullet space: links on, comments on, bake off.
GitHub file, Gist, anything else: links on, comments on, bake on.
Tool Pages (pages under Library/) and pages tagged meta or meta/... (such as templates) are published as they are, except that their share.* keys are removed.
To publish a page unchanged (apart from its share.* keys), add share.transform: false to its frontmatter. To turn off single steps, use a table:
share:
uri: https://github.com/me/notes/blob/main/Post.md
mode: push
transform:
bake: false
These steps only apply to push. Pull and sync copy the page as it is, only without the share.* keys. You can add your own steps with the share:transform service, see API/share.
Out of the box, sharing is supported for:
https:// URIs (Pull mode only) (implemented in ^Library/Std/Infrastructure/URI).https://github.com/* for repository files and https://gist.github.com/* URLs): both in Pull mode, and Push mode after signing in to Github through a device code (or with a personal token configured instead). Technically Sync should work except that Github aggressively caches files, making this impractical.To implement your own share provider, have a look at the implementations linked to understand how they work.