🔌 External Libraries

Plugs
1

External Libraries Plug for SilverBullet

Hello SilverBullet Community! :wave:

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"

:information_source: 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.

5 Likes
2

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.

3

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?

4

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.

5

[Should this be merged?]

It would be a great addition to the existing plug or as an extra ‘default’ plug, I think. :slight_smile: 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. :slight_smile:

6

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!

7

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).

8

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. :slight_smile:

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.

9

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.

1 Like