Bundled translators

Better BibTeX bundles 5 translators you might care about:

Export

These translators are supported by the auto-export functionality built into Better BibTeX:

• Better BibLaTeX exports items in BibLaTeX format (but better, natch)
• Better BibTeX exports items in BibTeX format
• Better CSL JSON exports items in pandoc-compatible CSL-JSON format, with added citation keys and parsing of metadata
• Better CSL YAML exports the same as the Better CSL JSON exporter, but in YAML format
• Collected Notes exports just notes – standalone notes and notes attached to items, not the extra field – to HTML. This way, Zotero can serve as a (very) simple research notebook.

Import

• Better BibTeX exports and imports entries in Bib(La)TeX format

Included, but you should usually ignore it.

I would hide these if I could. They’re used for Zotero’s drag-and-drop citation facility, and for Better BibTeX debugging.

• BetterBibTeX JSON exports and imports items in BetterBibTeX debug format. The error reporter uses this format
• Better BibTeX Quick Copy exports citations to be copy-pasted into your LaTeX/Markdown document in the form \cite{< key >}/[@key]

Export

The Better BibTeX Configuration can be found under the regular Zotero preferences pane, tab ‘Better BibTeX’.

The configuration of Better BibTeX is a little baroque compared to the standard Zotero Bib(La)TeX exporters (which only have hidden preferences). The defaults should just work, but here’s an attempt to describe what they do.

Making any change here will drop your entire export cache. This is usually not a problem unless you have a really large library, but you can read about what is involved here.

BibTeX

Export unicode as plain-text latex commands (recommended)

default: yes

BibTeX has really spotty Unicode support, so you generally want this on. It will translate things like accented characters to their equivalent LaTeX constructs on export.

Disregard name prefixes when sorting

default: no

Name handling is a lot more complex than I had ever thought it to be. A lot more complex. BibTeX has really limited ways of dealing with names with particles (van, von, de, etc). If you turn this on, BBT will add code to have van Gogh sorted under Gogh.

Export numeric edition as English-written ordinals

default: no

Try to convert a numeric edition value to English words during BibTeX exports

Add URLs to BibTeX export

default: no

Most BibTeX styles do not support DOI/URL fields. Of the styles that do support them, many forget to load the required ‘url’ package, so make sure to load it yourself. DOI and URL fields are so-called ‘verbatim’ fields, and without the ‘url’ package loaded compilation will likely fail.

Options:

• no
• in the ’note’ field
• in the ’note’ field, but assuming the ‘url’ package is not loaded
• in the ‘url’ field
• in the ‘url’ field, but assuming the ‘url’ package is not loaded

BibLaTeX

Export unicode as plain-text latex commands

default: no

BibLaTeX actually has really good Unicode support, so you generally want this off. But for some geezers such as me it is simply more pleasing to have things like accented characters translated to their equivalent LaTeX constructs on export.

Use BibLaTeX extended name format (requires biblatex 3.5)

default: yes

Use the extended biber 2.7 format for names with particles - only works in BibLaTeX 3.5 or later. This biblatex has a new (less ambiguous) way to store creator names. It’s technically superior, but the LaTeX world moves slowly, so many people won’t have it yet. But if you’re an early adopter, you can enable it here

add use-prefix when family name has a prefix

default: yes

When a family name prefix is found, add useprefix=true

Fields

Fields to omit from export (comma-separated)

default: <not set>

If there are some fields you don’t want in your bibtex files (such as note for example), add a list of them here, separated by comma’s.

BibTeX/BibLaTeX

Export language as

default: langid

Export either langid, language or both fields based on the item language (if any).

Options:

• langid
• language
• both

When an item has both a DOI and a URL, export

default: both

Does what it says on the tin, really. If an item has both a DOI and an URL, you can choose to have them both exported, or either one of them. Note that for BibTeX, you must load the url package when you have doi or url fields. doi and url fields are so-called verbatim fields with different escaping rules, and BibTeX compilation will likely error out without the package loaded.

Options:

• both
• DOI
• URL

Include JabRef-specific metadata:

default: 0

Export JabRef-specific fields: timestamps, titles for attachments, and groups for each collection an item is part of. Note that having this on will disable caching in exports, which is really undesirable specifically for auto-exports.

Options:

• no
• for JabRef 3
• for JabRef 4
• for JabRef 5

Quick-Copy

Quick-Copy/drag-and-drop citations

Quick-Copy format

default: LaTeX citation

Used for drag-and-drop/quick copy using Better BibTeX citation keys. In the Zotero “Export” pane, choose Better BibTeX Quick Copy as the default export format for quick copy, and choose the desired format for the drag-and-drop citations here.

In the case of Eta templates, the selected items are available as it.items. <%= JSON.stringify(it.items) %> will show you the available data on the items.

Options:

• LaTeX citation
• Cite Keys
• Eta template
• GitBook
• org-ref citation
• org-ref v3 citation
• Org-mode citation link
• Org-mode select link
• Pandoc citation
• Roam Cite Key
• RTF Scan marker
• Zotero select link
• Jupyter notebook
• Jekyll cite

LaTeX command

default: cite

Used for drag-and-drop/quick copy citations in LaTeX format. Set the desired LaTeX citation command here. If you set this to citep, drag-and-drop citations will yield \citep{key1,key2,...}

Surround Pandoc citations with brackets

default: no

Used for drag-and-drop/quick copy citations in Pandoc format. You can use this option to select whether you want to have these pandoc citations surrounded with brackets or not.

Org-mode select link

default: using Zotero item key

OrgMode to select items in your library

Options:

• using Zotero item key
• using Better BibTeX citation key

Zotero select link

default: using Zotero item key

Hyperlink to select items in your library

Options:

• using Zotero item key
• using Better BibTeX citation key

Eta template

default: <not set>

Used for drag-and-drop/quick copy citations in Build your own format. This is going to get pretty technical, sorry. You can paste a Eta template here. Inside the template, you will find an array it.items, each of which is a serialized Zotero item. To find out what an item looks like inside the template, export some items as BetterBibTeX JSON.

postscript

Miscellaneous

Automatically abbreviate journal title if none is set explicitly

default: no

