DOCSEARCHbyAlgolia
Submit Docs

ZotLit Documentation

repository·next·Indexed 21 days ago

https://github.com/aidenlx/zotlit

A bridge between Zotero and Obsidian that automates the creation of Markdown literature notes, citation management, and annotation syncing. Key features include a dedicated Annotation Workspace for PDF highlights, batch literature note workflows, Liquid and JavaScript templating, and a Template Data Explorer. ZotLit v2 (beta) supports per-device Zotero path configuration and an optional '@' trigger for citations.

Tokens
95.7K
Snippets
204
Records
483
Agent score
76%

What's inside ZotLit

  1. Overview of ZotLit Contexts

    next

    The ZotLit ecosystem is organized into several specialized contexts:

    • Zotero Data Model (@zotlit/db): Models Zotero's item hierarchy, identification, and query surface.
    • Obsidian Plugin: Manages literature notes, imported notes, templates, citations, and the services bridging Zotero data into an Obsidian vault.
    • Obsidian i18n (@zotlit/obsidian-i18n): Handles Messages, JSON Language Packs, and the headless Obsidian lifecycle.
    • ZotLit Protocol (@zotlit/protocol): Defines the wire format between the Zotero companion and the Obsidian plugin, utilizing permanent obsidian:// URIs and ephemeral version-gated HTTP requests.
    • ZotLit Documentation (@zotlit/docs): Defines the naming and framing rules for the official documentation site.

  2. Overview of ZotLit

    next

    ZotLit is a tool that connects your Zotero library to Obsidian. It allows you to transform Zotero items into Markdown literature notes using custom templates, search your library to insert citations directly in the editor, and view Zotero annotations in a dedicated sidebar. All data is stored as plain Markdown within your Obsidian vault.

    Key Capabilities:

    • Literature notes: Convert Zotero items to Markdown notes via a single command.
    • Citations: Search and insert citations without leaving the Obsidian editor.
    • Annotation view: A sidebar that displays highlights and notes synchronized with your active Zotero reader.
    • Note import: Import Zotero child and standalone notes as Markdown.
    • Syncing: Re-render notes to update metadata or use the Zotero companion for live updates from Zotero to Obsidian.
    • Templating: Use Liquid or Eta templates for notes, citations, and filenames.
    • Agent-assisted templates: Use AI agents to describe, edit, and test templates against your library.

  3. Summary of Zotero 7, 8, and 9 transitions

    next

    Zotero 7 → 8

    This was a major breaking transition involving:

    • Firefox-ESR jumps (115 → 128 → 140).
    • Full ESM-ification and removal of Bluebird.
    • Removal of several XPCOM interfaces.
    • Preference-pane scope changes.
    • Dropped support for macOS 10.14 and Windows 7-8.

    Zotero 8 → 9

    This is a thin release on top of Zotero 8 with the same JS runtime and plugin APIs. The primary changes are:

    • Additive Schema Change: Addition of the itemAttachments.dateLastOpened column and index for the 'Recently Read' collection.
    • Feature Additions: Read Aloud, web-based login, and group-library 'Added By'/'Modified By' fields.

  4. Understand the six ZotLit template types

    next

    ZotLit uses six template types to render different parts of your literature notes and citations. Each type receives data from Zotero and maps to a specific output. You can customize these by 'ejecting' the built-in default into your vault.

    TemplateSettings labelVault filenameWhat it renders
    filenameNote filenamezotlit-filename.liquid.mdFilename of a new literature note. Use / to route into subfolders.
    noteLiterature notezotlit-note.liquid.mdBody of a new literature note.
    annotationAnnotationzotlit-annotation.liquid.mdA single annotation.
    contentManaged regionzotlit-content.liquid.mdManaged region that is overwritten on note update.
    citeCitationzotlit-cite.liquid.mdCitation inserted into the editor.
    cite2Alternate citationzotlit-cite2.mdAlternate citation format.

  5. Configure Templates and use the Template Data Explorer

    next

    ZotLit v2 uses a Liquid-based template language by default for formatting Literature Notes, annotations, and citations. For advanced programmatic control, you can enable JavaScript Templates in the plugin settings.

    Template Data Explorer: Use the Template Data Explorer panel in Obsidian to view the exact, typed data available for any Zotero item. This allows you to write templates against verified field names and types (e.g., journal article vs. book) rather than guessing.

  6. Understand Obsidian CLI transport and connectivity

    next

    The Obsidian CLI communicates with the running Obsidian application via a Unix domain socket (macOS/Linux) or a Windows named pipe. It does not use second-instance or obsidian:// protocols.

    Important connectivity notes:

    • The CLI does not launch the Obsidian application; it only connects to an already running instance. If Obsidian is not running, the CLI will fail with an error.
    • On Windows, the CLI uses a named pipe. On macOS, it uses $HOME/.obsidian-cli.sock. On Linux, it uses $XDG_RUNTIME_DIR/.obsidian-cli.sock (falling back to $HOME/.obsidian-cli.sock).
    • The CLI uses a JSON header followed by bidirectional stdin/stdout streaming.
    | Platform | Address |
