Citation Keys

Generating citekeys for your items

The BibTeX citations keys generated by the standard Zotero exporters are always generated at time of export, using an algorithm that usually generates unique keys. For serious LaTeX users, “usually” presents the following problems:

  • If a non-unique key is generated, which one gets postfixed with a distinguishing character is essentially non-deterministic.
  • The keys are always auto-generated, so if you correct a typo in the author name or title, the key will change
  • You can’t see the citation keys until you export them

For a LaTeX author, the citation keys have their own meaning, fully separate from the other entry data, even if people usually pick a naming scheme related to them. As the citation key is the piece of data that connects your bibliography, this is a piece of data you want to have control over. BBT offers you this control:

  • Stable citation keys, without key clashes. BBT generates citation keys that take into account other existing keys in your library in a deterministic way, regardless of what part of your library you export, or the order in which you do it.
  • BBT is conservative about citation key changes, and allows you to fix keys to any value of your choosing.
  • Generate citation keys from JabRef(-ish) patterns.

You can also

  • Drag and drop LaTeX citations using these keys to your favorite LaTeX editor
  • Show your citation keys in the item list view.

Set your own, fixed citation keys

By default, BBT generates the citation key from the item information, and this key may change when you edit the item. Such keys are called dynamic keys, which are marked with a pushpin the item list view and in the item details to distinguish them from dynamic keys.

You can fix the citation key (called pinning in BBT) for an item by adding the text Citation Key: <your citekey> anywhere in the extra field of the item on a line of its own. You can generate a pinned citation key by selecting one or more items, right-clicking, and selecting Generate BibTeX key, which will add the current citation key to the extra field, thereby pinning it.

Drag and drop/hotkey citations