If set, generates journal abbreviations on export using the Zotero journal abbreviator, according to the abbreviation style selected in the list below the checkbox.

Sort TeX/CSL output (useful if you use version control on the output):

default: citation key (slower on very large libraries)

BBT sorts the output for TeX and CSL exports to have the output be versioning-friendly.

Options:

• off (fastest)
• item creation order (plenty fast)
• citation key (slower on very large libraries)

Include comments about potential problems with the exported entries

default: no

Generate quality reports for exported entries. These show up only in BibTeX and BibLaTeX report formats and indicate things like missing required fields and duplicate citation keys.

Include automatic tags in export

default: yes

Some importers or Zotero extensions (such as the ShortDOI manager for example) create tags on items that are more for item management than that they are descriptive of the item. When this is off, such tags will not be included in the export.

Apply title-casing to titles

default: yes

If you’re dead-set on ignoring both BibTeX/BibLaTeX best practice (see the BBT FAQ) and the Zotero recommendations on title/sentence casing, you can turn this off to suppress title casing for English items

Apply case-protection to capitalized words by enclosing them in braces

default: yes

If you’re dead-set on ignoring both BibTeX/BibLaTeX best practice (see the BBT FAQ) and the Zotero recommendations on title/sentence casing, you can turn this off to suppress automatic brace-protection for words with uppercase letters.

Cache

Enable caching for background exports

default: yes

Even though BBT exports happen in a separate thread, some work needs to be done before the background export can start. Part of this work is preloading the cache. You can shorten the (blocking) preparation time by turning off the cache, at the cost of longer export times.

Automatic export

The Better BibTeX Configuration can be found under the regular Zotero preferences pane, tab ‘Better BibTeX’.

The configuration of Better BibTeX is a little baroque compared to the standard Zotero Bib(La)TeX exporters (which only have hidden preferences). The defaults should just work, but here’s an attempt to describe what they do.

Making any change here will drop your entire export cache. This is usually not a problem unless you have a really large library, but you can read about what is involved here.

Automatic export

default: On Change

Determines when [automatic exports]({{ ref . “exporting” }}) are kicked off. Having it disabled still marks auto-exports as needing updates, so when you re-enable it, those exports will start. On-change means exports happen whenever an item in the export changes/is added/is removed. On idle does more or less what Disabled (that is, no exports but mark as needing changes), but will kick off exports when your computer is idle. You mostly want this if your computer is performance-constrained (aka slow).

Options:

• On Change
• When Idle
• Paused

Delay auto-export for

default: 5

If you have auto-exports set up, BBT will wait this many seconds before actually kicking off the exports to buffer multiple changes in quick succession setting off an unreasonable number of auto-exports. Minimum is 1 second. Changes to this preference take effect after restarting Zotero.

Import

The Better BibTeX Configuration can be found under the regular Zotero preferences pane, tab ‘Better BibTeX’.

The configuration of Better BibTeX is a little baroque compared to the standard Zotero Bib(La)TeX exporters (which only have hidden preferences). The defaults should just work, but here’s an attempt to describe what they do.

Making any change here will drop your entire export cache. This is usually not a problem unless you have a really large library, but you can read about what is involved here.

Insert case-protection for braces:

default: minimal

On import, BBT will add case-protection (<span class=“nocase”>…<span>) to titles that have words in {Braces}.

There’s plenty of bib(la)tex files out there that do this a little overzealously, and you may not like the resulting HTML code in your items, even though this is what the braces mean in bib(la)tex, and Zotero supports it.

If you turn this off, the markup is omitted during import. When you select ‘yes’, all braces that bib(la)tex would interpret as case protection (which is not all of them) are converted to span elements. In minimal mode, the number of span elements is minimized.

Options:

• minimal
• yes
• no

When scanning an AUX file, attempt to import entries from the attached bib file when their citation keys are not in Zotero

default: no

By default, when scanning for cited items in the aux file, BBT will just generate a note listing all citation keys it cannot find in Zotero. When this option is turned on, BBT will attempt to import such missing items from the bib file that the AUX file being scanned points to.

Sentence-case titles on import:

Sentence-case titles on import:

default: yes, but try to exclude already-sentence-cased titles

Bib(La)TeX entries must be stored in Title Case; Zotero items are expected to be entered as sentence-case.

With this option on, BBT will try to sentence-case during import. This sentence-casing uses heuristics, no natural language processing is performed, and the results are not perfect.

You can turn this off, but you may then also want to disable Apply title-casing to titles (which has its own problems, see the help entry for that option on this page). With ‘yes, but try to exclude already-sentence-cased titles’, BBT will attempt to detect titles that are already sentence cased and leave them as-is on import.

Options:

• yes, but try to exclude already-sentence-cased titles
• yes
• no (import titles as-is)

Migrate BetterBibTeX preferences/citation keys

Miscellaneous

The Better BibTeX Configuration can be found under the regular Zotero preferences pane, tab ‘Better BibTeX’.

The configuration of Better BibTeX is a little baroque compared to the standard Zotero Bib(La)TeX exporters (which only have hidden preferences). The defaults should just work, but here’s an attempt to describe what they do.

Making any change here will drop your entire export cache. This is usually not a problem unless you have a really large library, but you can read about what is involved here.

Fields

When merging items, also merge:

their citation keys into an bib(la)tex ids field

default: no

When merging items, also merge their citation keys into an bib(la)tex ids field.

fields that are understood to be CSL fields by Zotero

default: no

When merging items, also merge fields that are understood to be CSL fields by Zotero.

their tex.* fields

default: no

When merging items, also merge their tex.* fields.

@string definitions

Expand the @string vars below during imports

default: yes

When enabled, BBT will prepend the @strings section below to all Bib(La)TeX imports and will expand the strings during export.

If a field could be a @string reference, export it as an unbraced @string reference

default: No

When enabled, BBT will try to retain @string vars its exports unsurrounded by braces; when set to ‘detect’, single-word strings will be assumed to be externally-defined @string vars, when set to ‘match’, only @strings declared in the @strings section of the preferences will be preserved. If you don’t know what this means, leave it off.

Options:

• No
• Assume single-word fields to be @string vars
• Match against the @string declarations below
• Match against the @string declarations and their values below

