Citation keys

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.

Active citation key formula

default: auth.lower + shorttitle(3,3) + year

Set the pattern used to generate citation keys. The format of the keys is documented [here]({{ ref . “citing” }}).

Force citation key to plain text

default: yes

If you have deviated from the default citation key format pattern by [specifying your own]({{ ref . “citing” }}), you may wind up with non-ASCII characters in your citation keys. You can prevent that using the fold function at the appropriate place in your pattern, but checking this checkbox will just apply fold to all your keys.

Enable citation key search

default: yes

Enable searching on citation keys. Slows down startup on very large libraries. Requires Zotero restart to enable/disable.

Automatically pin citation key after

default: 0

When > 0, BBT will automatically pin the first citation keys it generates for an item after this many seconds.

Keeping citation keys unique

Ignore upper/lowercase when comparing for uniqueness

default: yes

Treat “AugusteComte” and “augustecomte” as the same key when testing for uniqueness

Keep keys unique

default: within each library

Auto-generated (non-pinned) keys automatically get a postfix when they would generate a duplicate. By default, the check for duplicates is restricted to the library/group the item lives in. When set to global, the check will include all libraries/groups, so auto-generated keys would be globally unique. Changing this setting does not affect existign keys - for this you would need to select the items and refresh the keys.

Options:

• across all libraries
• within each library

On conflict with a pinned key, non-pinned keys will be

default: kept (causes key duplicates)

This determines what happens if you pin a key to a value that is already in use in a different item but not pinned there. Neither are ideal, you just get to pick your poison. If you let BBT change the non-pinned key by adding a postfix character, the citation key changes which could be problematic for existing papers. If you keep the non-pinned key as-is, your library now has duplicate keys.

Options:

• postfixed (causes key changes)
• kept (causes key duplicates)

Ideographs in citekeys

Apply kuroshiro romajization in Japanese names/titles. Uses a lot of memory.

default: no

When on, BBT will load kuroshiro for romajization in citation keys. This uses a lot of memory, easily 100MB. If you don’t have Japanese titles/names, keep this off.

Enable ‘jieba’/‘pinyin’ filters in citekey patterns. Uses a lot of memory.

default: no

When on, BBT will make Chinese word segmentation (jieba) and transliteration (pinyin) available for citation keys generation. This uses a lot of memory, easily 70MB, and adds several seconds to the startup time of BBT. If you don’t have Chinese titles/names, keep this off.

Warn me when changing citation keys in bulk

default: 10

For those who are curious about what the Clear/Generate BibTeX key right-click options do, this will warn you if you are doing this on more than 10 (default) at the same time, to prevent your curiosity from changing all your citation keys at once.

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]

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:

• 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

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 reference.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:

<tr>
  
    <td>annotation<sup>Z</sup></td>
  
    <td>artwork</td>
  
    <td>attachment</td>
  
    <td>audioRecording</td>
  
</tr>

<tr>
  
    <td>bill</td>
  
    <td>blogPost</td>
  
    <td>book</td>
  
    <td>bookSection</td>
  
</tr>

<tr>
  
    <td>case</td>
  
    <td>classic<sup>JM</sup></td>
  
    <td>computerProgram</td>
  
    <td>conferencePaper</td>
  
</tr>

<tr>
  
    <td>dataset<sup>Z</sup></td>
  
    <td>dictionaryEntry</td>
  
    <td>document</td>
  
    <td>email</td>
  
</tr>

<tr>
  
    <td>encyclopediaArticle</td>
  
    <td>film</td>
  
    <td>forumPost</td>
  
    <td>gazette<sup>JM</sup></td>
  
</tr>

<tr>
  
    <td>hearing</td>
  
    <td>instantMessage</td>
  
    <td>interview</td>
  
    <td>journalArticle</td>
  
</tr>

<tr>
  
    <td>legalCommentary<sup>JM</sup></td>
  
    <td>letter</td>
  
    <td>magazineArticle</td>
  
    <td>manuscript</td>
  
</tr>

<tr>
  
    <td>map</td>
  
    <td>newspaperArticle</td>
  
    <td>note</td>
  
    <td>patent</td>
  
</tr>

