Cite as you Write
PSA: as of Zotero 5.0.71, access to the CAYW URL will no longer work from the browser for security reasons; curl and other programmatic access such as from editors access will work.
Good news for TeXnicians and those down with Mark (aka Markdown, RST, whatnot): this is the time to go pester the author of your favorite editor for Zotero integration!
Editor integration
vim
Graciously supplied by David Lukes:
paste it in your .vimrc (and modify to your liking):
function! ZoteroCite()
" pick a format based on the filetype (customize at will)
let format = &filetype =~ '.*tex' ? 'citep' : 'pandoc'
let api_call = 'http://127.0.0.1:23119/better-bibtex/cayw?format='.format.'&brackets=1'
let ref = system('curl -s '.shellescape(api_call))
return ref
endfunction
noremap <leader>z "=ZoteroCite()<CR>p
inoremap <C-z> <C-r>=ZoteroCite()<CR>
This inserts the citation at the cursor using the shortcut ctrl-z (in insert mode) or <leader>z (in normal, visual etc. modes, <leader> being backslash by default).
Alternatively, if you use a recent version of Vim (not Neovim) and have written your config file in vim9script, you may be interested in a vim9script version of the above solution to take advantage of JIT compilation:
def g:ZoteroCite(): string
# Pick a citation format based on the filetype (feel free to customize)
var format: string
if &filetype =~ '.*tex'
format = 'cite'
else
format = 'pandoc'
endif
# Make the BetterBibTeX API call and return the result.
var api_call = 'http://127.0.0.1:23119/better-bibtex/cayw?format=' .. format .. '&brackets=1'
var citation = system('curl -s ' .. shellescape(api_call))
return citation
enddef
inoremap <C-x><C-z> <C-r>=g:ZoteroCite()<cr>
In this case, the keybinding Ctrl-X Ctrl-Z in insert mode inserts a Zotero citation. You can add a normal-mode keybinding in the same way as for the legacy VimScript version provided above.
emacs
@newhallroad wrote a function in elisp, which brings up the CAYW input, adds the chosen items as pandoc citations to the buffer, and moves the point to after the citations. This is for markdown-mode. Emacs users who use org-mode may (or may not) need something different.
(defun alk/bbt-zotero-insert-key ()
"Run shell command to bring up better bibtex cayw input and insert pandoc citation at point"
(interactive)
(shell-command "curl -s http://127.0.0.1:23119/better-bibtex/cayw?format=pandoc^&brackets=true" t nil) ; caret escapes ampersand
(search-forward "]") ; place cursor after inserted citation
)
Zotero Citations for Atom
A sample implementation of real integration (rather than the working-but-clunky workarounds using paste) can be found in the Zotero Citations package for the Atom editor.
VS Code Citation Picker for Zotero
If you don’t feel like typing citations out (and let’s be honest, you don’t), executing VS Code Citation Picker for Zotero extension for the VS Code editor will call up a graphical picker which will insert these for you, formatted and all.
Scrivener 2.0/Marked 2 for Mac
Dave Smith has gracefully written instructions on how to set up Scrivener 2.0 and Marked 2 for OSX to use the CAYW picker, including ready-to-run apps
Scrivener 1.0 for Windows
Emilie has writen instructions for using the CAYW picker for Scrivener 1.0 in Windows 10, with the necessary files
Linux
- Emma Reisz has gracefully written instructions and scripts for setting up CAYW on Linux.
- ConorIA has more versatile solution called zotero4overleaf, which was inspired by Emma’s scripts. This should allow use with Overleaf, which is pretty insane that it’s possible if you think about it.
Overleaf
David Lukes takes Overleaf integration one step further with a GreaseMonkey/TamperMonkey userscript which not only allows popping up the CAYW picker straight from your browser, no other tools required, but adds a hotkey to refresh your bib file on Overleaf. This should work with the free subscription, no fiddling with git or dropbox required.
DIY
BBT exposes an URL at http://127.0.0.1:23119/better-bibtex/cayw . The url accepts
the following URL parameters:
| parameter |
|
probe |
If set to any non-empty value, returns ready. You can use this to test whether BBT CAYW picking is live; it will not pop up the picker |
format |
Set the output format |
clipboard |
Any non-empty value will copy the results to the clipboard |
minimize |
Any non-empty value will minimize Zotero windows after a pick |
texstudio |
Any non-empty value will try to push the pick to TeXstudio |
selected |
Any non-empty value will use the current selection in Zotero rather than popping up the pick window |
select |
More of a gimmick than anything else, but if you add select=true, BBT will select the picked items in Zotero. |
The following formats are available:
natbib. Generates natbib citation commands. Extra URL parameters allowed:
command: the citation command to use (if unspecified, defaults to cite)
latex and cite are aliases for natbib with the assumption you want the cite command to be citecitep and citet are aliases for natbib with the assumption you want the cite command to be citep or citet, respectively.biblatex. Generates biblatex citation commands. Extra URL parameters allowed:
command: the citation command to use (if unspecified, defaults to autocite)
mmd: MultiMarkdownpandoc. Accepts additional URL parameter brackets; any non-empty value surrounds the citation with bracketsasciidoctor-bibtextypst Generates typst citation commandsjupyterscannable-cite for the ODF scannerformatted-citation: output formatted citation as per the current Zotero quick-export setting, if it is set to a citation style, and not an export formatformatted-bibliography: output formatted bibliography as per the current Zotero quick-export setting, if it is set to a citation style, and not an export formattranslate invokes a Zotero export translator. Extra URL parameters allowed:
translator: stripped name of one of the BBT translators (lowercased, remove ‘better’, and only the letters, e.g. biblatex or csljson), or a translator ID. Defaults to biblatex.exportNotes: set to true to export notesuseJournalAbbreviation: set to true to use journal abbreviations
json: the full pick information Zotero provides.eta: formats the pick using Eta, with the picks exposed as it.items. To see what the items look like, use the json formatter. URL parameter required:
template: the Eta template to render
The eta formatter is great for experimentation, but if you need a format for a common target application, feel free to request a change to have that added to this list.
The picker passes the following data along with your picked items if you filled them out:
| field |
|
locator |
the place within the work (e.g. page number) |
prefix |
for stuff like “see …” |
suffix |
for stuff after the citations |
suppress author |
if you only want the year |
However not all output formats support these. Pandoc and scannable cite are the richest ones, supporting all 4. MultiMarkdown supports
none. The formatted- formats will ignore these. LaTeX supports all 4, in a way:
- in the
latex (natbib) format: if you choose suppress author for none or all of your items in a pick, you
will get the citation as you would normally enter it, such as \cite{author1,author2}, or
\citeyear{author1,author2}. If you use locator, prefix, suffix in any one of them, or you use suppress author
for some but not for others, the picker will write them out all separate, like \cite[p. 1]{author1}\citeyear{author2},
as natbib doesn’t seem to have a good mechanism for combined citations that mix different prefixes/suffixes/locators.
- in the
biblatex format: suppress author is ignored unless the command is one of \cite, \autocite
or \parencite and there is one items only, in which case the starred variant of the command is returned, which
hides the author; for multiple items with locators, prefixes or suffixes, the s-affixed variant of the
command is generated
Some of the formatters use abbreviated labels for the results if you include a locator. The defaults are:
| locator label |
abbreviation |
| article |
art. |
| chapter |
ch. |
| subchapter |
subch. |
| column |
col. |
| figure |
fig. |
| line |
l. |
| note |
n. |
| issue |
no. |
| opus |
op. |
| page |
p. |
| paragraph |
para. |
| subparagraph |
subpara. |
| part |
pt. |
| rule |
r. |
| section |
sec. |
| subsection |
subsec. |
| Section |
Sec. |
| sub verbo |
sv. |
| schedule |
sch. |
| title |
tit. |
| verse |
vrs. |
| volume |
vol. |
In your call to the CAYW URL, you can override the abbreviations by adding them to the query, e.g. http://127.0.0.1:23119/better-bibtex/cayw?format=mmd&page=&Section=sec., page-picks will have no label, and Section-picks will get sec. rather than Sec..
The clipboard option can be used as a workaround for editors that haven’t gotten around to integrating this yet. If
you use this option you will probably want to bind to a hotkey, either system-wide (which is going to be platform-dependent, I know
AutoHotKey works for windows, for OSX Karabiner ought to
do the job, and for Linux xbindkeys could do the job.
For example, if you call up http://127.0.0.1:23119/better-bibtex/cayw?format=mmd&clipboard=yes, the Zotero citation picker will pop up. If you then select two items that happen to have cite keys adams2001 and brigge2002, then
- the response body will be
[#adams2001][][#brigge2002][], and
[#adams2001][][#brigge2002][] will be left on the clipboard
Functions
auth(n: number = 0, m: number = 1, creator: ('author' | 'editor' | 'translator' | 'collaborator' | '*') = '*', initials: boolean = false)
The first n (default: all) characters of the mth (default: first) author's last name.
| parameter | type | |
|---|
n | number | the number of characters to take from the name, 0 = all |
m | number | select the mth author |
creator | ('author' | 'editor' | 'translator' | 'collaborator' | '*') | kind of creator to select, * selects author first, and if not present, editor, translator or collaborator, in that order. |
initials | boolean | add author initials |
authAuthEa(creator: ('author' | 'editor' | 'translator' | 'collaborator' | '*') = '*', initials: boolean = false, sep: string = '.')
The last name of the first two authors, and ".ea" if there are more than two.
| parameter | type | |
|---|
creator | ('author' | 'editor' | 'translator' | 'collaborator' | '*') | kind of creator to select, * selects author first, and if not present, editor, translator or collaborator, in that order. |
initials | boolean | add author initials |
sep | string | use this character between authors |
authEtAl(creator: ('author' | 'editor' | 'translator' | 'collaborator' | '*') = '*', initials: boolean = false, sep: string = ' ')
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.
| parameter | type | |
|---|
creator | ('author' | 'editor' | 'translator' | 'collaborator' | '*') | kind of creator to select, * selects author first, and if not present, editor, translator or collaborator, in that order. |
initials | boolean | add author initials |
sep | string | use this character between authors |
authEtal2(creator: ('author' | 'editor' | 'translator' | 'collaborator' | '*') = '*', initials: boolean = false, sep: string = '.')
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.
| parameter | type | |
|---|
creator | ('author' | 'editor' | 'translator' | 'collaborator' | '*') | kind of creator to select, * selects author first, and if not present, editor, translator or collaborator, in that order. |
initials | boolean | add author initials |
sep | string | use this character between authors |
authForeIni(creator: ('author' | 'editor' | 'translator' | 'collaborator' | '*') = '*')
The given-name initial of the first author.
| parameter | type | |
|---|
creator | ('author' | 'editor' | 'translator' | 'collaborator' | '*') | kind of creator to select, * selects author first, and if not present, editor, translator or collaborator, in that order. |
authIni(n: number = 0, creator: ('author' | 'editor' | 'translator' | 'collaborator' | '*') = '*', initials: boolean = false, sep: string = '.')
The beginning of each author's last name, using no more than n characters (0 = all).
| parameter | type | |
|---|
n | number | the number of characters to take from the name, 0 = all |
creator | ('author' | 'editor' | 'translator' | 'collaborator' | '*') | kind of creator to select, * selects author first, and if not present, editor, translator or collaborator, in that order. |
initials | boolean | add author initials |
sep | string | use this character between authors |
authorIni(creator: ('author' | 'editor' | 'translator' | 'collaborator' | '*') = '*', initials: boolean = false, sep: string = '.')
The first 5 characters of the first author's last name, and the last name initials of the remaining authors.
| parameter | type | |
|---|
creator | ('author' | 'editor' | 'translator' | 'collaborator' | '*') | kind of creator to select, * selects author first, and if not present, editor, translator or collaborator, in that order. |
initials | boolean | add author initials |
sep | string | use this character between authors |
authorLast(creator: ('author' | 'editor' | 'translator' | 'collaborator' | '*') = '*', initials: boolean = false)
The last name of the last author
| parameter | type | |
|---|
creator | ('author' | 'editor' | 'translator' | 'collaborator' | '*') | kind of creator to select, * selects author first, and if not present, editor, translator or collaborator, in that order. |
initials | boolean | add author initials |
authorLastForeIni(creator: ('author' | 'editor' | 'translator' | 'collaborator' | '*') = '*')
The given-name initial of the last author.
| parameter | type | |
|---|
creator | ('author' | 'editor' | 'translator' | 'collaborator' | '*') | kind of creator to select, * selects author first, and if not present, editor, translator or collaborator, in that order. |
authorsAlpha(creator: ('author' | 'editor' | 'translator' | 'collaborator' | '*') = '*', initials: boolean = false, sep: string = ' ')
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.
| parameter | type | |
|---|
creator | ('author' | 'editor' | 'translator' | 'collaborator' | '*') | kind of creator to select, * selects author first, and if not present, editor, translator or collaborator, in that order. |
initials | boolean | add author initials |
sep | string | use this character between authors |
authorsn(n: number = 0, creator: ('author' | 'editor' | 'translator' | 'collaborator' | '*') = '*', initials: boolean = false, sep: string = ' ')
The last names of the first n (default: all) authors.
| parameter | type | |
|---|
n | number | the number of characters to take from the name, 0 = all |
creator | ('author' | 'editor' | 'translator' | 'collaborator' | '*') | kind of creator to select, * selects author first, and if not present, editor, translator or collaborator, in that order. |
initials | boolean | add author initials |
sep | string | use this character between authors |
authshort(creator: ('author' | 'editor' | 'translator' | 'collaborator' | '*') = '*', initials: boolean = false, sep: string = '.')
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.
| parameter | type | |
|---|
creator | ('author' | 'editor' | 'translator' | 'collaborator' | '*') | kind of creator to select, * selects author first, and if not present, editor, translator or collaborator, in that order. |
initials | boolean | add author initials |
sep | string | use this character between authors |
creatornames(template?: `sprintf-style format template`, transliterate?: boolean)
Sets the sprintf-template default for representing creator names. Default is '%(f)s'.
in the creator template, you can use:
%(f)s: family ("last") name%(f_zh)s: family ("last") name extracted from chinese compound names. Need jieba to be enabled%(g)s: given ("first") name%(g_zh)s: given ("first") name extracted from chinese compound names. Need jieba to be enabled%(i)s: given-name initials%(I)s: given-name initials, upper-case
| parameter | type | |
|---|
template | sprintf-style format template | template string |
transliterate | boolean | transliterate the returned name |
creators(n: (number | [ number, number ]) = 0, type: ('*' | Creator | Creator[] | (Creator | '*')[][]) = [['primary', 'editor', 'translator', '*']], name: ('' | `sprintf-style format template`) = '', etal: string = '', sep: string = ' ', min: number = 0, max: number = 0)
Author/editor information.
creator type can be one of artist, attorneyAgent, author, bookAuthor, cartographer, castMember, commenter, composer, contributor, cosponsor, counsel, director, editor, guest, interviewee, interviewer, inventor, performer, podcaster, presenter, producer, programmer, recipient, reviewedAuthor, scriptwriter, seriesEditor, sponsor, translator, wordsBy
in the creator template, you can use:
%(f)s: family ("last") name%(f_zh)s: family ("last") name extracted from chinese compound names. Need jieba to be enabled%(g)s: given ("first") name%(g_zh)s: given ("first") name extracted from chinese compound names. Need jieba to be enabled%(i)s: given-name initials%(I)s: given-name initials, upper-case
| parameter | type | |
|---|
n | (number | [ number, number ]) | select the first n creators (when passing a number) or the authors in this range (inclusive, when passing two values); negative numbers mean "from the end", default = 0 = all |
type | ('' | Creator | Creator[] | (Creator | '')[][]) | select only creators of given type(s). Default: all |
name | ('' | sprintf-style format template) | sprintf-js template. Available named parameters are: f (family name), g (given name), i (initials) |
etal | string | use this term to replace authors after n authors have been named |
sep | string | use this character between authors |
min | number | skip to the next pattern if there are less than min creators, 0 = ignore |
max | number | skip to the next pattern if there are more than max creators, 0 = ignore |
creatortypes(match?: RegExp)
This will return a comma-separated list of creator type information for all creators on the item
in the form <1 or 2><creator-type>, where 1 or 2 denotes a 1-part or 2-part creator, and creator-type is one of {{% citekey-formatters/creatortypes %}}, or primary for
the primary creator-type of the Zotero item under consideration. The list is prefixed by the item type, so might look like audioRecording:2performer,2performer,1composer.
| parameter | type | |
|---|
match | RegExp | Regex to test the creator-type list. When passed, and the creator-type list does not match the regex, jump to the next formule. When it matches, return nothing but stay in the current formule. When no regex is passed, output the creator-type list for the item (mainly useful for debugging). |
date(format: string = '%Y-%m-%d')
The date of the publication
| parameter | type | |
|---|
format | string | sprintf-style format template |
extra(variable: string)
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.
| parameter | type | |
|---|
variable | string | extra-field line identifier |
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+.)
group(name: string)
Tests whether the item is in the given group library
| parameter | type | |
|---|
name | string | group name |
infix(format: `sprintf-style format template` = '%(a)s', start: (string | number) = 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.
in the template, you can use:
%(a)s: lower-case alphabetic disambiguator%(A)s: upper-case alphabetic disambiguator%(n)s: numeric disambiguator
| parameter | type | |
|---|
format | sprintf-style format template | sprintf-style format template |
start | (string | number) | start value for postfix |
inspireHep
Fetches the key from inspire-hep based on DOI or arXiv ID
item(id: ('key' | 'id') = 'key')
returns the internal item ID/key
| parameter | type | |
|---|
id | ('key' | 'id') | 'id': return itemID; 'key': return the item key |
journal(abbrev: ('off' | 'abbrev' | 'auto' | 'abbrev+auto' | 'full') = '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).
| parameter | type | |
|---|
abbrev | ('off' | 'abbrev' | 'auto' | 'abbrev+auto' | 'full') | abbreviation mode |
keyword(n: number)
Tag number n. Mostly for legacy compatibility
| parameter | type | |
|---|
n | number | position of tag to get |
language(...name: string[])
Tests whether the item has the given language set, and skips to the next pattern if not
language can be one of 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, العربية, 中文, 中文-中文, 日本語, 简体中文, 繁體中文
| parameter | type | |
|---|
name | string[] | one or more language codes |
lastpage
The number of the last page of the publication (See the remark on firstpage)
library
Tests whether the item is in the user library
month
the month of the publication
origdate
the original date of the publication
origyear
the original year of the publication
postfix(format: `sprintf-style format template` = '%(a)s', start: (string | number) = 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.
in the template, you can use:
%(a)s: lower-case alphabetic disambiguator%(A)s: upper-case alphabetic disambiguator%(n)s: numeric disambiguator
| parameter | type | |
|---|
format | sprintf-style format template | sprintf-style format template |
start | (string | number) | start value for postfix |
shorttitle(n: number = 3, m: number = 0)
The first n (default: 3) words of the title, apply capitalization to first m (default: 0) of those.
| parameter | type | |
|---|
n | number | number of words to select |
m | number | number of words to capitalize. 0 means no words will be capitalized. Mind that existing capitals are not removed. If you enable capitalization, you also get transliteration; for CJK, capitalization is not meaningful, so if you want capitalization, BBT romanizes first. |
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
transliterate(mode: (('minimal' | 'german' | 'japanese' | 'chinese' | 'arabic' | 'ukranian' | 'mongolian' | 'russian') | 'de' | 'ja' | 'chinese-traditional' | 'zh-hant' | 'zh' | 'tw' | 'ar' | 'uk' | 'mn' | 'ru'))
Set the default transliteration mode. If you don't specify a mode, the mode for an entry is derived from the item language field
| parameter | type | |
|---|
mode | (('minimal' | 'german' | 'japanese' | 'chinese' | 'arabic' | 'ukranian' | 'mongolian' | 'russian') | 'de' | 'ja' | 'chinese-traditional' | 'zh-hant' | 'zh' | 'tw' | 'ar' | 'uk' | 'mn' | 'ru') | specialized translateration modes for german, japanese or chinese. |
type(...allowed: string[])
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.
creator type can be one of annotation, artwork, attachment, audioRecording, bill, blogPost, book, bookSection, case, computerProgram, conferencePaper, dataset, dictionaryEntry, document, email, encyclopediaArticle, film, forumPost, hearing, instantMessage, interview, journalArticle, letter, magazineArticle, manuscript, map, newspaperArticle, note, patent, podcast, preprint, presentation, radioBroadcast, report, standard, statute, thesis, tvBroadcast, videoRecording, webpage
| parameter | type | |
|---|
allowed | string[] | one or more item type names |
veryshorttitle(n: number = 1, m: number = 0)
The first n words of the title, apply capitalization to first m of those
| parameter | type | |
|---|
n | number | number of words to select |
m | number | number of words to capitalize. 0 means no words will be capitalized. Mind that existing capitals are not removed. |
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/titles 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).
Direct access to unprocessed fields (“Field functions”)
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).
Filters
abbr(chars: number = 1)
Abbreviates the text. Only the first character and subsequent characters following white space will be included.
| parameter | type | |
|---|
chars | number | number of characters to return per word |
acronym(list: string = 'acronyms', reload: boolean = false, passthrough: boolean = false)
Does an acronym lookup for the text.
| parameter | type | |
|---|
list | string | 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. |
reload | boolean | reload the list for every call. When off, the list will only be read at startup of Better BibTeX. You can set this to true temporarily to live-reload a list. |
passthrough | boolean | if no match is found, pass through input. |
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(sep: string = '')
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).
| parameter | type | |
|---|
sep | string | replacement character |
default(text: string)
Returns the given text if no output was generated
| parameter | type | |
|---|
text | string | literal text to return |
discard
discards the input
find(match: (string | RegExp), passthrough: boolean = false)
Finds a text in the string and returns it.
| parameter | type | |
|---|
match | (string | RegExp) | regex or string to match. String matches are case-insensitive |
passthrough | boolean | if no match is found, pass through input. |
formatDate(format: string = '%Y-%m-%d')
formats date as by replacing y, m and d in the format
| parameter | type | |
|---|
format | string | sprintf-style format template |
ideographs
Treat ideaographs as individual words
jieba(mode?: string)
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
| parameter | type | |
|---|
mode | string | for backwards compatibility, this param will be accepted, but it is a no-op since the switch to jieba-rs. It will be removed eventually. |
kuromoji
word segmentation for Japanese items. Uses substantial memory; must be enabled under Preferences -> Better BibTeX -> Advanced -> Citekeys
len(relation: ('<' | '>' | '<=' | '==' | '!=' | '>=') = '>', length: number = 0)
If the length of the output does not match the given number, skip to the next pattern.
| parameter | type | |
|---|
relation | ('<' | '>' | '<=' | '==' | '!=' | '>=') | comparison operator |
length | number | value to compare length with |
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(match: (string | RegExp), clean: boolean = false)
If the output does not match the given string/regex, skip to the next pattern.
| parameter | type | |
|---|
match | (string | RegExp) | regex or string to match. String matches are case-insensitive |
clean | boolean | transliterates the current output and removes unsafe characters during matching |
nopunct(dash: string = '-')
Removes punctuation
| parameter | type | |
|---|
dash | string | replace dashes with given character |
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(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
| parameter | type | |
|---|
postfix | string | postfix string |
prefix(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.
| parameter | type | |
|---|
prefix | string | prefix string |
replace(find: (string | RegExp), replace: string)
replaces text, for the text to match you can pass either:
- a string:
.replace('.etal','&etal') which will match case-insensitive, so will replace .EtAl with &etal.
- javascript regular expression:
.replace(/[.]etal/ig, '&etal')
| parameter | type | |
|---|
find | (string | RegExp) | string or regex to match. String matches are case-insensitive |
replace | string | literal text to replace the match with |
select(start: number = 1, n?: number)
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.
| parameter | type | |
|---|
start | number | first word to select (1-based) |
n | number | number of words to select. Default is all. |
skipwords(nopunct: boolean = 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.
| parameter | type | |
|---|
nopunct | boolean | remove punctuation from words |
substring(start: number = 1, n?: number)
substring(start,n) selects n (default: all) characters starting at start
| parameter | type | |
|---|
start | number | starting character (1-based) |
n | number | number of characters to select (default: remainder from start) |
transliterate(mode?: (('minimal' | 'german' | 'japanese' | 'chinese' | 'arabic' | 'ukranian' | 'mongolian' | 'russian') | 'de' | 'ja' | 'chinese-traditional' | 'zh-hant' | 'zh' | 'tw' | 'ar' | 'uk' | 'mn' | 'ru'))
transliterates the citation key. If you don't specify a mode, the mode is derived from the item language field
| parameter | type | |
|---|
mode | (('minimal' | 'german' | 'japanese' | 'chinese' | 'arabic' | 'ukranian' | 'mongolian' | 'russian') | 'de' | 'ja' | 'chinese-traditional' | 'zh-hant' | 'zh' | 'tw' | 'ar' | 'uk' | 'mn' | 'ru') | specialized translateration modes for german, japanese or chinese. |
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.