# Sharing shelves

> Publish a shelf, with covers and your recommendations, as schema.org JSON-LD and as notes a site can read.

A shelf of recommendations can leave your vault in a form any website can use. What leaves is decided by a **share template**, so a field you don't name never goes out.

## The quick way

1. In **Settings → Library Hub → Sharing**, choose **Customize…** on **Recommendations** (or **New template…**) and switch on the fields you want to share.
2. Open a shelf note and run **Shelves: Share this shelf…**; pick the template. This adds `share: <template name>` to the shelf note.
3. Add a `recommendation` property to the books you want to recommend (a sentence or two).
4. Run **Sync: Share shelves…**. You see what will be written. Choose **Share**.

Only a shelf with `share` is ever published. Undo with **Undo a notes sync**.

## What it writes

**JSON-LD** (the open format): in the template's folder (default `Shelf exports`), one `<shelf>.jsonld` per shelf, an `index.jsonld` listing them, and a `covers` folder. Each is a schema.org `ItemList` of `Book`s, with the author, cover, year, ISBN, series, a `review` (your rating and recommendation) and an `offers` entry for each buy link. A field with no schema.org property of its own is kept as an `additionalProperty`. A page can fetch the file, or embed it in a `<script type="application/ld+json">` block.

**Notes** (for a site that reads your vault): a folder note per shelf with the properties you set, and one note per book with a link to the book's own note, its place (`order`) and the recommendation as its body, cut to the limit you set. A book note carries other properties only if you list them under `fields` (and its links only with `links: true`), because a site that reads these notes often accepts only a few. Properties another tool adds to these notes (a site's sync adds `slug` and `updated`) are left as they are and never count as your edits, and a cover is copied beside the notes only if `cover` is one of those fields.

Everything is written inside your vault. Library Hub never publishes: your own sync or publishing tool carries the files from there.

## The template

A YAML file in the **Share templates** folder, edited with the form or by hand:

```yaml
name: Recommendations
publisher: Your name            # signs each review; leave out for unsigned
fields:
  - { from: title }
  - { from: authors }
  - { from: cover }
  - { from: isbn }
  - { from: recommendation }
  - { from: mood, as: Mood }    # any property of your book notes
links:
  - { label: Bookshop, url: "https://bookshop.org/search?keywords={title} {author}" }
  - { label: Reading notes, from: library_url }   # a property holding an address
outputs:
  jsonld: { folder: Shelf exports }
  notes: { folder: Shelf exports/notes, body: recommendation, bodyMax: 280, folderNote: { type: books, published: false }, bookLink: book, order: order, fields: [title] }
```

In a link address `{title}`, `{author}` and `{isbn}` are filled in, and a link whose value is missing is left out. A link from a property must be a web address or a path starting with `/`.

## Order

Books are ordered by `share_order` on the shelf note (a list of book note names), then by author.

## Give each book its own page

A site can show a page for every book, not only a card. Add a `summaries` block to the notes output:

```yaml
outputs:
  notes:
    folder: Web/Panels
    summaries:
      folder: Web/Book Summaries
      link: summary
```

Sharing then creates one **summary note** for each shared book in that folder, and puts a `summary` property on each panel note that links to it. A new summary note is an unpublished stub: it has `book` and `published: false`, and a place at the top for your own intro. Nothing is published by sharing.

- A book that already has a summary note, found by the `book` link in its properties, is not given a second one; its panel note links to the one it has.
- Once created, a stub is yours. Sharing never changes it, however you edit it, and never removes it, even when the book leaves the shelf.
- `publish: true` in the block is for the publish skill, which sets `published: true` after it writes a page.

## What it leaves alone

- A file already there that Library Hub did not write, or one you edited after it was shared, is left as it is and listed in the preview.
- A shelf you stop sharing has its files removed, but only the ones this plugin wrote and you have not edited.
- A cover you change is not copied again until you stop sharing the shelf and share it again.

## What it sends

Nothing. It reads your notes and writes files in your vault.