Hidden preferences

The Better BibTeX Configuration can be found under the regular Zotero preferences pane, tab ‘Better BibTeX’.

The configuration of Better BibTeX is a little baroque compared to the standard Zotero Bib(La)TeX exporters (which only have hidden preferences). The defaults should just work, but here’s an attempt to describe what they do.

Making any change here will drop your entire export cache. This is usually not a problem unless you have a really large library, but you can read about what is involved here.

You can edit most Better BibTeX preferences through the Preferences window in Zotero. However, Better BibTeX supports additional hidden preferences. These settings are intended for more advanced use.

Zotero

To view the full list of Better BibTeX’s preferences, including many hidden preferences, go to the Advanced pane of the Zotero preferences and click “Config Editor”. Enter “better-bibtex” into the Filter field at the top of the list that comes up. Preferences that can be safely changed by users are described below.

The Better BibTeX hidden preferences are preceded by “extensions.zotero.translators.better-bibtex.”

ascii

default: <not set>

If you have unicode turned on you can still selectively replace some characters to plain-text commands; any characters entered here will always be replaced by their LaTeX-command counterparts.

autoExportIdleWait

default: 10

Number of seconds to wait after your system goes idle before kicking off auto-exports.

biblatexExtendedDateFormat

default: yes

Support for EDTF dates in biblatex

charmap

default: <not set>

a JSON mapping from single character to raw LaTeX, to augment the default mapping; these will be applied when you export as ASCII. DO NOT edit this preferencedirectly, but create a CSV (not semicolons) file named charmap.csv in the zotero data directory under the better-bibtex folder with columns unicode (the source character), text (representation in LaTeX text mode, if any) and math (representation in LaTeX math mode, if any, without dollar signs).

csquotes

default: <not set>

if you set csquotes to a string of character pairs, each pair will be assumed to be the open and close parts of a pair and will be replaced with a \\enquote{...} construct.

git

default: config

Can be off, config or always

import

default: yes

Use BBTs importer instead of Zotero’s importer

importCitationKey

default: yes

On import, assign the existing citation key to the item being imported

importDetectURLs

default: yes

On import, detect URLs in non-standard bib(la)tex fields and import them as attachments

importExtra

default: yes

On import, place all bib(la)tex field Zotero doesn’t have an existing field for in the Zotero extra field of the item

importJabRefAbbreviations

default: yes

Expand journal abbreviations to the full journal name on import.

importJabRefStrings

default: yes

During import, replace titles matching a list of common @string definitions with the value of that @string

importNoteToExtra

default: <not set>

On import, import note-like fields in this comma-separated list to the extra field, unless the note has rich text.

importPlaceEvent

default: inproceedings,conference,presentation,talk

During import of bib(la)tex, these types will be treated as event-like, in which case if an entry has both an location and an address field, the location will go to Zotero’s Place field. In all other instances, address will go to Place.

importSentenceCaseQuoted

default: yes

During import, also sentence-case quoted parts of titles

importUnknownTexCommand

default: ignore

What to do when encountering a TeX command the parser does not know about. Please only use values:

• ignore: ignore the command entirely
• tex: import and mark as TeX code, so on re-export it will be output as-is
• text: import without marking it as TeX code, so on re-export it will be treated as regular text

itemObserverDelay

default: 5

I’ve had reports where Zotero notifies extensions that items have changed, but if BBT then actually retrieves those same items, Zotero complains they “haven’t been saved yet”. Super. This preference sets the number of microseconds BBT should wait after being notified before acting on the changed items.

mapMath

default: <not set>

Any characters entered here will prefer a math-mode LaTeX-command counterpart over a text-mode mapping, if a math-mode command is available.

mapText

default: <not set>

Any characters entered here will prefer a text-mode LaTeX-command counterpart over a math-mode, if a text-mode command is available.

packages

default: <not set>

Some LaTeX commands only work when certain packages are loaded. By default, BBT will export Bib(La)TeX that requires no extra packages, but you can provide a comma-separated list here of packages to load to get higher fidelity export (for some admittedly niche characters). Details of these packages and what they add can be found [here]({{ ref . “exporting/unicode.md” }}).

parseParticles

default: yes

Name particle handling. Only turn on when requested and we’re talking about it on github.

patchDates

default: dateadded=dateAdded, date-added=dateAdded, datemodified=dateModified, date-modified=dateModified

Import translators cannot set the date-added and date-modified of the items that are imported, they always get the current time as their date-added. BBT will leave fields it can’t map as tex.[field] in the extra field of the item. If you enter a list of comma-separated field mappings here, like date-added = dateAdded, timestamp=dateModified, BBT will offer a menu option to remove them from the extra field and set the corresponding date of the item to their values, assuming they can be parsed as simple dates (no circa and stuff).

postscript

default: <not set>

Snippet of javascript to run [after each entry generation]({{ ref . “exporting/scripting.md” }}).

postscriptOverride

default: <not set>

You can use a custom postscript per export directory:

1. Edit the hidden preference postscriptOverride, and set it to a filename like postscript.js
2. In the directory where you intend to export to, create a file called postscript.js (or whatever you set the preference to) and add the postscript you want there
3. Export to that directory.

A postscript override will disable caching for that export.

preferencesOverride

default: <not set>

You can use custom preferences per export directory:

1. Edit the hidden preference preferencesOverride, and set it to a filename like preferences.json
2. In the directory where you intend to export to, create a file called preferences.json (or whatever you set the preference to), or called [bibfile you are exporting to].json and add the desired preference overrides in the format {"override": { "preferences": {"skipFields": "note"} } }. You can get your current preferences by exporting to BetterBibTeX JSON and removing everything except config.preferences, and renaming config to override.
3. Export to that directory.

A preferences override will disable caching for that export.

rawImports

default: no

When you set this on, BBT will import bib files leaving any LaTeX commands as-is, and add the #LaTeX tag for raw re-exports.

rawLaTag

default: #LaTeX

When an item has this tag, all its fields will be assumed to hold raw LaTeX and will undergo no further transformation. If you set this to *, all items will be assumed to have raw LaTeX.

relativeFilePaths

default: no