| --- | --- |
| Windows | `\\.\\pipe\\obsidian-cli-<username>` |
| macOS | `$HOME/.obsidian-cli.sock` |
| Linux | `$XDG_RUNTIME_DIR/.obsidian-cli.sock`, else `$HOME/.obsidian-cli.sock` |

  7. Resolve Zotero paths on multiple devices

    next

    ZotLit uses absolute filesystem paths for the Zotero profile and data directories. Because these paths differ between computers, ZotLit handles them as follows:

    • Auto-detection: ZotLit automatically detects the default Zotero profile (via profiles.ini) and data directory on each machine.
    • Device Overrides: If Zotero is in a non-default location, you can set a Device Override on that specific machine.
    • Sync Behavior: Overrides are stored locally (per vault, per device) and are never synced through the vault. This ensures that path settings on one computer do not overwrite settings on another.

  9. Integrate Obsidian i18n via injected ports

    next

    The @zotlit/obsidian-i18n package is designed to provide internationalization (i18n) capabilities to Obsidian plugins using an injected port pattern. This allows the package to remain decoupled from specific UI implementations while providing a secure, versioned contract for language packs.

    Key Integration Concepts

    • Injected Ports: Instead of hardcoding dependencies, the lifecycle accepts ports for language, device-storage, HTTP, and logging. This allows consuming plugins to provide their own implementations for these services.
    • Logging: Logging is handled via an injected StructuredLogger port. By default, this is a no-op, allowing consuming plugins to integrate their own logging stack (e.g., LogTape) without being forced into a specific implementation.
    • Locale Composition: The compiler emits a Locale Catalog (containing the base locale and remote pack filenames). The consumer is responsible for supplying the Pack Source (base URL and origin) and Locale Aliases. The lifecycle then composes these into usable pack URLs.
    • Runtime vs. Compiler: The package separates the Node-only compiler and Vite entry points from the browser-safe runtime and lifecycle, which are exported separately for use in consumer projects.

  10. Understand JavaScript Templates in ZotLit

    next

    JavaScript Templates (using the Eta engine) allow for full JavaScript execution within .eta.md template files and frontmatter fields declared with the javascript language.

    Unlike Liquid templates, which are restricted to text rendering and data combination, Eta templates have the same access as ZotLit itself: they can read/modify your vault, make network calls, and (on desktop) access your system.

    Because of these capabilities, JavaScript template execution is controlled by a per-device gate that is disabled by default to ensure security.

  11. Configure annotation view follow modes

    next

    The annotation view supports three distinct modes to determine which annotations are displayed:

    ModeBehavior
    Note (default)Follows the active literature note currently open in Obsidian.
    ReaderFollows the item currently open in the Zotero PDF reader. (Requires ZotLit server)
    LinkedPinned to a specific, manually chosen Zotero item.

    To use Linked mode, click the link button (tooltip: "Link to a Zotero item..."), search for your desired item, and select it. To return to default behavior, click the Unlink button.

  12. Understand truthiness in ZotLit templates

    next

    In Liquid, only nil (null/missing) and false are falsy. Values like 0, "" (empty string), and empty arrays are considered truthy.

    Note on ZotLit normalization: ZotLit normalizes empty-string field values to null before rendering. This means you can check for the existence of a field using a simple {% if zt.field %} check without needing to check for != "".