Librarian

Librarian for Obsidian

Librarian is a comprehensive book-tracking and library management tool for Obsidian. It provides a local-first alternative to services like Goodreads by managing book metadata, reading progress, and personal libraries directly within your vault.

Introduction

Librarian transforms Obsidian into a sophisticated reading journal. It automates the creation of book notes using the Open Library API, manages reading states through non-destructive frontmatter updates, and provides high-level data visualization for your reading habits.

Key Features

Metadata Management

• Open Library Integration: Search and import book metadata including Title, Author, ISBN, Page Count, and Cover URLs.
• Custom Book Entry: Manually enter book details for titles not found in Open Library.
• Automated Note Generation: Create standardized book notes based on customizable templates.
• Custom Properties: Support for user-defined YAML properties alongside core tracking fields.

Reading Lifecycle Tracking

• State Management: Track books through "To-Read", "Currently Reading", "Finished", and "DNF" (Did Not Finish) states.
• Session Logging: Automatically records start and end dates for every reading session, supporting multiple re-reads.
• Header Actions: Injects functional UI elements directly into the Obsidian note header for frictionless state updates.

Library Organization & Visualization

• Bookshelves: Group books into custom shelves (e.g., "Reference", "Philosophy", "2024 Queue").
• Dynamic Folder Organization: Use placeholders like {{author}}, {{year}}, or {{subject}} in your default folder path to automatically sort new books into subfolders.
• Sidebar Views: Dedicated views for browsing your library by shelf and analyzing reading statistics.
• Statistical Analysis: Track total pages read, unique books completed, and drill down into specific date ranges. Lists are automatically sorted by most recently read.
• Reading Challenge: Set a personal yearly reading goal and track your progress in the Reading Stats view, complete with historical data from previous years.

Quote & Annotation Support

• Contextual Quotes: Quickly capture quotes with page numbers and tags.
• Block Referencing: Generates stable block IDs for easy embedding in other notes.
• Aggregation: Surface quotes across your entire library using dynamic code blocks.

Data Structure

Librarian relies on standardized YAML frontmatter. Below is an example of the data structure generated and managed by the plugin:

---
type: book
title: "Foundation"
author: "Isaac Asimov"
isbn: "9780553293357"
pages: 244
cover: "https://covers.openlibrary.org/b/id/10416358-L.jpg"
shelf: 
  - Classics
  - Sci-Fi
readCount: 1
currentlyReading: false
dateRead: 2024-03-01
readHistory:
  - start: 2024-02-15
    end: 2024-03-01
---

Usage Examples

The librarian Code Block

You can embed dynamic lists or quote aggregations into any note (e.g., your Daily Note) using the librarian code block.

Query reading history for a specific date:

```librarian
date: 2024-03-05
hideHeader: false
```

Aggregate quotes by tag:

```librarian
tag: philosophy
limit: 5
hideHeader: true
```

Custom Templates

Librarian allows you to define a Template file in the settings. This template controls the body content below the automatically managed frontmatter.

Available Placeholders

• {{title}}: The book's title.
• {{author}}: The primary author.
• {{pages}}: Page count.
• {{year}}: Publication year.
• {{cover}}: URL of the cover image.
• {{cover_image}}: Formatted markdown image (e.g., ![](https://raw.githubusercontent.com/lastratalive/Librarian/HEAD/url)).
• {{isbn}}: ISBN-10 or ISBN-13.
• {{id}}: Open Library Work ID.
• {{dateAdded}}: Date the book was added to your vault.
• {{subject}}: Primary subject/genre (also available for folder paths).
• {{firstLetter}}: First letter of the title (A-Z, useful for folder paths).

Template Example

Create a markdown file (e.g., templates/book-template.md) with the following content:

# {{title}} - {{author}}

{{cover_image}}

## Summary
(Write your summary here...)

## Quotes
> [!quote]
> Add your favorite quotes here.

## Notes
- 

Installation

From Community Plugins (Not Yet Available)

1. Open Obsidian Settings > Community Plugins.
2. Click Browse and search for "Librarian".
3. Click Install, then Enable.

Manual Installation (Development)

1. Clone this repository into your vault's .obsidian/plugins/ folder.
2. Install dependencies: npm install.
3. Build the plugin: npm run build.
4. Enable Librarian in the Obsidian Community Plugins settings.

Technical Details

• Language: TypeScript
• Network Disclosure: This tool makes external network requests to the Open Library API (https://openlibrary.org/) to search for book metadata and retrieve cover images. No personal data or vault content is ever sent to this or any other external service.
• Dependencies: Obsidian API, Open Library API
• License: 0-BSD

Roadmap

The following features are planned for future releases. Development will begin once the plugin is available in the Community Plugins directory.

Goodreads Import / Export

Migrate your existing reading history into Librarian from a Goodreads CSV export, or export your library back out. Goodreads data does not map cleanly to Open Library metadata, so this feature will hopefully include careful handling of edge cases such as missing ISBNs, mismatched titles, and multi-read histories.

---

Support the Project

If you find Librarian helpful and want to support its development, you can sponsor the project on GitHub!

Sponsor on GitHub

---

Developed by LastRatAlive