When exporting a Bib(La)TeX file, if the attachments are stored anywhere under the directory the bibliography is exported to, use relative paths to those attachments. Caching is disabled when this option is on, so it affects performance.

separatorList

default: and

Separator between list elements in list-type fields. You will need to add --listsep='|' to your biber calls.

separatorNames

default: and

Separator between author names. You will need to add --namesep='|' to your biber calls.

skipWords

default: a,ab,aboard,about,above,across,after,against,al,along,amid,among,an,and,anti,around,as,at,before,behind,below,beneath,beside,besides,between,beyond,but,by,d,da,das,de,del,dell,dello,dei,degli,della,dell,delle,dem,den,der,des,despite,die,do,down,du,during,ein,eine,einem,einen,einer,eines,el,en,et,except,for,from,gli,i,il,in,inside,into,is,l,la,las,le,les,like,lo,los,near,nor,of,off,on,onto,or,over,past,per,plus,round,save,since,so,some,sur,than,the,through,to,toward,towards,un,una,unas,under,underneath,une,unlike,uno,unos,until,up,upon,versus,via,von,while,with,within,without,yet,zu,zum

list of words to skip in title when generating citation keys

startupProgress

default: popup

Zotero takes a few seconds to start up, which is sometimes mistakenly attributed to BBT. BBT will tell you what phase the startup process is in (of Zotero and BBT) to prevent support requests for something that I cannot change. Please only use values:

• popup: show a popup during startup
• progressbar: show a progressbar in the top of the frame

strings

default: <not set>

If you have externally maintained @string vars paste them here and they will be resolved for subsequent imports. These should be entered as @string declarations, such as @string{IEEE_J_PWRE = "{IEEE} Transactions on Power Electronics"}, not just the var name.

stringsOverride

default: <not set>

You can use a custom @string list per export directory:

1. Edit the hidden preference stringstOverride, and set it to a filename like strings.bib
2. In the directory where you intend to export to, create a file called strings.bib (or whatever you set the preference to) and add the @string declarations you want there
3. Export to that directory.

A strings override will disable caching for that export.

verbatimFields

default: url,doi,file,pdf,ids,eprint,/^verb[a-z]$/,groups,/^citeulike-linkout-[0-9]+$/, /^bdsk-url-[0-9]+$/, keywords

list of fields to treat as verbatim during import. If you’re importing e.g. Mendeley-generated BibTeX, which is out of spec in various ways, try removing file from this list before import.

warnTitleCased

default: no

Both Zotero and BBT expect titles to be in sentence-case, but a lot of sites offer import data that is Title Cased. When exporting these titles to bib(la)tex you’re going to get a lot of extra unwanted braces, because all these Title Cased words will look like proper nouns to BBTs own title-casing mechanism. When this setting is on, you will be warned when you import/save items in Zotero with titles that look like they’re Title Cased, so that you can inspect/correct them.

Automatic export

To export a library, group or collection, right-click on it in the left Zotero pane and choose “Export Library…” or “Export Collection…”. With BBT’s export translators (e.g., “Better BibTeX”), checking the Keep updated option will register the export for automation. After you’ve completed the current export, any changes to the collection or library will trigger an automatic re-export to update the file. You can review/remove exports from the BBT preferences. While I’ve gone to some lengths to make sure performance is OK, don’t go overboard with the number of auto-exports you have going. Also, exporting only targeted selections over your whole library will get you better performance. You can set up separate exports for separate papers for example if you have set up a collection for each.

Managing auto-exports

There are two important concepts in play for auto-export

• register a collection/library for scheduled exports, and
• executing these scheduled exports

When you check “keep updated” in the export screen, that means “in the future, schedule this export for re-export when any of its items change, to the file I pick next”. If you do not check this checkbox, that merely means you are not registering the export you are doing, rather than undoing an auto-export you scheduled before.

When these scheduled exports are ran depends on a further configuration in the preferences. You can choose to have scheduled exports to be ran:

• on change: run the scheduled export as soon as possible
• on idle: run the scheduled export as soon as Zotero goes idle (meaning you haven’t used it for some seconds)
• paused: run the scheduled exports manually, or run then whenever you change the setting back to “on change” or “on idle”. In sthis mode, exports are still scheduled, they are just not ran until you give permission.

After you’ve set up an auto-export using an Keep updated export, you can manage your auto-exports in the BBT preferences under the Automatic exports tab. There, you can remove auto-exports or change settings on them. You cannot add new auto-exports from here, that can only be done by initiating an export.

Getting your BBT-generated bib(la)tex/citekeys to other places

You may want to use your BBT generated bib(la)tex on other systems; maybe you use Overleaf (as I do), maybe you have your documents compiled using github actions (as I do). In any case, you want your auto-exported items to show up somewhere else. If you’re thinking of this in the context of Overleaf, here’s a TL;DR of the pros and cons:

• Auto-export + cloud-sync + import by URL
  • pro: gets the full Better BibTex / Better BibLaTeX file into Overleaf
  • pro: free or already included in what you pay for your cloud service
  • con: requires cloud service which has direct-download links (Dropbox seems to offer this, as does Onedrive, but I haven’t tested this)
• Auto-export + Dropbox - Overleaf integration
  • pro: gets the full Better BibTex / Better BibLaTeX file into Overleaf
  • con: paid option on Overleaf
• Auto-export + git:
  • pro: gets the full bibtex file to Overleaf, tested and works
  • con: requires technical expertise to set up, paid option on overleaf
• citekey pinning:
  • pro: no setup, free
  • con: only gets the BBT citekeys, BibTeX is generated by Zotero itself

DropBox / Google Drive / Box.com / …

Or any other of the plethora of choices that are available today that will “cloud-sync” your files. Will work with any cloud service, as long as it delivers direct-download links, as this method will import into Overleaf by URL. 1.Export the Better Bibtex / Better LaTeX file into an cloud shared folder, with the “keep updated”-option checked 2.Create/generate/find a direct-download link. Google is your friend. 3.Import your cloud-saved bib-file into Overleaf by “Add file -> From external URL” 4.When adding new sources, refresh both the Zotero client, and click the “refresh”-button in the file on Overleaf

