*zotcite.txt* Integration with Zotero 1. Overview |zotcite_overview| 2. Usage |zotcite_usage| 2.1. Commands |zotcite_commands| 2.2. Mappings |zotcite_mappings| 2.3. Compiling documents |zotcite_compiling_docs| 3. Customization |zotcite_customization| 3.1. Paths |zotcite_paths| 3.2. Change default maps |zotcite_change_mappings| 3.3. Zotcite engine |zotcite_engine| 3.4. Syntax highlighting |zotcite_highlighting| 3.5. File types |zotcite_filetypes| 3.6. Open attachment |zotcite_open_in_zotero| 3.7. Show errors of command to open attachment |zotcite_wait_attachment| 4. Troubleshooting |zotcite_troubleshooting| ============================================================================== 1. Overview *zotcite_overview* Zotcite is a Vim plugin that provides integration with Zotero. Please, see a description of its features, including screenshots at: https://github.com/jalvesaq/zotcite ============================================================================== 2. Usage *zotcite_usage* ------------------------------------------------------------------------------ 2.1. Commands *zotcite_commands* You can use the command `:Zseek` to see what references have either a last author's name or title matching the pattern that you are seeking for. Example: >vim :Zseek marx Only the first word is used as the search pattern. Thus, the following command would give the same result as the above one: >vim :Zseek marx anything The Telescope picker is filled with references that include the searched pattern as a substring in the author's names or the work's title, but Telescope allows you to further fuzzy filter the results. If you want the Telescope picker filled with Zotero's entire database, run `:Zeek` without arguments. The same Telescope dialogue is also used by `:Zannotations`, `:Zselectannotations`, `:Znote`, and `:Zpdfnote` (see below). Zotcite can extract and insert into the markdown document (1) annotations that you have made using Zotero's built-in PDF viewer, (2) notes that you have attached to a Zotero entry, and (3) annotations inserted in a PDF by an external PDF viewer. To extract annotations made with Zotero's built-in PDF viewer, use the Vim command `:Zannotations key`. If the PDF has page labels, Zotero will register them as the page numbers; otherwise, Zotero will consider the first page of the PDF as page 1 which in most cases will be wrong. You can fix this by passing an integer number as a second argument to `:Zannotations`. For example, if page 1 of a book is page 11 of its PDF, you will get the correct page numbers if you do: >vim :Zannotations key -10 By default, the colon separating the year from the page is replaced by ", p. ". If you want to use the colon or any other string as the separator, set the value of `year_page_sep` in your `config`. Example: >lua year_page_sep = ':' If you want to extract annotations made with Zotero's built-in PDF viewer but would prefer to make a selection of the annotations to be imported then use the vim command `:Zselectannotations key`. After choosing the reference, a second dialogue will appear with the annotations and notes (if you have made notes). You can scroll through the annotations list and press `enter` on the annotations you'd wish to import. Once finished making the selection you need to press `Esc` to escape the annotation selection dialogue. >vim To extract notes from Zotero, use the Vim command `:Znote key` Similarly, to extract annotations (notes and highlighted texts) that were inserted into a PDF document by an external PDF viewer, use the Vim command `:Zpdfnote`. The page numbers of the annotations might be wrong, so always check them after the extraction. You have also to manually add italics and other rich text formatting and put back hyphens incorrectly removed from the end of the PDF lines. To insert citation keys, you can press in Insert mode. The sequence of letters before the cursor will be used to filter the references (see `:Zseek` above). ------------------------------------------------------------------------------ 2.2. Mappings *zotcite_mappings* In Insert mode, type the `@` letter and one or more letters of either the last name of the first author or the reference title. The matching of citation keys is case-insensitive. In Vim's Insert mode, inserts citation keys (requires Telescope). In Vim's Normal mode, put the cursor over a citation key and press: - zo to open the reference's attachment as registered in Zotero's database. - zi to see in the status bar the last name of all authors, the year, and the title of the reference. - za to see all fields of a reference as stored by Zotcite. - zb to insert the abstract (if available) into the current buffer. - zv to view the (pdf or html) document generated from the current (Markdown, Rmd, or Quarto) document. ------------------------------------------------------------------------------ 2.3. Compiling documents *zotcite_compiling_docs* Note: Make backup of your bib files because they will be overwritten by zotcite. zotcite will automatically save the bib file indicated in the YAML header when saving the document. The citation key will have the format `@ABCDEFGH`, and the `Author-Year` complement will be inserted as a virtual text. If you have an old markdown document with citations including the no longer used `-Author-Year` real text, the Vim command below will delete the `-Author-Year` complements (with no automatic way of getting them back): >vim :%s/@\([A-Z0-9]\{8}\)[-#][-:+_[:digit:][:lower:][:upper:]\u00FF-\uFFFF]\+/@\1/g < Note: make a backup of you Markdown document before running the command to be able to revert the changes if anything goes wrong. Convert from ODT ~ If you have an OpenDocument Text with citations inserted by the Zotero extension and want to convert it to Markdown, you can use the `odt2md.py` application from the `scripts` directory to help you convert the document. Example: >sh /path/to/zotcite/scripts/odt2md.py Document.odt Within Neovim, you can run the command `:Zodt2md` to convert the ODT document and see the resulting Markdown document in a new tab: >vim :Zodt2md Document.odt Note that the conversion is not perfect because the visible text from the citation fields is not deleted. You have to delete them manually, keeping what is needed, such as the page numbers that you have added manually. It is not possible to automate this step because LibreOffice allows the manual edition of the citation fields. ============================================================================== 3. Customization *zotcite_customization* ------------------------------------------------------------------------------ 3.1. Paths |zotcite_paths| *zotero_sqlite_path* If Zotcite cannot find the path to Zotero's database (`zotero.sqlite`), put the correct path in your `config`. Example: >lua zotero_sqlite_path = '~/.zotero/zotero.sqlite' < *tmpdir* If Zotcite is trying to use a non-writable directory as its temporary and cache directory, set the value of `tmpdir`. Example: >lua tmpdir = '/dev/shm/zotcite-user_name' Zotcite adds its `scripts` directory to the environment variable `PATH`. If it's not correctly finding the directory, you can set it manually: >lua python_scripts_path = "/path/to/zotcite/scripts" < *zotcite_python_path* Zotcite runs "python3" when extracting notes from PDF documents annotated by PDF viewers other than Zotero (`:Zpdfnote`) and when converting ODT to Markdown (`:Zodt2md`). If "python3" is not in your path or if you are running Python from a virtual environment, you should set the correct path in your zotcite config. Example: >lua python_path = "/home/user_name/.py3env/bin/python3" < ------------------------------------------------------------------------------ 3.2. Change default maps *zotcite_change_mappings* Below are examples of how to change the available key bindings: >lua -- Insert citation key: vim.keymap.set("i", "", "ZCite") -- Open reference attachment: vim.keymap.set("n", "", "ZOpenAttachment") -- See basic information on the reference of a citation key: vim.keymap.set("n", "I", "ZCitationInfo") -- See how the reference of a citation key is stored by Zotcite: vim.keymap.set("n", "C", "ZCitationCompleteInfo") -- Extract the abstract into the current buffer from the citation under cursor: vim.keymap.set("n", "A", "ZExtractAbstract") -- View the (pdf or html) document generated from the -- current (Markdown, Rmd, or Quarto) document: vim.keymap.set("n", "V", "ZViewDocument") < ------------------------------------------------------------------------------ 3.3. Zotcite engine *zotcite_engine* *zotcite_key_type* You can use three different types of citation keys with Zotcite: - Zotero keys. - Keys based on the citation template. - Better BibTeX citation keys. Zotero keys are sequences of random upper case letters and numbers with length eight, such as `A1B2C3D4` or `ABCD1234`. These keys are generated by Zotero. Keys based on the citation template are generated by zotcite according to the `citation_template` option explained below. Duplicates are fixed by appending alphabetic letters `a`, `b`, `c`, and so on. The letter that is appended follows the chronological order of addition of references to Zotero's database. This type of citation key is similar to what you get from Better BibTex. The Better BibTeX citation keys are generated by Zotero's extension Better BibTex. Advantages of each type: - Zotero key: It is guaranteed to be unique. You will never get a duplicate. But they are meaningless for humans because it is not based on an author name, reference title, or year of publication. As a workaround, zotcite conceals the Zotero key and inserts a virtual text based on the citation template. The problem is that the cursor movement becomes strange as it jumps over the virtual text. - Key based on the citation template: You see the real text of the citation key, and you see the cursor moving as usual. The problem is that if you delete from Zotero's database a reference that was resulting in duplicate citation key, the letters appended to the remaining references will change unless the deleted reference was the last one added. - Better BibTeX citation key: Same advantages and disadvantages of citation keys based on a template. What is the best for you: - If you are writing a book or paper alone (or if everyone is using Neovim and zotcite) and the strange cursor movements isn't annoying to you, then, the Zotero key is the best option. - If you are writing alone (or if everyone is using Neovim and zotcite), but you want normal cursor movements, and don't want to install Better BibTex, then, a citation key based on the citation template is the best option. - If you are writing with other people who use Better BibTeX, than, of course, you have no choice but to use Better BibTeX keys too. The type of citation key is defined with the option `key_type`. Valid values are "template" (the default), "better-bibtex", and "zotero". Example: >lua key_type = "zotero", < You can also set a different value for each document. For a Markdown, RMarkdown or Quarto document, add the key `zotcite-key-type` to the YAML header. Example: >yaml zotcite-key-type: better-bibtex < For LaTeX, Rnoweb, or Tpyst, it should be within a commented line with the comment string at the beginning of the line. Example for LaTeX: >tex % zotcite-key-type = zotero < and for Typst: >typst // zotcite-key-type = template < *citation_template* When the `key_type` is "zotero", zotcite complements the citation key with a virtual text in the format `Author_Year`. The citation key is the key attributed by Zotero to the references stored in its database, `Author` is the last name of the first author, and `Year` is the full year (four digits). You can define whether it will include or not the first author's last name (in either lower case `{author}` or title case `{Author}`), the last names of the first three authors (either `{authors}` or `{Authors}`), and the year (with either four digits `{Year}` or only two `{year}`). Example: >lua citation_template = '{Author}-{year}' < When Zotero's SQLite3 database is updated, zotcite copies it to its temporary directory. While copying, the slowest operation is writing the copy of the file to disk. If you have enough RAM, you may want to set `tmpdir` as a directory in a file system mounted in virtual memory, as in the second example above. *exclude_fields* If you want to exclude some of Zotero's fields from the bib file generated by Zotcite, set the value of `exclude_fields` to a white-separated list of fields to be excluded. For example, if you want to exclude the fields "Extra" (which appears as `note` in the bib file) and "file" field, put this in your `config`: >lua exclude_fields = "note file" < *sort_key* By default, zotcite uses the field "dateModified" to sort the results displayed by `:Zseek`. You can use a different field, such as "date", "title", "alastnm" or other fields whose values are strings or numbers (do `za` over some citation keys to see the available fields): >lua sort_key = "date" < *Zotero_collection* If you want to restrict the search for references to specific collections while completing citation keys, set the value `collection` in the YAML header of the Markdown document, as in the examples: > --- collection: ['New Paper'] --- --- collection: ['PhD Thesis', 'New Paper'] --- The Python script `pdfnote.py` imports the modules `PyQt5` and `popplerqt5`. On Debian systems they can be installed with the command: >sh sudo apt install python3-pyqt5 python3-poppler-qt5 < In any system, if using `pip`: >sh pip install poppler-qt5 pip install python-poppler-qt5 < If you have trouble install `poppler-qt5` or `python-poppler-qt5` you can add to your zotcite config: >lua pdf_extractor = "pdfnotes2.py", < The Python script `pdfnotes2.py` requires the `pymupdf` module, which can be installed on Debian: >sh sudo apt install python3-pymupdf < or with `pip`: >sh pip install pymupdf < ------------------------------------------------------------------------------ 3.4. Syntax Highlighting *zotcite_highlighting* Syntax highlighting customization is done with Vim variables. *hl_cite_key* If you want to disable Zotcite's syntax highlighting of citation keys, put in your `config`: >lua hl_cite_key = false < *zotcite_conceallevel* Zotcite will set the 'conceallevel' of the document if you set the value `conceallevel` in its config: >lua conceallevel = 0 if `conceallevel` is a negative integer (the default), zotcite will do nothing. ------------------------------------------------------------------------------ 3.5. File types *zotcite_filetypes* Zotcite is a filetype plugin and is enabled only if the file type is `markdown`, `pandoc`, `rmd`, `quarto`, `vimwiki`, `latex` or `rnoweb`. If you want to disable it for some of these file types, you should set the value of `filetypes` in your `config`. Example: >lua filetypes = { 'markdown', 'pandoc', 'rmd', 'vimwiki' } ------------------------------------------------------------------------------ 3.6. Open attachment *zotcite_open_in_zotero* Zotcite calls `vim.ui.open()` to open attachments. But you can change the command in your config: >lua open_cmd = "my_open_script" If you want ZOpenAttachment to open PDF attachments in Zotero (as opposed to your system's default PDF viewer), put the following in your `config`: >lua open_in_zotero = true Note that you'll need to have Zotero configured as the default app for opening `zotero://` links. On Linux, assuming your Zotero installation included a `zotero.desktop` file, you can do the following: >sh xdg-mime default zotero.desktop x-scheme-handler/zotero ------------------------------------------------------------------------------ 3.7. Show errors of command to open attachment *zotcite_wait_attachment* While opening an attachment, zotcite cannot catch errors because it doesn't wait for the application to finish. If zotcite fails to open a PDF attachment, you may want to temporarily set `wait_attachment` as `true` in your `config`: >lua wait_attachment = true Then, Neovim should freeze until the attachment is closed, and, if the PDF viewer finishes with non-zero status, anything output to the `stderr` will be displayed as a warning message. ============================================================================== 4. Troubleshooting *zotcite_troubleshooting* *:Zinfo* If either the plugin does not work or you want easy access to the values of some internal variables, do the following command: >vim :Zinfo Note that, unless you are editing Quarto documents, Zotcite will not enable omni completion if any of the buffer's lines matches the regular pattern `^bibliography:.*\.bib` when the markdown file is read. vim:tw=78:ts=8:ft=help:norl