<tr>
  
    <td>podcast</td>
  
    <td>preprint<sup>Z</sup></td>
  
    <td>presentation</td>
  
    <td>radioBroadcast</td>
  
</tr>

<tr>
  
    <td>regulation<sup>JM</sup></td>
  
    <td>report</td>
  
    <td>standard</td>
  
    <td>statute</td>
  
</tr>

<tr>
  
    <td>thesis</td>
  
    <td>treaty<sup>JM</sup></td>
  
    <td>tvBroadcast</td>
  
    <td>videoRecording</td>
  
</tr>

<tr>
  
    <td>webpage</td>
  
    <td></td>
  
    <td></td>
  
    <td></td>
  
</tr>

Other fields on the zotero object are:

<tr>
  
    <td>DOI</td>
  
    <td>ISBN</td>
  
    <td>ISSN</td>
  
    <td>abstractNote</td>
  
</tr>

<tr>
  
    <td>accessDate</td>
  
    <td>adminFlag<sup>JM</sup></td>
  
    <td>adoptionDate<sup>JM</sup></td>
  
    <td>album<sup>JM</sup></td>
  
</tr>

<tr>
  
    <td>applicationNumber</td>
  
    <td>archive</td>
  
    <td>archiveCollection<sup>JM</sup></td>
  
    <td>archiveID<sup>Z</sup></td>
  
</tr>

<tr>
  
    <td>archiveLocation</td>
  
    <td>artworkMedium</td>
  
    <td>artworkSize</td>
  
    <td>assemblyNumber<sup>JM</sup></td>
  
</tr>

<tr>
  
    <td>assignee</td>
  
    <td>audioFileType</td>
  
    <td>audioRecordingFormat</td>
  
    <td>authority<sup>Z</sup></td>
  
</tr>

<tr>
  
    <td>billNumber</td>
  
    <td>blogTitle</td>
  
    <td>bookAbbreviation<sup>JM</sup></td>
  
    <td>bookTitle</td>
  
</tr>

<tr>
  
    <td>callNumber</td>
  
    <td>caseName</td>
  
    <td>code</td>
  
    <td>codeNumber</td>
  
</tr>

<tr>
  
    <td>codePages</td>
  
    <td>codeVolume</td>
  
    <td>committee</td>
  
    <td>company</td>
  
</tr>

<tr>
  
    <td>conferenceDate<sup>JM</sup></td>
  
    <td>conferenceName</td>
  
    <td>country</td>
  
    <td>court</td>
  
</tr>

<tr>
  
    <td>date</td>
  
    <td>dateAmended<sup>JM</sup></td>
  
    <td>dateDecided</td>
  
    <td>dateEnacted</td>
  
</tr>

<tr>
  
    <td>dictionaryTitle</td>
  
    <td>distributor</td>
  
    <td>division<sup>JM</sup></td>
  
    <td>docketNumber</td>
  
</tr>

<tr>
  
    <td>documentName<sup>JM</sup></td>
  
    <td>documentNumber</td>
  
    <td>edition</td>
  
    <td>encyclopediaTitle</td>
  
</tr>

<tr>
  
    <td>episodeNumber</td>
  
    <td>filingDate</td>
  
    <td>firstPage</td>
  
    <td>format<sup>Z</sup></td>
  
</tr>

<tr>
  
    <td>forumTitle</td>
  
    <td>gazetteFlag<sup>JM</sup></td>
  
    <td>genre</td>
  
    <td>history</td>
  
</tr>

<tr>
  
    <td>identifier<sup>Z</sup></td>
  
    <td>institution</td>
  
    <td>interviewMedium</td>
  
    <td>issue</td>
  
</tr>

<tr>
  
    <td>issueDate</td>
  
    <td>issuingAuthority</td>
  
    <td>journalAbbreviation</td>
  
    <td>jurisdiction<sup>JM</sup></td>
  
</tr>

<tr>
  
    <td>label</td>
  
    <td>language</td>
  
    <td>legalStatus</td>
  
    <td>legislativeBody</td>
  
</tr>

<tr>
  
    <td>letterType</td>
  
    <td>libraryCatalog</td>
  
    <td>manuscriptType</td>
  
    <td>mapType</td>
  
