zotero-sync

README

zotero-sync

A fast, efficient synchronization tool for LaTeX references managed in Zotero, designed to integrate seamlessly with Neovim.

Overview

zotero-sync is a command-line tool that synchronizes bibliography references between Zotero's exported BibTeX file (Zotero.bib) and a local bibliography file (local.bib). It automatically extracts citation keys from LaTeX documents and ensures your local bibliography contains exactly the references you need.

Features

• 🔄 Synchronizes bibliography references: Creates and maintains a local BibTeX file containing only the references cited in your LaTeX documents
• 📄 Recursive processing: Automatically processes all included LaTeX files (\include and \input commands)
• 🔑 Citation key preservation: Preserves entries with older citation keys in your local bibliography to ensure documents still compile correctly
• 🚀 Performance: Optimized for speed, allowing it to run on each file save in Neovim
• 🔍 Smart detection: Supports various citation commands like \cite, \citep, \citet, etc.

Installation

Using the installer script

# Install to $HOME/.local/bin
curl -fsSL https://raw.githubusercontent.com/immofon/zotero-sync/main/manage.sh | bash -s -- install

# Install with custom path
curl -fsSL https://raw.githubusercontent.com/immofon/zotero-sync/main/manage.sh | bash -s -- install --dir <install directory>

# Uninstall
curl -fsSL https://raw.githubusercontent.com/immofon/zotero-sync/main/manage.sh | bash -s -- uninstall

Manual installation

1. Download the latest release from the GitHub Releases page
2. Extract the archive and move the binary to your preferred location
3. Ensure the binary is in your PATH

Build from source

git clone https://github.com/immofon/zotero-sync.git
cd zotero-sync
go build -o zotero-sync

Usage

Basic Usage

# Sync the local.bib file with cited references from current directory
zotero-sync sync

Advanced Options

# Specify custom paths
zotero-sync --zotero-bib ~/Documents/Zotero.bib --local-bib ./references.bib sync

# Process files in a different directory
zotero-sync --directory ./thesis sync

# Display verbose output
zotero-sync --verbose sync

Command-line Options

• --zotero-bib, -z: Path to the Zotero.bib file (default: ~/Downloads/My Library.bib)
• --local-bib, -l: Path to the local bibliography file (default: local.bib)
• --directory, -d: Directory to search for LaTeX files (default: .)
• --verbose, -v: Show verbose output

Integration with Neovim

You can integrate zotero-sync with Neovim by adding the following to your configuration file:

-- Sync bibliography on file save for LaTeX files
vim.api.nvim_create_autocmd("BufWritePre", {
  pattern = "*.tex",
  callback = function()
    vim.fn.system("zotero-sync sync")
  end,
})

How It Works

1. The tool scans all .tex files in the current directory and processes any included files recursively
2. It extracts all citation keys from various citation commands
3. It reads both Zotero.bib and local.bib (if it exists)
4. It creates a new local.bib file containing only the references cited in the LaTeX files
5. If a citation key exists in local.bib but not in Zotero.bib (e.g., the key was changed in Zotero), it keeps the entry from local.bib to ensure your documents still compile correctly

Development

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see the LICENSE file for details.