69 lines
4.2 KiB
Markdown
69 lines
4.2 KiB
Markdown
A lot of useful functionality in SilverBullet is implemented through [[Templates]], as well as regular [[Pages]]. Some of these you will create yourself for your own specific use, but many are generic and generally useful. Libraries offer a way to _distribute_ sets of templates and pages easily, but also help to give some guidance on how to structure templates for your personal use.
|
||
|
||
# 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 widgets such as [[Table of Contents]] or [[Linked Mentions]]
|
||
* Useful pages that help you perform maintenance on your space, like detecting broken links, such as [[Library/Core/Page/Maintenance]].
|
||
|
||
# Configuring libraries
|
||
Libraries are managed by specifying them in [[SETTINGS]] under the `libraries` attribute. The paths used to libraries are using [[Federation]] page reference syntax.
|
||
|
||
When you set up a fresh space, the [[Library/Core]] is automatically configured:
|
||
|
||
```yaml
|
||
libraries:
|
||
- import: "[[!silverbullet.md/Library/Core/*]]"
|
||
```
|
||
|
||
If you would like to _exclude_ specific pages, for instance [[Library/Core/Widget/Table of Contents]], you can do so using the library’s `exclude` attribute
|
||
|
||
```yaml
|
||
libraries:
|
||
- import: "[[!silverbullet.md/Library/Core/*]]"
|
||
exclude:
|
||
- "[[!silverbullet.md/Library/Core/Widget/Table of Contents]]"
|
||
```
|
||
|
||
In these paths, you can also use the `*` wildcard:
|
||
|
||
```yaml
|
||
- "[[!silverbullet.md/Library/Core/Widget/*]]"
|
||
```
|
||
|
||
This would exclude all widgets specified in the Core library.
|
||
|
||
# Updating libraries
|
||
To update all libraries from their original source (we recommend doing this regularly to get the latest updates), run the {[Libraries: Update]} command.
|
||
|
||
Updating does the following for each library:
|
||
|
||
1. It _deletes_ all pages under its local source prefix in your space. For instance for the Core library, this would be `Library/Core/*`. This means that you should **not make local changes** to these files, because they will be wiped out on every update.
|
||
2. It downloads fresh copies from the `source` and puts them in the local source prefix (for `!silverbullet.md/Library/Core/*` this would be `Library/Core/`).
|
||
3. It performs a {[System: Reload]} so all new commands and configurations are immediately available.
|
||
|
||
# Where are libraries stored?
|
||
Libraries are kept in your space’s `Library/` folder. Since these are just regular [[Meta Pages]], the just live along the rest of your content. For instance, the [[Library/Core]] is kept under `Library/Core`. This is _largely_ a convention, but one worth to sticking to.
|
||
|
||
If you would like to keep your own templates as a library as well, we recommend putting them in `Library/Personal` as a convention. Then, when you identify a set that may be valuable to other people, you can move them elsewhere under `Library/`.
|
||
|
||
# Can I change libraries locally?
|
||
Technically there is nothing stopping you from making local changes to library content, however **these changes would be reset on every library update**.
|
||
|
||
Therefore, the recommended approach when requiring to make local adjustments is:
|
||
1. Make a copy (copy & paste or {[Page: Copy]}) of the page or template you want to change _outside_ the original library path, e.g. under `Library/Personal`.
|
||
2. _Exclude_ the page in question using the `exclude` attribute explained under [[#Configuring libraries]] and then run {[Libraries: Update]} again, to remove the excluded (non-modified) version of the page from your space.
|
||
3. Profit
|
||
|
||
# How to host a library?
|
||
This is a topic for exploration. The way it is done here at `silverbullet.md` is by running a SilverBullet instance with the libraries in read-only mode (see [[Install/Configuration#Run mode]]). However, we should explore easier ways to do this. Come talk to us in [the SilverBullet Community](https://community.silverbullet.md/) if you’re interested.
|
||
|
||
# What libraries exist?
|
||
Libraries are still a young concept in SilverBullet and therefore we’re still exploring how to organize and structure these.
|
||
|
||
Currently, we have the following libraries available:
|
||
* [[Library/Core]]: this is the library you want to use _for sure_. Just do it.
|
||
* [[Library/Journal]]: for the journalers among us.
|
||
|