Zotero BibTeX Export Action

Fetch a Zotero collection (user or group) and export it to a cleaned BibTeX file with pinned citation keys.

Designed for reproducible bibliography builds in GitHub workflows.

✨ Features

• Supports personal libraries (users) and group libraries

• Fetches Zotero collections via the official API

• Preserves pinned citation keys (from Extra → Citation Key:, often generated by Better BibTeX)

• Cleans up common BibTeX formatting issues:

  • Nested braces in type = {…}

  • Acronym protection in titles

  • Converts journal = {...} to journaltitle = {...} for @article

  • Converts journal = {...} to organization = {...} for @online

• Configurable output path & filename

🔧 Inputs

Name	Required	Default	Description
api-key	✅ Yes	—	Zotero API key (create at Zotero API settings)
library-id	✅ Yes	—	Zotero userID (numeric) or groupID
coll-key	✅ Yes	—	Zotero collection key (e.g. 5SR8EG4D)
is-group	❌ No	false	Set to "true" if using a group library
out-bib-path	❌ No	references.bib	Where to write the .bib file

🔑 Getting Your IDs

• API key: Create at https://www.zotero.org/settings/keys

• User ID: Also visible on the API keys page (“Your userID for use in API calls”).

• Group ID: Found in the group’s URL (https://www.zotero.org/groups/<groupID>/...).

• Collection key: Last part of the collection URL (https://www.zotero.org/.../collections/<collKey>).

⚠️ Note: The API requires a numeric userID, not your username.

🚀 Usage

Personal library (default)

jobs:
  build-bib:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Export Zotero BibTeX
        uses: your-org/zotero-bibtex-action@v1
        with:
          api-key: ${{ secrets.ZOTERO_API_KEY }}
          library-id: ${{ secrets.ZOTERO_USER_ID }}
          coll-key: ${{ secrets.ZOTERO_COLLECTION_KEY }}
      - run: cat references.bib

Group library

jobs:
  build-bib:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Export Zotero BibTeX
        uses: your-org/zotero-bibtex-action@v1
        with:
          api-key: ${{ secrets.ZOTERO_API_KEY }}
          library-id: ${{ secrets.ZOTERO_GROUP_ID }}
          coll-key: ${{ secrets.ZOTERO_COLLECTION_KEY }}
          is-group: "true"
          out-bib-path: "docs/references.bib"
      - run: cat docs/references.bib

📦 Versioning

• Stable releases are tagged (e.g. v1.0.0).

• Use the v1 tag to always get the latest compatible release:

uses: your-org/zotero-bibtex-action@v1

🤝 Contributing

PRs and issues welcome! Please ensure:

• You test with both personal and group libraries

• You include sample .bib diffs in your PRs

📜 License

MIT — use, modify, and share freely.