Global Book Search

Global Book Search is an advanced metadata aggregation plugin for Obsidian. It facilitates the creation of comprehensive book notes by consolidating data from multiple international sources, scraping dynamic web content, and applying automated enrichment pipelines.

Table of Contents

• Core Architecture
• Search Modalities
• Metadata Sources
• Universal Enrichment Pipeline
• Template System and Variables
• Calibre Integration
• Mobile Optimization
• Installation and Credits

Core Architecture

The plugin is designed around a multi-stage extraction engine that prioritizes data integrity and depth. Unlike standard plugins that rely on a single API, Global Book Search uses a hybrid approach:

• Direct API Integration: Utilizes official REST APIs for Google Books and OpenLibrary.
• Resilient Web Scraping: Emplements custom parsing engines for Goodreads and StoryGraph to capture data not available via public APIs.
• Conflict Resolution: Merges data from multiple providers using a prioritized scoring system.

Search Modalities

[i] Global Search

Consolidates results from all configured services into a single unified view.

• Automatically deduplicates results by normalizing titles and authors.
• Displays source badges for each result to indicate data availability.
• Triggers the full enrichment pipeline upon selection.
• QR/Barcode Scanner: You can now point your camera at a physical book’s barcode to instantly trigger the extraction pipeline.

[i] Individual Service Search

Allows for targeted searching within a specific provider (e.g., searching only your local Calibre library or only StoryGraph).

Metadata Sources

StoryGraph (Advanced Scraper)

A high-resilience engine designed to bypass common scraping blocks.

• [!] Translator Extraction: Specifically targets and isolates translator information.
• [!] Edition Precision: Allows selection of specific editions (e.g., by publisher or cover).
• [!] JSON-LD Fallback: Parses structured metadata even when standard HTML elements are obscured.

Goodreads (Primary Enrichment)

The industry standard for social book metadata.

• [!] Rich Metadata: Captures original titles, total pages, and ASINs.
• [!] High-Res Covers: Automatically attempts to fetch the highest resolution available.

OpenLibrary and Google Books

Reliable fallbacks for ISBN validation and categorized genre data.

Universal Enrichment Pipeline

When a book is selected, the plugin initiates a sequential enrichment process:

1. Step 1: Primary Fetch: Retrieves full details from the selected source.
2. Step 2: Goodreads Fallback: If the primary source lacks an ISBN, the plugin searches Goodreads by title/author to recover the identifier.
3. Step 3: Multi-Source Bridge: Uses the ISBN to fetch missing fields (description, genres, publisher) from all other providers in parallel.
4. Step 4: Passive Enrichment (Fable.co): Scans Fable.co for high-quality descriptions and covers if still missing.
5. Step 5: Library of Congress (LoC): Validates publication dates and page counts against official records.

Template System and Variables

The plugin utilizes a Handlebars-based template system.

[!] Default Frontmatter Template (English)

The plugin provides localized default templates. Below is the English structure:

---
Title: "{{title}}"
Original title: "{{originalTitle}}"
Author: "{{author}}"
Translator: "{{translator}}"
Prologue: ""
Description: "{{description}}"
Total Pages: "{{totalPage}}"
Publisher: {{publisher}}
Categories: {{categories}}
isbn 10: "{{isbn10}}"
isbn 13: "{{isbn13}}"
Asin: {{asin}}
Published: {{publishDate}}
Date read:
Cover: "{{localCoverImage}}"
Link: {{link}}
Tags: {{tags}}
Read: false
---

[i] Supported Languages

[!] Default Language: The plugin initializes with the Spanish template by default. [i] Customization: You can choose and restore default templates for any of the following 11 languages directly from the settings menu:

• Spanish, English, French, German, Italian, Portuguese, Dutch, Russian, Simplified Chinese, Japanese, and Korean.

[!] Mandatory Tag Syntax

When using the {{tags}} variable in YAML, it must be wrapped in quotes to remain valid during the transformation process: tags: "{{tags}}" The plugin will automatically convert this into a proper YAML list format upon note creation.

Available Variables