If working in a group, this can be accomplished by repeating step 1 for each person into the same cloud-shared folder. When doing step 1, make sure to use the same filename as the original bib-file. This will overwrite the bib-file every time the library is refreshed.

git support

BBT auto-export works nicely with git services (such as Overleaf, which is where I use it myself; the instructions for setting up Overleaf for git can be found here, but any git service (gitlab, github, etc) should work exactly the same. I’m toying with various online services here.

Note that this is more for the technically inclined, you will need to be comfortable with the command line to set this up. I can’t think of a real benefit to using git over cloud-sync unless, like me, you like to keep a backup history in git.

To activate git support, first clone the repo that holds your article/thesis/whatnot from your provider (github, overleaf, etc), run git config zotero.betterbibtex.push true in a command shell in that clone, and set up an auto export to that directory; at each update, BBT will now also push your library to the git service. For the technically curious, that means it does:

1. git pull
2. Performs the export
3. git add <your library file>
4. git commit -m <your library file>
5. git push

Note that the nature of git commit/push is not file-bound; if you made edits to other files, and added those, they will be committed and pushed along. If you want to be super-careful, the best way to go about it is to have a separate clone of your repo that BBT auto-exports to, and then another repo that you do your own edits in. I don’t use it myself this way, but you have been warned.

Pinning BBT citekeys for Overleaf

If you only want BBTs citation keys on Overleaf, you can simply pin them and use the regular Overleaf-Zotero integration. This will get you the pinned keys, but the bibtex is generated by the standard Zotero exporters. If you want this to be done by default, set autoPinDelay to a non-zero value.

Markdown/Pandoc

In addition to LaTeX, BBT plays very well with pandoc:

• you can drag and drop citations from Zotero into your markdown documents.
• you can cite as you write in your favorite editor with varying levels of comfort, mostly depending on how easy (VSCode, Sublime) or hard (looking at you Scrivener) it is to extend your editor.
• you can even convert your markdown document into a LibreOffice/Word document with actual live Zotero items as if you had entered them into Zotero all along (see below)

Use CSL, not bibtex with pandoc

Many tutorials on the use of pandoc to generate documents with citations seem to use bibtex as a bibliography format. I would encourage the use of CSL instead. Internally, both Zotero and pandoc-citeproc use CSL citation engines; the two options you have are:

Not only is the extra step through “pandoc-citeproc in convert mode” unnecesary, the translation between bibtex and CSL is complex and often lossy:

• Because Zotero primarily targets the built-in CSL processor, it assumes titles are stored in sentence case (as CSL styles assume sentence case); bibtex expects title case titles, so Zotero converts titles to title case on export to bibtex. “pandoc-citeproc in convert mode” will then take that title-cased bibtex and convert it back to sentence case. Neither Zotero nor pandoc-citeproc use natural language processing; the conversion between casing styles is largely done using heuristics. This conversion is imperfect, and you don’t gain any benefit from it.
• The item model of Zotero/CSL on the one hand and bibtex on the other has important differences, and in the conversion, choices must be made on what to put where, and what to drop. Zotero and pandoc-citeproc do not necessarily have the same business rules, and this unspoken difference can be another cause of loss.

All of these problems go away if you just skip the detour via bibtex and export (Better) CSL from Zotero and use that in your pandoc process.

From Markdown to Zotero live citations

You can convert a Pandoc-compatible markdown source to a LibreOffice or Word document with live citation fields connecting to Zotero.

• make sure you have pandoc version 2.16.2 or later.
• download the Pandoc filter
• optional: add some metadata to your markdown file in a YAML header:

---
# all the regular stuff you have here
zotero:
  library: <group name> # omitted to use your personal library
  scannable-cite: false # only relevant when you're compiling to scannable-cite .odt
  client: <zotero or jurism> # defaults to zotero
  author-in-text: false # when true, enabled fake author-name-only cites by replacing it with the text of the last names of the authors
  csl-style: apa # pre-fill the style
  sorted: true # sort clustered citations by author.
...

or you can specify them on the pandoc command line:

pandoc -s --lua-filter=zotero.lua --metadata=zotero_scannable_cite:true --metadata=zotero_client:jurism ...

And hey presto, a live LibreOffice/Word file, or an ODT file with scannable cites. When you first open the document with live citations, open the Zotero document preferences and click OK before you refresh, or you’ll get a confirmation popup for each citation. Also, the Word document is sometimes deemed corrupt when opening it, but running the pandoc command again without any changes fixes it ¯\_(ツ)_/¯ LibreOffice doesn’t recognise Zotero citations in DOCX, see issue #2070, and you must use ODT.

You can also specify transferable: true to create a transferable document. You don’t really need this for ODT or DOCX (just use Pandoc to create those directly using this filter), but it will allow transferring your document to GDocs.

Zotero needs to be running, with BBT installed, while you compile your document.

With regards to sorting citations within a cluster, this is how Zotero does it by default, where pandoc keeps citations in the order you entered them. You can override this by setting sorted to false, for example to retain a prefix at the front, but it may generated citations that are not style-compliant.

Pull export

You can fetch your bibliography on the url http://127.0.0.1:23119/better-bibtex/collection?[collectionID].[format] ¹. You can get this URL for a group, library or collection by right-clicking it and selecting Download Better BibTeX export...

You can add options to the export as URL parameters:

• &exportNotes=[true|false]
• &useJournalAbbreviation=[true|false]

You can fetch your library as part of your build, using something like curl from your Makefile, or with a BibLaTeX remote statement like

\addbibresource[location=remote]{http://127.0.0.1:23119/better-bibtex/collection?/0/8CV58ZVD.biblatex}

format can be:

• bib or biblatex for BibLaTeX
• bibtex for BibTeX
• json or csljson for CSL-JSON
• yaml, yml or cslyaml for CSL-JSON in YAML format
• jzon for BetterBibTeX JSON debug format
• the value of translatorID taken from the header of any existing Zotero translator to get an export in that translator format

addbibresource from pull export will only work if you are compiling your document on the same system your Zotero client with BBT runs on. Technically it can be made to work for pulling from other systems, but it’s even more arcane to set up than git support.

Note that as of Zotero 5.0.71, access to this URL will no longer work from the browser for security reasons; curl and other programmatic access will work.

Scripting

You wanted customized…

You got customized. If you go into the Export tab of the Better BibTeX preferences, subtab postscript, you will find a text box (empty by default) where you can edit a javascript snippet which will be executed for each entry generated in the Bib(La)TeX exporter. In this code, you have access to the entry just before it will be written out and cached. There is an API to do this, and it’s fairly stable, but usually you can just open a new issue and ask me to write it, and I’ll add it here (it’s how the examples got here). Postscripts are available in 4 of the translators:

1. BetterBibLaTeX
2. BetterBibTeX
3. BetterCSLJSON
4. BetterCSLYAML

You can (and totally should) check in which translator your postscript is running, which you can do by testing for Translator.<id> where <id> is one of these four names, using something like

if (Translator.BetterBibLaTeX) {
  ...
}

or alternately on the full name using a switch

switch (Translator.header.label) {
  case 'Better BibLaTeX':
    ...
    break;
  case 'Better BibTeX':
    ...
    break;
  case 'Better CSL JSON':
    ...
    break;
  case 'Better CSL YAML':
    ...
    break;
}

If you want to run a postscript in the CSL translators but don’t care whether it will output YAML or JSON, you can test for Translator.BetterCSL, which will be true when either one of BetterCSLJSON or BetterCSLYAML is active. Analogously, Translator.BetterTeX will be true if either of Better BibTeX or Better BibLaTeX is active.

In the postscript, the entry being built is available as tex (primary), entry, reference and this (legacy) in BetterTeX postscripts, or csl (primary), entry, reference and this in BetterCSL postscripts; the Zotero item it is being built from is available as zotero (primary) or item (legacy).

You should really test for the translator context in your postscripts using the Translator.<name> tests mentioned above. If you don’t because you have a postscript that pre-date postscript CSL support, you will probably be using the legacy use of this to set things on the entry being built, and calling tex.add in those postscripts; since, for CSL postscripts, this is not set, it will make the script will non-fatally error out, so you’re very probably good to go as-is. But please fix your postscripts to test for the translator context.

The API for Better BibTeX and Better BibLaTeX

The postscript should be a javascript snippet. You can access the data with following objects and methods:

• zotero is the Zotero item that’s the source for the entry being built.

• tex is the BibTeX entry you are building, and the entry has a number of fields.

  e.g. you can access the date in zotero item zotero.date.

• tex.has is a dictionary of fields for output.

• tex.date is the parsed and normalized version of zotero.date.

  e.g. you can see whether the year field has been set by testing for tex.has.year, and when e.g. for a season-date only the year is exported in bibtex, you can find it in tex.date.season

• tex.add is the function to add or modify keys in tex.has. It accepts the following named parameters in the form of an object:

  • name: name of the bib(la)tex field to output
  • value: the value for the field without LaTeX encoding
  • bibtex: the value for the field with LaTeX encoding already applied. If both bibtex and value are present, bibtex takes precedence
  • enc: specifies how to encode the value field. Valid values are:
    • latex: encode markup and special characters to LaTeX. This is the default, if you don’t provide an enc parameter, latex is assumed
    • verbatim: encode under verbatim rules
    • literal: encode under literal rules
    • raw: assume value is already LaTeX-encoded (same as passing the value in bibtex)
    • url: encode as verbatim url
  • sep: if value is an array, and enc is latex, encode each array element using latex and join the results with the string in sep. Defaults to an empty string.
  • html: boolean indicating whether the value is full HTML (really only useful for notes)
  • caseConversion: boolean indicating whether the field should have title-casing applied.

  e.g. change the value of year in output tex.add({name: 'year', value: "your_year_value"})

• tex.addCreators adds the contents of zotero.creators to tex.

  author encoding has a fair number of moving bits and generates multiple fields (author, editor, etc), this function is here so you can manipulate zotero.creators and call tex.addCreators to replace the existing creator fields on tex.

• tex.remove removes a field previously added by tex.add or tex.addCreators

The API for BetterCSLJSON and BetterCSLYAML

• csl is the CSL object being built. Any changes made to this object will directly change the CSL object being output.
• zotero is the Zotero item it’s being built from.

There isn’t really an API. You can use regular javascript to manipulate the csl object, which is a CSL-JSON object.

Item types and fields

In a postscript zotero.itemType will have one of these values:

Other fields on the zotero object are:

(types/fields marked ^Z are only available in Zotero, fields marked with ^JM are only available in Juris-M).

Debugging

There isn’t much in place in terms of debugging, as tranlators (and thus postscripts) are not allowed to do any UI work. You can do old-fashioned printf-style debugging by calling Zotero.debug(...) in your postscript – it will output the string you pass into the Zotero debug log which you can inspect from the Help menu. You can for example do Zotero.debug(JSON.stringify(item)) to see what the Zotero item looks like to the translator.

Samples

Add accessdate, url for BibTeX

Since BibTeX doesn’t really have well-defined behavior across styles the way BibLaTeX does, BBT can’t generate URL data which is compatible with all BibTeX styles. If you know the style you use yourself, you can add the data in the format you want using a postscript. The script below will add a note for the last accessed date, and a \url tag within the howpublished field, but only for BibTeX, not for BibLaTeX, and only for webpage entries:

if (Translator.BetterBibTeX && zotero.itemType === 'webpage') {
    if (zotero.accessDate) {
      tex.add({ name: 'note', value: "(accessed " + zotero.accessDate.replace(/\s*T?\d+:\d+:\d+.*/, '') + ")" });
    }
    if (zotero.url) {
      tex.add({ name: 'howpublished', bibtex: "{\\url{" + tex.enc_verbatim({value: zotero.url}) + "}}" });
    }
  }

Comma’s in keywords

If you want to retain commas in your keywords (e.g. for chemical elements) and separate with a comma-space, you could do:

if (Translator.BetterTeX) {
  tex.add({ name: 'keywords', value: zotero.tags, sep: ', ', enc: 'tags' });
}

as the default encoder knows what to do with arrays, if you give it a separator.

Add DOI in note field

if (Translator.BetterTeX && zotero.DOI) {
  var doi = zotero.DOI;
  if (doi.indexOf('doi:') != 0) { doi = 'doi:' + doi; }
  tex.add({ name: 'note', value: '[' + doi + ']' });
}

Add arXiv data

arXiv is a bit of an odd duck. It really isn’t a journal, so it shouldn’t be the journal title, and their own recommendations on how to include arXiv IDs is a little lacking: this doesn’t say where to include the arXiv:... identfier, and this says not to include it. Nor does it give any recommendations on how to achieve the desired output.

But for arguments’ sake, let’s say you get the desired output by including an empty journaltitle field (ugh) and stuff the arXiv:... ID in the pages field (ugh). You could do that with the following postscript:

if (Translator.BetterTeX && zotero.arXiv) {
  tex.add({ name: 'pages', value: zotero.arXiv.id });
  if (!tex.has.journaltitle) { tex.add({ name: 'journaltitle', bibtex: '{}' }); }
}

Custom field order

Specify the ordering of the listing of fields in an exported Biblatex/Bibtex entry. Your postscript:

if (Translator.BetterTeX) {
  // the bib(la)tex fields are ordered according to this array.
  // If a field is not in this list, it will show up after the ordered fields.
  // https://github.com/retorquere/zotero-better-bibtex/issues/512

  const front = ['author', 'date', 'title', 'publisher']
  const order = front.filter(field => tex.has[field]).concat(Object.keys(tex.has).filter(field => !front.includes(field)))
  for (const [field, value] of order.map(f => [f, tex.has[f]])) {
    delete tex.has[field]
    tex.has[field] = value
  }
}

In Zotero when using an Export Format of Better Biblatex we’ll get something like the following entry …

@book{nietzsche_1974_gay,
  author = {Nietzsche, Friedrich Wilhelm},
  date = {1974-03},
  title = {The {{Gay Science}}: {{With}} a {{Prelude}} in {{Rhymes}} and an {{Appendix}} of {{Songs}}},
  publisher = {{Random House}},
  origdate = {1882},
  shorthand = {GS},
  keywords = {Philosophy / General,Philosophy / History  Surveys / Modern},
  translator = {Kaufmann, Walter},
  timestamp = {2016-06-05T20:12:28Z},
  pagetotal = {407},
  shorttitle = {The {{Gay Science}}},
  isbn = {0-394-71985-9},
  edition = {1}
}

Further details Export to Biblatex/Bibtex. Custom field order. #512.

Case-protect italicized text

if (Translator.BetterTeX && tex.has.title) {
  tex.add({ name: 'title', value: zotero.title.replace(/(<i>)/ig, '<span class="nocase">$1').replace(/(<[/]i>)/ig, '$1</span>'))
}

Detect and protect LaTeX math formulas

if (Translator.BetterTeX && tex.has.title) {
  tex.add({ name: 'title', value: zotero.title.replace(/(\$.*?\$)/g, '<script>{$1}</script>') });
}

Or, detect and protect (simple) LaTeX commands

if (Translator.BetterTeX && tex.has.journal) {
  tex.add({ name: 'journal', value: tex.has.journal.value.replace(/(\\\w+)/g, '<script>{$1}</script>') });
}

Detect and protect MathJax

if (Translator.BetterTeX) {
  // different for bibtex and biblatex exporters
  const note = ['annotation', 'note'].find(field => tex.has[field])

  if (note) {
    let notes = zotero.notes.map(note => `<div>${note}</div>`).join('')
    notes = notes
      .replace(/(\$\$[\s\S]*?\$\$)/g, '<script>$1</script>')
      .replace(/\\\(/g, '<script>$')
      .replace(/\\\)/g, '$</script>')
    tex.add({ name: note, value: notes, html: true });
  }
}

Replace director with author for videoRecording and film entries

Creator handling is fairly complicated, so to change the authors/editors/creators of any kind, you must change them on zotero and then call addCreators to do the needful. addCreators will replace the existing creators that were added to tex with the current state in zotero.creators, however you left it.

if (Translator.BetterBibLaTeX) {
  switch (zotero.itemType) {
    case 'videoRecording':
    case 'film':
      for (const creator of zotero.creators) {
        if (creator.creatorType === 'director') creator.creatorType = 'author'
      }
      tex.addCreators();
      break;
  }
}

Changing the entry type from collection to book

if (Translator.BetterBibLaTeX) {
  if (tex.entrytype === 'collection') tex.entrytype = 'book'
}

Set the entry type to misc for arXiv preprints in BibTeX

if (Translator.BetterBibTeX && tex.entrytype === 'article' && zotero.arXiv) {
  if (tex.has.journal && zotero.arXiv.source === 'publicationTitle') {
    tex.remove('journal');
  }
  if (!tex.has.journal) tex.entrytype = 'misc'
}

Citing documents with a physical archive location

This is one area where some of the supposedly most popular packages – biblatex, biblatex-apa, biblatex-chicago, biblatex-mla – are all over the place, if they explicitly support archival material at all. There doesn’t seem to be a solution that caters for all of these and possibly other packages, too. biblatex has no special fields for dealing with info about physical archives, even if it does have provisions for electronic archives via the fields eprint (identifier), eprintclass (section of an archive), and eprinttype (name of the archive).

Of the packages mentioned above, only one (biblatex-mla) has a clear schema of how to record archival information (type @unpublished; fields number, library, location). Note that the library field is unique to biblatex-mla. (biblatex does define the field, but never uses it in its standard styles, and we find no indication that either biblatex-apa or biblatex-chicago would use it for a physical archive.)

Given all of this, I’m going to leave referencing of physical location to postscripts for now. If you enable the quality report, BBT will list Zotero fields with data that has not been used in the export:

@letter{MillionDemiInfirmes1968,
  title = {Un Million et Demi d'infirmes, Handicapés Physiques et Mentaux},
  date = {1968-05-31},
  url = {https://archives.strasbourg.eu/archive/fonds/FRAM67482_0592_114Z/view:115037},
  urldate = {2021-04-08},
  type = {Letter}
}
% == BibLateX quality report for MillionDemiInfirmes1968:
% Unexpected field 'title'
% Unexpected field 'type'
% ? Unused archive: Archives de la Ville et l'Eurométropole de Strasbourg
% ? Unused archiveLocation: 114 Z 1 248
% ? Unused callNumber: 114 Z 1 248

if you then apply a postscript such as

if (Translator.BetterBibLaTeX) {
  // biblatex-mla
  if (zotero.archive && zotero.archiveLocation) {
    tex.add({ name: 'type', value: tex.entrytype })
    tex.entrytype = 'unpublished'
    tex.add({ name: 'library', value: zotero.archive})
    tex.add({ name: 'number', value: zotero.archiveLocation })
  }
}

you get

@unpublished{MillionDemiInfirmes1968,
  title = {Un Million et Demi d'infirmes, Handicapés Physiques et Mentaux},
  date = {1968-05-31},
  url = {https://archives.strasbourg.eu/archive/fonds/FRAM67482_0592_114Z/view:115037},
  urldate = {2021-04-08},
  type = {letter},
  library = {Archives de la Ville et l'Eurométropole de Strasbourg},
  number = {114 Z 1 248}
}
% == BibLateX quality report for MillionDemiInfirmes1968:
% Unexpected field 'number'
% Missing required field 'author'

Export season for BibTeX

if (Translator.BetterBibTeX && tex.date.type === 'season') {
  tex.add({ name: 'month', value: ['', 'spring', 'summer', 'fall', 'winter'][tex.date.season] })
}

Adding rights field in BibLaTeX

if (Translator.BetterBibLaTeX) {
  tex.add({ name: 'rights', value: zotero.rights});
}

Use ~ in file paths to avoid the .bib file being different on different computers

For example on a Linux machine you might have /home/myname and on MacOS it is typically /Users/mypossiblyothername. If you sync a bib file on both to a git repo you will see a lot of diffs everytime due to them fighting each other.

if (Translator.BetterTeX && !Translator.options.exportFileData && zotero.attachments && zotero.attachments.length) {
  for (const att of zotero.attachments) {
    if (att.localPath) {
      att.localPath = att.localPath.replace(/^\/.*?\/.*?\//, '~/')
    }
  }
  tex.add({ name: 'file', value: zotero.attachments, enc: 'attachments' })
  return { cache: false }
}

From discussion here.

Adding file field for CSL JSON export

It can be useful to have paths to attachment files included in json files, which is currently not the case, see issue 518.

if (Translator.BetterCSLJSON) {
	csl.file = zotero.attachments.map(a => a.localPath).join(";");
}

Convert Windows attachment paths to Unix

if (Translator.BetterTeX && !Translator.options.exportFileData && zotero.attachments && Translator.exportPath.includes('\\\\')) {
  if (zotero.attachments) {
    tex.add({ name: 'file', bibtex: tex.enc_attachments({ value: zotero.attachments }, path => path.replace(/^[A-Z]:/i, '').replace(/\\\\/g, '/')) })
  }
}

Extra fields

In some cases the Zotero fields do not offer a place to enter the data you need to get your exported entries just right. For this Zotero has a so-called “cheater syntax” which allows you to add extra “fields” as separate lines in the extra field all items in Zotero have. These fields are supported by the citation processor inside Zotero, and BBT understands them too, and adds one “cheater syntax of its own.

You can add such fields by adding each on their own line in the following format:

Label: value

or the older format you migh have seen, which is supported but considered depracated:

{:csl-variable: value}

The full list of labels and the Zotero/CSL variables they translate to can be found in the table at the end.

These extra-fields are available to postscripts as extra.kv.<variable-name>. Which variable it is depends (sorry):

• when you export to CSL, it is attempted to map it to the corrsponding CSL fields; if none are available, it is available under their zotero name
• when you export to Better BibTeX/Better BibLaTeX, it is attempted to map it to the corresponding zotero fields; if none are available, it is available under their csl variable name

There’s three type of fields:

• text
• date
• name

Text is just that. For dates, BBT will do its darndest to parse the crazy dates so many people seem intent in using but if you want consistent results, stick to YYYY-MM-DD. For names, use either just text (equivalent to a single-part name in Zotero), or <family name> || <given name>.

BBT-specific

There is also a BBT-specific extra-field format that looks like

tex.field: value

These fields are simply copied to the output by BBT, so if you have

tex.bestfield: philosophy

you will end up with

  bestfield = {philosophy}

in the written bib(la)tex.

You can make BBT export the field only for bibtex or biblatex by changing the prefix to bibtex. (so bibtex.bestfield:) or biblatex. respectively. Finally, you can use = instead of : as a delimiter, and that will indicate to BBT that what follows the = is “raw LaTeX”; BBT will not do any escaping and just copy it out unchanged. This means, for example, that you would probably want

tex.corp: Black & Decker
tex.formula= $\sum\limits_{i=1}^{n} -p(m_{i})\log_{2}(p(m_{i}))$

and not

tex.corp= Black & Decker
tex.formula: $\sum\limits_{i=1}^{n} -p(m_{i})\log_{2}(p(m_{i}))$

BBT will apply case-protection rules for non-raw fields by including capitals in the prefix, eg

TeX.corp: Black & Decker

It is important to note that these BBT-specific fields are not recognized by any other exporter. They might end up in notes for some other exporters; there’s nothing I can do about that.

Label/variable list

note: I list the Zotero fields here, not the bibtex fields. The Zotero fields are translated to bibtex fields but that translation is pretty complicated and I don’t have a simple description of it at this time.

¹ only supported in Juris-M

Unicode

LaTeX en unicode

If you’re lucky and you live in the 21st century or later, you can just use unicode in BibLaTeX and you don’t have to bother about anything that follows except if you’re the curious kind.

Some of us though are bound to outlets that still demand BibTeX, and there’s geezers like me who just prefer the aesthetic of TeX commands over fancy-schmancy unicode, or you find TeX commands easier to search for in your doc than having to memorize how to enter Ψ. BBT has an extensive map of unicode characters, but translating unicode to TeX comes with a massive downside – support for non-ascii characters is scattered across a myriad of packages that you will have to usepackage into your document. The default set are supported by your latex distribution, and require nothing extra in your preamble, but to achieve that I’ve had to make some compromises. You can amend those choices by telling BBT you have extra packages available. BBT can export commands from the following packages:

wasysym

unicode-math