Sharing shelves · Library Hub

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#

In Settings → Library Hub → Sharing, choose Customize… on Recommendations (or New template…) and switch on the fields you want to share.
Open a shelf note and run Shelves: Share this shelf…; pick the template. This adds share: <template name> to the shelf note.
Add a recommendation property to the books you want to recommend (a sentence or two).
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 Books, 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:

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:

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.