• {{title}}: Current edition title.
• {{originalTitle}}: Original work title.
• {{author}}: Primary author.
• {{translator}}: Book translator (StoryGraph/Goodreads).
• {{description}}: Full summary.
• {{totalPage}}: Page count.
• {{publisher}}: Publishing house.
• {{publishDate}}: Publication date.
• {{isbn13}} / {{isbn10}}: Industry identifiers.
• {{asin}}: Amazon identification number.
• {{link}}: Direct link to the source book page.
• {{categories}}: List of genres and categories.
• {{localCoverImage}}: Locally saved cover. In Local cover mode this is a [[wikilink]]; in Remote mode it is the image URL.
• {{coverUrl}}: Remote URL of the cover image (available regardless of cover mode).
• {{tags}}: Automated author/name and libros/title tags.

Modifiers

Append :modifier to any variable to transform its output. Modifiers can be chained left-to-right:

• :raw — strip surrounding [[ ]] wikilink brackets, leaving the bare path.
• :url — URL-encode the value (spaces become %20), preserving / and : so it works for both vault paths and URLs.

Cover: "{{localCoverImage:raw:url}}"   →  Cover: "images/foo%20bar.png"
![[{{localCoverImage:raw}}|150]]       →  ![[images/foo bar.png|150]]

Variables without a modifier are unchanged, so existing templates keep working exactly as before.

LibraryThing "Common Knowledge" variables

The LibraryThing provider exposes extra literary metadata from a book's "Common Knowledge". These are not in the default frontmatter template — add the ones you want to your own template (they fill in only when LibraryThing has the data, and are empty for other providers):

• {{characters}} — main characters (e.g. Frederic Henry; Catherine Barkley)
• {{places}} — important places
• {{events}} — important events
• {{firstWords}} — opening line(s)
• {{lastWords}} — closing line(s)
• {{quotes}} — notable epigraph/quotes
• {{dedication}} — dedication
• {{blurbers}} — blurbers
• {{relatedMovies}} — related film adaptations
• {{originalLanguage}} — original language

Example template additions:

Characters: "{{characters}}"
Places: "{{places}}"
First words: "{{firstWords}}"
Original language: {{originalLanguage}}

Note: LibraryThing is behind Cloudflare's bot protection. The provider works only if your client can reach the site; it degrades gracefully (no results) otherwise.

[i] Duplicate Detection

To maintain vault organization, the plugin includes an automated safeguard:

• Vault Scanning: Before creating a note, the plugin checks for existing files with a matching title or ISBN.
• Action Prompts: If a match is found, you can choose to open the existing note, create a duplicate anyway, or cancel the operation.

Calibre Integration

To integrate with a local Calibre library, the Calibre Content Server must be active:

1. Enable Sharing over the net in Calibre Preferences.
2. Ensure the port (default 8080) is accessible.
3. [!] Calibre Workflows:
   • Search Calibre (Multi-Select): Allows batch importing via search results.
     • Enrichment Limit: If importing 5 or fewer books, the plugin performs full online enrichment (multi-source).
     • Batch Import: If selecting more than 5 books, enrichment is skipped to maintain performance, using only Calibre metadata.
   • Browse Calibre Library: Allows navigating your library by Author, Series, or Tag. This mode always uses local Calibre metadata exclusively to ensure instant results while browsing large collections.

Mobile Optimization

The interface has been specifically hardened for the Obsidian Mobile application (iOS/Android):

• [+] Responsive Modals: Search inputs and result lists automatically adapt to small viewports.
• [+] Keyboard Clearance: Modals are positioned to remain visible while the system keyboard is active.
• [+] Flexible Settings: Textareas and input fields in the settings panel utilize an adaptive vertical layout on mobile devices.

Installation and Credits

[i] Installation

1. Navigate to your Obsidian vault's hidden configuration folder: <vault>/.obsidian/plugins/.
2. Create a new directory named global-book-search.
3. Download the latest release files from the GitHub repository.
4. Place the following three files into the global-book-search folder:
   • main.js
   • manifest.json
   • styles.css
5. Open Obsidian and enable Global Book Search in the Community Plugins settings.

[i] Acknowledgments

• Based on the original obsidian-book-search-plugin by anpigon.
• Developed and maintained by DuckTapeKiller.