🔌 External Libraries

[janssen-io (Stan)]

External Libraries Plug for SilverBullet

Hello SilverBullet Community!

I’m excited to share a new plugin I’ve developed for SilverBullet. This plugin, External Libraries, allows you to seamlessly load pages from external sources like GitHub.

Key Features

• Easy Distribution: Effortlessly share templates, themes, scripts, and commands.
• Integration with GitHub: Load content directly from GitHub repositories. Content can also be previewed by hosting the shared markdown files on GitHub Pages.
• Enhanced Collaboration: Simplify the process of distributing and using shared resources.

Why External Libraries?

The Library functionality in SilverBullet allows you to share content between SilverBullet instances. External Libraries allows you to use any platform where you can host files to share content.

Platform flexibility brings the following benefits:

• Collaboration: This makes it easier to share community content such as themes, scripts and templates via a platform like GitHub, where others can also contribute.
• Cost: No need to buy/rent a server and storage to share your content publicly.
• Security: By using a third-party platform, you don’t need to worry about securing and maintaining your own server and network. You can safely keep your notes in a private SilverBullet instance.

Installation

Add the following plug to your PLUGS page:

- ghr:janssen-io/silverbullet-external-libraries

Loading an external library

Add the following block to your SETTINGS page:

externalLibraries:
- "gh://<user>/<repo>/Library/<library>"
- "https://example.com/path/to/Library/Name"

Requirements

1. the external library must still be a subdirectory inside a directory called Library
2. the parent directory (e.g., /Root/ in /Root/Library/MyTheme) must contain file named index.json that contains a list of all files.

Example

To load the LogseqDarkTheme from the repository janssen-io/silverbullet-libraries, you can use the following block:

externalLibraries:
- "gh://janssen-io/silverbullet-libraries/Library/LogseqDarkTheme"

As you can see the repository also contains an index.json in the root of the repository.

Learn More

For more details and installation instructions, check out the GitHub repository: GitHub - janssen-io/silverbullet-external-libraries.

[janssen-io (Stan)]

From now on I will publish versions via GitHub releases, so you can install the more stable version via:

ghr:janssen-io/silverbullet-external-libraries

The old install ‘link’ will still work, but it will download the development version. This version is less thoroughly tested and might be less stable.

[zef (Zef Hemel)]

Wow, this is really cool. Love the idea. I do wonder if this shouldn’t simply be merged into the core of SB though. To support both the federated libraries as before, as well as your more generic system.

What do you think?

[zef (Zef Hemel)]

What’s a bit of a shame usability wise, is that you still need to create an index.json file. Yes of course, you can automate the creation of this, but I’m wondering if it’s not somehow possible to leverage (some) Github API (for the GH resolver) that pulls a file list that way rather than depending on a static file in the repo. This may not be an option in general case (every resolver), but perhaps for some.

[janssen-io (Stan)]

[Should this be merged?]

It would be a great addition to the existing plug or as an extra ‘default’ plug, I think. Might be good to make it slightly more consistent with the other default plugs. For example, I use gh://, whereas the plugs plug uses github:.

---

[Use the GitHub API instead of index.json]

I hadn’t even considered using the Github API as an alternative to the index.json. Seems pretty easy to use:

Example of my library repo: https://api.github.com/repos/janssen-io/silverbullet-libraries/git/trees/main?recursive=1

Might be worth an update soon. Other resolvers can indeed implement whatever solution is best for them.

[janssen-io (Stan)]

The ‘edge’ version of this plug has been updated to be compatible with the current ‘edge’ version of SilverBullet. Thanks, @zeus-web, for bringing up the issue!

[zef (Zef Hemel)]

Head’s up: in time (not sure how soon) I will remove the libraries functionality as it exists today (as it relies on federation, which I’ll also remove (Who's using federation? - #10 by zef)).

With your permission @janssen-io I’d then move to basically including what you built here, but baked into SB core as the new “blessed” way to distribute libraries, because I think it’s better than the old way (which was pretty hard to use, unless you deployed a public read-only SB instance).

[janssen-io (Stan)]

That would be great, Zef! I can whip up a PR somewhere later this week hopefully, if you’d like.

If you think it’s better to add it yourself, then feel free to as well. I’m just looking for ways to contribute as I really love SilverBullet.

---

One thing to keep in mind:
Currently libraries do remove the entire folder first and then download the new ones. Mine just overwrites documents, but doesn’t delete ones that aren’t present anymore. So we might want to implement that still.

[zef (Zef Hemel)]

Yeah, I’m happy to take this. May rethink some details here.

Won’t do this just yet, there’s a couple of things I need to tackle and figure out first.

[nickb (Nick)]

Hi @janssen-io how do I access the ‘edge’ version?

Nick

[janssen-io (Stan)]

You can use the following “link” to install it:

github:janssen-io/silverbullet-external-libraries/external-libraries.plug.js

[zeus-web]

Zef also wrote a more detailed post about “living on the edge”

Living on the edge (builds)

If you’re a true SilverBullet enthusiast, just upgrading to the latest and greatest release may just not be edgy enough. Maybe you want to truly live on the bleeding edge, and always run the latest commit to the SilverBullet repo. I know I do. And I do. Every time new code is pushed to the main development branch, a new Docker image is released to zefhemel/silverbullet:edge within minutes, as well as a Deno build to https://edge.silverbullet.md/silverbullet.js. How to set this up First of all…

[nickb (Nick)]

Sure, but there’s no edge branch of external libraries plug to pull, and if there was what syntax would pull it?

[janssen-io (Stan)]

The main branch (github: syntax) of the plug is compatible with Edge.

The releases (ghr: syntax) is compatible with 0.10.4/stable.

If there are issues because of changes on Edge, I will fix them as soon as possible on the main branch.

Once a new version of SilverBullet is released as stable, I will also create a new release of the plug. (But hopefully once v2 is officially released, it will be part of SilverBullet itself)