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:
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:
You can also
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.
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]”.
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.
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.
Better BibTeX knows four kinds of “things” to build the citekey from:
shorttitle
. Even though these are largely case insensitive, they must start with a lowercase letter.(auth + title || year)
. these are fully case insensitive, and you can chain these together, each acting on the output of the previous filter.There are 3 ways you can build subformulae:
(auth + title)
(auth || title)
(use the first thing that returns any text, so auth
if that returns text, otherwise title
).(auth ? year : title)
(if auth
returns any text, use year
, otherwise use title
). Ternary operators have the format condition ? output_if_true : output_if_false
, and you can use it like an if-or statement.these can be combined, eg (auth || shorttitle || year) ? (auth + title) : (year || title)
, but subformulae cannot appear in parameters, so title.select(auth ? 3 : 4)
is not valid. Filters (explained below) can be applied to subformulae, so (title || auth).lower
checks whether the title
function produces output (i.e. not empty). If it does, the title
function is used; otherwise, the formula will use the auth
function. It then converts the output of (title || auth)
to lowercase.
You can also explicitly test whether a formula part is not empty and jump to the next formula if not:
title.lower.len + year; auth + year
which would have the formula evaluate whether the title
function returns a non-empty text; if this condition is not met, formula evaluaton jumps to the next formula auth + year
. You can also test for a minimal length using eg
title.len('>',1) + year | auth + year
which checks whether the title
output is longer than 1 character.
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.
auth.lower + shorttitle(3,3) + year
, means
.lower
filtern
(default: 3) words of the title, apply capitalization to first m
(default: 0) of those.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 semicolon (;
) or 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
Formulas have some ternary and or-style choice support; you can use them in formulas instead of a function, but not in parameters; you can for example use
(title ? title : auth).lower + year
or
(title || auth).lower + year
instead of
title.len + year | auth + year
and you can test for length of subsections; what you would previously do with
auth + title + len + year
to jump to the next formula if auth
and title
were both empty is now
(auth + title).len + year
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 but will be translated to the new format automatically.
Below you will find a full list of functions and filters you can use, in the new format only, sorry. You can still 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.
Note: a number of functions below talk about the author’s lastname; you can read that as “when available”. If you have the name as a single-field name (for entities like International Business Machines
or Aristoteles
), Zotero doesn’t have a last name, and the full single-field name is taken instead.
auth
parameter | type | description | default |
---|---|---|---|
n | number | the number of characters to take from the name, 0 = all | 0 |
m | number | select the | 1 |
creator | author / editor / translator / collaborator / * | kind of creator to select, | "*" |
initials | boolean | add author initials | false |
The first n
(default: all) characters of the m
th (default: first) author's last name.
authAuthEa
parameter | type | description | default |
---|---|---|---|
creator | author / editor / translator / collaborator / * | kind of creator to select, | "*" |
initials | boolean | add author initials | false |
sep | string | use this character between authors | "." |
The last name of the first two authors, and ".ea" if there are more than two.
authEtAl
parameter | type | description | default |
---|---|---|---|
creator | author / editor / translator / collaborator / * | kind of creator to select, | "*" |
initials | boolean | add author initials | false |
sep | string | 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
parameter | type | description | default |
---|---|---|---|
creator | author / editor / translator / collaborator / * | kind of creator to select, | "*" |
initials | boolean | add author initials | false |
sep | string | 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
parameter | type | description | default |
---|---|---|---|
creator | author / editor / translator / collaborator / * | kind of creator to select, | "*" |
The given-name initial of the first author.
authIni
parameter | type | description | default |
---|---|---|---|
n | number | the number of characters to take from the name, 0 = all | 0 |
creator | author / editor / translator / collaborator / * | kind of creator to select, | "*" |
initials | boolean | add author initials | false |
sep | string | use this character between authors | "." |
The beginning of each author's last name, using no more than n
characters (0 = all).
authorIni
parameter | type | description | default |
---|---|---|---|
creator | author / editor / translator / collaborator / * | kind of creator to select, | "*" |
initials | boolean | add author initials | false |
sep | string | 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
parameter | type | description | default |
---|---|---|---|
creator | author / editor / translator / collaborator / * | kind of creator to select, | "*" |
initials | boolean | add author initials | false |
The last name of the last author
authorLastForeIni
parameter | type | description | default |
---|---|---|---|
creator | author / editor / translator / collaborator / * | kind of creator to select, | "*" |
The given-name initial of the last author.
authors
parameter | type | description | default |
---|---|---|---|
n | number / [number, number] | select the first | 0 |
creator | author / editor / translator / collaborator / * | select type of creator ( | "*" |
name | a creator sprintf template with one or more of the variables f (family name) / g (given name) / i (first initial) / I (all initials) | sprintf-js template. Available named parameters are: | "%(f)s" |
etal | string | use this term to replace authors after | "" |
sep | string | use this character between authors | " " |
min | number | skip to the next pattern if there are less than | 0 |
max | number | skip to the next pattern if there are more than | 0 |
Author/editor information.
authorsAlpha
parameter | type | description | default |
---|---|---|---|
creator | author / editor / translator / collaborator / * | kind of creator to select, | "*" |
initials | boolean | add author initials | false |
sep | string | 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
parameter | type | description | default |
---|---|---|---|
creator | author / editor / translator / collaborator / * | kind of creator to select, | "*" |
initials | boolean | add author initials | false |
sep | string | 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.
date
parameter | type | description | default |
---|---|---|---|
format | string | sprintf-style format template | "%Y-%m-%d" |
The date of the publication
extra
parameter | type | description | default |
---|---|---|---|
variable | string | 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+
.)
infix
parameter | type | description | default |
---|---|---|---|
format | string | sprintf-style format template | "%(a)s" |
start | number | start value for postfix | 0 |
a pseudo-function that sets the citekey disambiguation infix using an sprintf-js format spec for when a key is generated that already exists. The infix charachter appears at the place of this function of the formula instead of at the and (as postfix does). 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 start set to 1
the disambiguator is always included, even if there is no need for it when no duplicates exist. The default format is %(a)s
.
inspireHep
Fetches the key from inspire-hep based on DOI or arXiv ID
item
parameter | type | default |
---|---|---|
id | id / key | "key" |
returns the internal item ID/key
journal
parameter | type | description | default |
---|---|---|---|
abbrev | abbrev / abbrev+auto / auto / full / 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 full
/off
(no abbrevation).
keyword
parameter | type | default |
---|---|---|
n | number |
Tag number n
. Mostly for legacy compatibility -- order of tags is undefined
language
parameter | type | description | default |
---|---|---|---|
name | ame / american / american english / americanenglish / ar / ar-ar / ar-dz / ar-eg / ar-iq / ar-jo / ar-lb / ar-ma / ar-ps / ar-sa / ar-sy / ar-tn / ara / arabic / arabic-algeria / arabic-dz / arabic-eg / arabic-egypt / arabic-iq / arabic-iraq / arabic-jo / arabic-jordan / arabic-lb / arabic-lebanon / arabic-ma / arabic-morocco / arabic-palestinianterritories / arabic-ps / arabic-sa / arabic-saudiarabia / arabic-sy / arabic-syria / arabic-tn / arabic-tunisia / 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 / newzealand / nge / ngerman / nsw / nswissgerman / schweizer hochdeutsch / simplified chinese / swiss high german / swisshighgerman / swisshighgerman-traditional / traditional chinese / tw / ukenglish / usenglish / zh / zh-hans / zh-hans-hk / zh-hans-mo / zh-hans-sg / zh-hant / zh-hant-hk / zh-hant-mo / zh-tw / 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
)
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
parameter | type | description | default |
---|---|---|---|
format | a postfix sprintf template with one or more of the variables a (alpha postfix) / A (alpha postfix uppercase) / n (numeric postfix) | sprintf-style format template | "%(a)s" |
start | number | start value for postfix | 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 start set to 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
parameter | type | description | default |
---|---|---|---|
n | number | number of words to select | 3 |
m | number | number of words to capitalize. | 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
parameter | type | description | default |
---|---|---|---|
allowed | artwork / audioRecording / bill / blogPost / book / bookSection / case / computerProgram / conferencePaper / dataset / dictionaryEntry / document / email / encyclopediaArticle / film / forumPost / hearing / instantMessage / interview / journalArticle / letter / magazineArticle / manuscript / map / newspaperArticle / patent / podcast / preprint / presentation / radioBroadcast / report / standard / statute / thesis / tvBroadcast / videoRecording / webpage / classic / gazette / legalCommentary / regulation / treaty | one or more item type names |
Without arguments, returns the item type. When arguments as passed, tests whether the item is of any of the given types, and skips to the next pattern if not, eg type(book) + veryshorttitle | auth + year
.
veryshorttitle
parameter | type | description | default |
---|---|---|---|
n | number | number of words to select | 1 |
m | number | number of words to capitalize. | 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.
Note: All auth...
functions will fall back to editors if no authors are present on the item.
Note: The functions above used to have the clean
function automatically applied to them, this is no longer the case, so if you have CJK authors/titels and you want to manipulate them (using eg. capitalize
), you could have to use transliterate
on them first, eg. authEtal2.transliterate.capitalize + year + shorttitle(3, 3)
.
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 |
AuthorityZ | 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 | FormatZ | ForumTitle | GazetteFlagJM |
Genre | History | ISBN | ISSN |
IdentifierZ | 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 | OrganizationZ |
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 |
RepositoryLocationZ | ResolutionLabelJM | Rights | RunningTime |
Scale | Section | Series | SeriesNumber |
SeriesText | SeriesTitle | Session | SessionTypeJM |
ShortTitle | SigningDateJM | Status | Studio |
Subject | SupplementNameJM | System | ThesisType |
Title | TreatyNumberJM | Type | University |
Url | VersionNumber | VideoRecordingFormat | Volume |
VolumeTitleJM | WebsiteTitle | WebsiteType | YearAsVolumeJM |
(fields marked Z are only available in Zotero, fields marked with JM are only available in Juris-M).
abbr
parameter | type | default |
---|---|---|
chars | number | 1 |
Abbreviates the text. Only the first character and subsequent characters following white space will be included.
acronym
parameter | type | description | default |
---|---|---|---|
list | string | lookup list. The list must be a CSV file and live in the | "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
parameter | type | description | default |
---|---|---|---|
sep | string | 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
parameter | type | description | default |
---|---|---|---|
text | string | literal text to return |
Returns the given text if no output was generated
discard
discards the input
formatDate
parameter | type | description | default |
---|---|---|---|
format | string | sprintf-style format template | "%Y-%m-%d" |
formats date as by replacing y, m and d in the format
ideographs
Treat ideaographs as individual words
jieba
parameter | type | default |
---|---|---|
mode | cn / hant / tw |
word segmentation for Chinese items. Uses substantial memory, and adds about 7 seconds to BBTs startup time; 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
parameter | type | description | default |
---|---|---|---|
relation | != / < / <= / = / > / >= | comparison operator | ">" |
length | number | 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
parameter | type | description | default |
---|---|---|---|
match | RegExp / string | regex or string to match. String matches are case-insensitive | |
clean | boolean | 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
parameter | type | default |
---|---|---|
dash | string | "-" |
Removes punctuation
nopunctordash
Removes punctuation and word-connecting dashes. alias for nopunct(dash='')
numeric
returns the value if it's an integer
pinyin
transliterates the citation key to pinyin
postfix
parameter | type | description | default |
---|---|---|---|
postfix | string | 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
parameter | type | description | default |
---|---|---|---|
prefix | string | 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
parameter | type | description | default |
---|---|---|---|
find | string / RegExp | string or regex to match. String matches are case-insensitive | |
replace | string | literal text to replace the match with |
replaces text, case insensitive when passing a string; .replace('.etal','&etal')
will replace .EtAl
with &etal
select
parameter | type | description | default |
---|---|---|---|
start | number | first word to select (1-based) | 1 |
n | number | 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
parameter | type | description | default |
---|---|---|---|
nopunct | boolean | remove punctuation from words | false |
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 with nopunct
on if you use title
(which is different from Title
) or shorttitle
.
substring
parameter | type | description | default |
---|---|---|---|
start | number | starting character (1-based) | 1 |
n | number | number of characters to select (default: remainder from |
substring(start,n)
selects n
(default: all) characters starting at start
transliterate
parameter | type | description | default |
---|---|---|---|
mode | ar / arabic / chinese / de / german / ja / japanese / minimal / mn / mongolian / ru / russian / tw / uk / ukranian / zh / zh-hant | 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.