You can drag and drop citations into your LaTeX/Markdown/Orgmode editor, and it will add a proper \cite{citekey}/[@citekey]/[[zotero://select...][@citekey]. The cite command is configurable for LaTeX by setting the config option in the preferences. Do not include the leading backslash.

This feature requires a one-time setup: choose the Quick Copy format under the Citation keys preferences for BBT, and go to Zotero preferences, tab Export, under Default Output Format, select “Better BibTeX Quick Copy: [format you just selected]”.

Find duplicate keys through integration with Report Customizer

The plugin will generate BibTeX comments to show whether a key conflicts and with which entry. BBT integrates with Zotero: Report Customizer to display the BibTeX key plus any conflicts between them in the zotero report.

Configurable citekey generator

BBT also implements a citekey generator for those entries that don’t have a citekey set explicitly; the formatter pattern language used to follow the JabRef key formatting syntax, but now uses a javascript-ish format. You can set your generator pattern in the Better BibTeX preferences (you can get there via the Zotero preferences, or by clicking the Better BibTeX “Preferences” button in the addons pane.

The default key pattern is auth.lower + shorttitle(3,3) + year; if you have papers that use keys which were generated by the key generator of the standard Bib(La)TeX exporters of Zotero you may want to use zotero.clean instead in order to ease migration from existing exports for people who previously used the standard Zotero Bib(La)TeX exports. You will be offered this choice on first run of BBT.

A common pattern is auth.lower + year, which means

  1. last name of first author without spaces, in lowercase
  2. year of publication if any,
  3. a letter postfix (a, b, c, etc) in case of a clash (this part is always added, you can’t disable it, although you can change it to Zotero-style numeric)

Changing a pattern will only affect items created/changed after you changed the pattern; existing keys are not automatically regenerated when you change the pattern. If you want your keys to update after a pattern change you will have to select your items, right-click, and select Refresh. This will not affect keys you have pinned.

If you want to get fancy, you can set multiple patterns separated by a vertical bar, of which the first will be applied that yields a non-empty string. If all return a empty string, a random key will be generated.

An example application for this behavior is to use the tex.shortauthor from the extra field when defined to generate short citation keys for entries with long group author names, but to default to auth.lower otherwise:

extra('tex.shortauthor').transliterate.clean.lower.len + year | auth.lower + year

You can add a verbatim text by just including it in single or double quotes:

extra('tex.shortauthor').transliterate.clean.lower.len + year | 'default' + auth.lower + year

Generating citekeys

To generate your citekeys, you use a formula composed of functions and filters. Broadly, functions grab text from your item, and filters transform that text. Note that the formula syntax has changed from a bracketed format to a javascript-ish format. The old syntax was getting harder to maintain and its inflexibility prevented new extensions to the functions being implemented cleanly. The old syntax still works and will be translated to the new format automatically and displayed below the old format if you use it. At some point not too far away, BBT will automatically upgrade old patterns and use those directly. But for now you can choose which format you use.

Below you will find a full list of functions and filters you can use, in the new format only, sorry. You can till use these in the old syntax, but they support only positional parameters, where I would recommend generally to use the new syntax with named parameters.

Functions

auth
parameters:
parametertypedescriptiondefault
nnumber

the number of characters to take from the name, 0 = all

+0
mnumber

select the mth author

1
creatorauthor / editor

select from authors or only from editors

'author'
initialsboolean

add author initials

false

The first n (default: all) characters of the mth (default: first) author's last name.

authAuthEa
parameters:
parametertypedescriptiondefault
creatorauthor / editor

select from authors or only from editors

'author'
initialsboolean

add author initials

false
sepstring

use this character between authors

'.'

The last name of the first two authors, and ".ea" if there are more than two.

authEtAl
parameters:
parametertypedescriptiondefault
creatorauthor / editor

select from authors or only from editors

'author'
initialsboolean

add author initials

false
sepstring

use this character between authors

' '

The last name of the first author, and the last name of the second author if there are two authors or "EtAl" if there are more than two. This is similar to auth.etal. The difference is that the authors are not separated by "." and in case of more than 2 authors "EtAl" instead of ".etal" is appended.

authEtal2
parameters:
parametertypedescriptiondefault
creatorauthor / editor

select from authors or only from editors

'author'
initialsboolean

add author initials

false
sepstring

use this character between authors

'.'

The last name of the first author, and the last name of the second author if there are two authors or ".etal" if there are more than two.

authForeIni
parameters:
parametertypedescriptiondefault
creatorauthor / editor

select from authors or only from editors

'author'

The given-name initial of the first author.

authIni
parameters:
parametertypedescriptiondefault
nnumber

the number of characters to take from the name, 0 = all

+0
creatorauthor / editor

select from authors or only from editors

'author'
initialsboolean

add author initials

false
sepstring

use this character between authors

'.'

The beginning of each author's last name, using no more than n characters (0 = all).

authorIni
parameters:
parametertypedescriptiondefault
creatorauthor / editor

select from authors or only from editors

'author'
initialsboolean

add author initials

false
sepstring

use this character between authors

'.'

The first 5 characters of the first author's last name, and the last name initials of the remaining authors.

authorLast
parameters:
parametertypedescriptiondefault
creatorauthor / editor

select from authors or only from editors

'author'
initialsboolean

add author initials

false

The last name of the last author

authorLastForeIni
parameters:
parametertypedescriptiondefault
creatorauthor / editor

select from authors or only from editors

'author'

The given-name initial of the last author.

authors
parameters:
parametertypedescriptiondefault
nnumber / [number, number]

select the first n authors (when passing a number) or the authors in this range (inclusive, when passing two values); negative numbers mean "from the end", default = 0 = all

+0
creatorauthor / editor

select type of creator (author or editor)

'author'
namestring

sprintf-js template. Available named parameters are: f (family name), g (given name), i (initials)

'%(f)s'
etalstring

use this term to replace authors after n authors have been named

''
sepstring

use this character between authors

' '
minnumber

skip to the next pattern if there are less than min creators, 0 = ignore

+0
maxnumber

skip to the next pattern if there are more than max creators, 0 = ignore

+0

Author/editor information.

authorsAlpha
parameters:
parametertypedescriptiondefault
creatorauthor / editor

select from authors or only from editors

'author'
initialsboolean

add author initials

false
sepstring

use this character between authors

' '

Corresponds to the BibTeX style "alpha". One author: First three letters of the last name. Two to four authors: First letters of last names concatenated. More than four authors: First letters of last names of first three authors concatenated. "+" at the end.

authshort
parameters:
parametertypedescriptiondefault
creatorauthor / editor

select from authors or only from editors

'author'
initialsboolean

add author initials

false
sepstring

use this character between authors

'.'

The last name if one author/editor is given; the first character of up to three authors' last names if more than one author is given. A plus character is added, if there are more than three authors.

clean
parameters:
parametertypedefault
enabledboolean

turn auto-cleaning on/off

date
parameters:
parametertypedescriptiondefault
formatstring

sprintf-style format template

'%Y-%m-%d'

The date of the publication

extra
parameters:
parametertypedescriptiondefault
variablestring

extra-field line identifier

A pseudo-field from the extra field. eg if you have Original date: 1970 in your extra field, you can get it as extra(originalDate), or tex.shortauthor: APA which you could get with extra('tex.shortauthor'). Any tex. field will be picked up, the other fields can be selected from this list of key names.

firstpage

The number of the first page of the publication (Caution: this will return the lowest number found in the pages field, since BibTeX allows 7,41,73--97 or 43+.)

inspireHep

Fetches the key from inspire-hep based on DOI or arXiv ID

journal
parameters:
parametertypedescriptiondefault
abbrevabbrev / abbrev+auto / auto / off

abbreviation mode

'abbrev+auto'

returns the journal abbreviation, or, if not found, the journal title, If 'automatic journal abbreviation' is enabled in the BBT settings, it will use the same abbreviation filter Zotero uses in the wordprocessor integration. You might want to use the abbr filter on this. Abbreviation behavior can be specified as abbrev+auto (the default) which uses the explicit journal abbreviation if present, and tries the automatic abbreviator if not (if auto-abbrev is enabled in the preferences), auto (skip explicit journal abbreviation even if present), abbrev (no auto-abbrev even if it is enabled in the preferences) or off (no abbrevation).

keyword
parameters:
parametertypedefault
nnumber

Tag number n. Mostly for legacy compatibility -- order of tags is undefined

language
parameters:
parametertypedescriptiondefault
nameame / american / american english / americanenglish / australian / australian english / australianenglish / austrian / austrian german / austrian-traditional / austriangerman / austriangerman-traditional / bri / british / british english / britishenglish / canadian / canadian english / canadianenglish / chinese / chinese-hans / chinese-hans-hk / chinese-hans-mo / chinese-hans-sg / chinese-hant / chinese-hant-hk / chinese-hant-mo / chinese-simplified / chinese-simplified-hongkongsarchina / chinese-simplified-macausarchina / chinese-simplified-singapore / chinese-traditional / chinese-traditional-hongkongsarchina / chinese-traditional-macausarchina / de / de-1901 / de-1996 / de-at / de-at-1901 / de-at-1996 / de-ch / de-ch-1901 / de-ch-1996 / de-de / deutsch / en / en-au / en-ca / en-en / en-gb / en-nz / en-us / eng / english / english-au / english-australia / english-ca / english-canada / english-gb / english-newzealand / english-nz / english-unitedkingdom / english-unitedstates / english-us / ger / german / german-at / german-at-traditional / german-austria / german-austria-traditional / german-ch / german-ch-traditional / german-switzerland / german-switzerland-traditional / german-traditional / ja / ja-ja / jap / japanese / nau / naustrian / new / newzealand / nge / ngerman / nsw / nswissgerman / schweizer hochdeutsch / swiss high german / swisshighgerman / swisshighgerman-traditional / ukenglish / usenglish / zh / zh-hans / zh-hans-hk / zh-hans-mo / zh-hans-sg / zh-hant / zh-hant-hk / zh-hant-mo / zh-zh / österreichisches deutsch / 中文 / 日本語

one or more language codes

Tests whether the item has the given language set, and skips to the next pattern if not

lastpage

The number of the last page of the publication (See the remark on firstpage)

len
parameters:
parametertypedescriptiondefault
relation!= / < / <= / = / > / >=

comparison operator

'>'
lengthnumber

value to compare length with

+0

If the length of the output does not match the given number, skip to the next pattern.

library

returns the name of the shared group library, or nothing if the item is in your personal library

month

the month of the publication

origdate

the original date of the publication

origyear

the original year of the publication

postfix
parameters:
parametertypedescriptiondefault
formatstring

sprintf-style format template

'%(a)s'
startnumber+0

a pseudo-function that sets the citekey disambiguation postfix using an sprintf-js format spec for when a key is generated that already exists. Does not add any text to the citekey otherwise. You must include exactly one of the placeholders %(n)s (number), %(a)s (alpha, lowercase) or %(A)s (alpha, uppercase). For the rest of the disambiguator you can use things like padding and extra text as sprintf-js allows. With +1 the disambiguator is always included, even if there is no need for it when no duplicates exist. The default format is %(a)s.

shorttitle
parameters:
parametertypedescriptiondefault
nnumber

number of words to select

3
mnumber

number of words to capitalize. 0 means no capitalization

+0

The first n (default: 3) words of the title, apply capitalization to first m (default: 0) of those.

shortyear

The last 2 digits of the publication year

title

Capitalize all the significant words of the title, and concatenate them. For example, An awesome paper on JabRef will become AnAwesomePaperJabref

type
parameters:
parametertypedescriptiondefault
allowedartwork / audioRecording / bill / blogPost / book / bookSection / case / classic / computerProgram / conferencePaper / dictionaryEntry / document / email / encyclopediaArticle / film / forumPost / gazette / hearing / instantMessage / interview / journalArticle / legalCommentary / letter / magazineArticle / manuscript / map / newspaperArticle / patent / podcast / preprint / presentation / radioBroadcast / regulation / report / standard / statute / thesis / treaty / tvBroadcast / videoRecording / webpage

one or more item type names

Tests whether the item is of any of the given types, and skips to the next pattern if not

veryshorttitle
parameters:
parametertypedescriptiondefault
nnumber

number of words to select

1
mnumber

number of words to capitalize. 0 means no capitalization

+0

The first n words of the title, apply capitalization to first m of those

year

The year of the publication

zotero

Generates citation keys as the stock Zotero Bib(La)TeX export does. Note that this pattern inherits all the problems of the original Zotero citekey generation -- you should really only use this if you have existing papers that rely on this behavior.

(type names marked JM are only available in Juris-M).

Note: All auth... functions will fall back to editors if no authors are present on the item.

Note: the functions above all have the clean filter (see below) applied to them by default. You can turn that off by passying clean=false.

Direct access to unprocessed fields

The above functions all retrieve information stored in the item’s fields and process it in some way. If you don’t want this, you can instead call field contents without any processing. To access Zotero fields, refer to them as given in the table below:

AbstractNote AccessDate AdminFlagJM AdoptionDateJM
AlbumJM ApplicationNumber Archive ArchiveCollectionJM
ArchiveIDZ ArchiveLocation ArtworkMedium ArtworkSize
AssemblyNumberJM Assignee AudioFileType AudioRecordingFormat
BillNumber BlogTitle BookAbbreviationJM BookTitle
CallNumber CaseName Code CodeNumber
CodePages CodeVolume Committee Company
ConferenceDateJM ConferenceName Country Court
DOI Date DateAmendedJM DateDecided
DateEnacted DictionaryTitle Distributor DivisionJM
DocketNumber DocumentNameJM DocumentNumber Edition
EncyclopediaTitle EpisodeNumber FilingDate FirstPage
ForumTitle GazetteFlagJM Genre History
ISBN ISSN Institution InterviewMedium
Issue IssueDate IssuingAuthority JournalAbbreviation
JurisdictionJM Label Language LegalStatus
LegislativeBody LetterType LibraryCatalog ManuscriptType
MapType Medium MeetingName MeetingNumberJM
NameOfAct Network NewsCaseDateJM NumPages
Number NumberOfVolumes OpeningDateJM OpusJM
OriginalDateJM Pages ParentTreatyJM PatentNumber
Place PostType PresentationType PriorityDateJM
PriorityNumbers ProceedingsTitle ProgramTitle ProgrammingLanguage
PublicLawNumber PublicationDateJM PublicationNumberJM PublicationTitle
Publisher References RegnalYearJM RegulationTypeJM
RegulatoryBodyJM ReignJM ReleaseJM ReportNumber
ReportType Reporter ReporterVolume RepositoryZ
ResolutionLabelJM Rights RunningTime Scale
Section Series SeriesNumber SeriesText
SeriesTitle Session SessionTypeJM ShortTitle
SigningDateJM StatusJM Studio Subject
SupplementNameJM System ThesisType Title
TreatyNumberJM Type University Url
VersionNumber VideoRecordingFormat Volume VolumeTitleJM
WebsiteTitle WebsiteType YearAsVolumeJM

(fields marked JM are only available in Juris-M).

Filters

abbr

Abbreviates the text. Only the first character and subsequent characters following white space will be included.

acronym
parameters:
parametertypedescriptiondefault
liststring

lookup list. The list must be a CSV file and live in the Zotero/better-bibtex directory in your Zotero profile, and must use commas as the delimiter.

'acronyms'

Does an acronym lookup for the text.

alphanum

clears out everything but unicode alphanumeric characters (unicode character classes L and N)

ascii

removes all non-ascii characters

capitalize

uppercases the first letter of each word

clean

transliterates the citation key and removes unsafe characters

condense
parameters:
parametertypedescriptiondefault
sepstring

replacement character

''

replaces spaces in the value passed in. You can specify what to replace it with by adding it as a parameter, e.g .condense(_) will replace spaces with underscores. Equivalent to .replace(/\s+/g, sep).

default
parameters:
parametertypedescriptiondefault
textstring

literal text to return

Returns the given text if no output was generated

discard

discards the input

fold
parameters:
parametertypedescriptiondefault
modechinese / german / japanese

specialized folding modes for german, japanese or chinese

tries to replace diacritics with ascii look-alikes. Removes non-ascii characters it cannot match

formatDate
parameters:
parametertypedescriptiondefault
formatstring

sprintf-style format template

'%Y-%m-%d'

formats date as by replacing y, m and d in the format

jieba

word segmentation for Chinese items. Uses substantial memory; must be enabled under Preferences -> Better BibTeX -> Advanced -> Citekeys

kuromoji

word segmentation for Japanese items. Uses substantial memory; must be enabled under Preferences -> Better BibTeX -> Advanced -> Citekeys

len
parameters:
parametertypedescriptiondefault
relation!= / < / <= / = / > / >=

comparison operator

'>'
lengthnumber

value to compare length with

+0

If the length of the output does not match the given number, skip to the next pattern.

localTime

transforms date/time to local time. Mainly useful for dateAdded and dateModified as it requires an ISO-formatted input.

lower

Forces the text inserted by the field marker to be in lowercase. For example, auth.lower expands to the last name of the first author in lowercase.

match
parameters:
parametertypedescriptiondefault
matchRegExp / string

regex or string to match. String matches are case-insensitive

cleanboolean

transliterates the current output and removes unsafe characters during matching

false

If the output does not match the given string/regex, skip to the next pattern.

nopunct
parameters:
parametertypedefault
dashstring'-'

Removes punctuation

nopunctordash

Removes punctuation and word-connecting dashes. alias for nopunct(dash='')

numeric

returns the value if it's an integer

postfix
parameters:
parametertypedescriptiondefault
postfixstring

postfix string

postfixes with its parameter, so postfix(_) will add an underscore to the end if, and only if, the value it is supposed to postfix isn't empty

prefix
parameters:
parametertypedescriptiondefault
prefixstring

prefix string

prefixes with its parameter, so .prefix(_) will add an underscore to the front if, and only if, the value it is supposed to prefix isn't empty.

replace
parameters:
parametertypedescriptiondefault
findstring / RegExp

string or regex to match. String matches are case-insensitive

replacestring

literal text to replace the match with

replaces text, case insensitive when passing a string; .replace('.etal','&etal') will replace .EtAl with &etal

select
parameters:
parametertypedescriptiondefault
startnumber

first word to select (1-based)

1
nnumber

number of words to select. Default is all.

selects words from the value passed in. The format is select(start,number) (1-based), so select(1,4) or select(n=4) would select the first four words. If n is not given, all words from start to the end are selected.

skipwords

filters out common words like 'of', 'the', … the list of words can be seen and changed by going into about:config under the key extensions.zotero.translators.better-bibtex.skipWords as a comma-separated, case-insensitive list of words.

If you want to strip words like 'Jr.' from names, you could use something like [Auth:nopunct:skipwords:fold] after adding jr to the skipWords list. Note that this filter is always applied if you use title (which is different from Title) or shorttitle.

splitIdeographs

Treat ideaographs as individual words

substring
parameters:
parametertypedescriptiondefault
startnumber

starting character (1-based)

1
nnumber

number of characters to select (default: remainder from start)

substring(start,n) selects n (default: all) characters starting at start

transliterate
parameters:
parametertypedescriptiondefault
modechinese / de / german / ja / japanese / minimal / zh

specialized translateration modes for german, japanese or chinese. default is minimal

transliterates the citation key. If you don't specify a mode, the mode is derived from the item language field

upper

Forces the text inserted by the field marker to be in uppercase. For example, [auth:upper] expands the last name of the first author in uppercase.

Usage note: the functions condense, skipwords, capitalize and select rely on whitespaces for word handling. Most functions strip whitespace and thereby make these filter functions sort of useless. You will in general want to use the fields from the table above, which give you the values from Zotero without any changes. The fields with ** are only available in Juris-M.