</tr>

<tr>
  
    <td>medium</td>
  
    <td>meetingName</td>
  
    <td>meetingNumber<sup>JM</sup></td>
  
    <td>nameOfAct</td>
  
</tr>

<tr>
  
    <td>network</td>
  
    <td>newsCaseDate<sup>JM</sup></td>
  
    <td>numPages</td>
  
    <td>number</td>
  
</tr>

<tr>
  
    <td>numberOfVolumes</td>
  
    <td>openingDate<sup>JM</sup></td>
  
    <td>opus<sup>JM</sup></td>
  
    <td>organization<sup>Z</sup></td>
  
</tr>

<tr>
  
    <td>originalDate<sup>JM</sup></td>
  
    <td>pages</td>
  
    <td>parentTreaty<sup>JM</sup></td>
  
    <td>patentNumber</td>
  
</tr>

<tr>
  
    <td>place</td>
  
    <td>postType</td>
  
    <td>presentationType</td>
  
    <td>priorityDate<sup>JM</sup></td>
  
</tr>

<tr>
  
    <td>priorityNumbers</td>
  
    <td>proceedingsTitle</td>
  
    <td>programTitle</td>
  
    <td>programmingLanguage</td>
  
</tr>

<tr>
  
    <td>publicLawNumber</td>
  
    <td>publicationDate<sup>JM</sup></td>
  
    <td>publicationNumber<sup>JM</sup></td>
  
    <td>publicationTitle</td>
  
</tr>

<tr>
  
    <td>publisher</td>
  
    <td>references</td>
  
    <td>regnalYear<sup>JM</sup></td>
  
    <td>regulationType<sup>JM</sup></td>
  
</tr>

<tr>
  
    <td>regulatoryBody<sup>JM</sup></td>
  
    <td>reign<sup>JM</sup></td>
  
    <td>release<sup>JM</sup></td>
  
    <td>reportNumber</td>
  
</tr>

<tr>
  
    <td>reportType</td>
  
    <td>reporter</td>
  
    <td>reporterVolume</td>
  
    <td>repository<sup>Z</sup></td>
  
</tr>

<tr>
  
    <td>repositoryLocation<sup>Z</sup></td>
  
    <td>resolutionLabel<sup>JM</sup></td>
  
    <td>rights</td>
  
    <td>runningTime</td>
  
</tr>

<tr>
  
    <td>scale</td>
  
    <td>section</td>
  
    <td>series</td>
  
    <td>seriesNumber</td>
  
</tr>

<tr>
  
    <td>seriesText</td>
  
    <td>seriesTitle</td>
  
    <td>session</td>
  
    <td>sessionType<sup>JM</sup></td>
  
</tr>

<tr>
  
    <td>shortTitle</td>
  
    <td>signingDate<sup>JM</sup></td>
  
    <td>status</td>
  
    <td>studio</td>
  
</tr>

<tr>
  
    <td>subject</td>
  
    <td>supplementName<sup>JM</sup></td>
  
    <td>system</td>
  
    <td>thesisType</td>
  
</tr>

<tr>
  
    <td>title</td>
  
    <td>treatyNumber<sup>JM</sup></td>
  
    <td>type</td>
  
    <td>university</td>
  
</tr>

<tr>
  
    <td>url</td>
  
    <td>versionNumber</td>
  
    <td>videoRecordingFormat</td>
  
    <td>volume</td>
  
</tr>

<tr>
  
    <td>volumeTitle<sup>JM</sup></td>
  
    <td>websiteTitle</td>
  
    <td>websiteType</td>
  
    <td>yearAsVolume<sup>JM</sup></td>
  
</tr>

(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(RegExp("^\/.*?\/.*?\/"), "~/")
    }
  }
  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) {
	entry.file = item.attachments.map(a => a.localPath).join(";");
}

Convert Windows attachment paths to Unix

if (Translator.BetterTeX && !Translator.options.exportFileData && item.attachments && Translator.exportPath.includes('\\\\')) {
  if (item.attachments) {
    reference.add({ name: 'file', bibtex: reference.enc_attachments({ value: item.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