*zotcite.txt* *zotcite* zotcite Integration with Zotero Author: Jakson A. Aquino 1. Overview |zotcite_overview| 2. Usage |zotcite_usage| 3. Suggested workflow |zotcite_workflow| 4. Customization 4.1 Change default maps |zotcite_mappings| 4.2 Zotcite engine |zotcite_engine| Citation template |ZCitationTemplate| Ban words from citation template |ZBannedWords| Path to Zotero database |ZoteroSQLpath| Temporary directory path |Zotcite_tmpdir| Fields to exclude from references |Zotcite_exclude| Zotero collection to use |Zotero_collection| 4.3 Syntax highlighting |zotcite_highlighting| Syntax highlighting of citation keys |zotcite_hl| Conceal level |zotcite_conceallevel| 4.4 File types |zotcite_filetypes| 4.5 Open attachment in Zotero |zotcite_open_in_zotero| 4.6 Show errors of command to open attachment |zotcite_wait_attachment| 4.7 Quarto render options |zotcite_quarto_render| 5. 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* 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` where `key` is a word with one or more letters of authors' names or from a reference title. 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: > :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 `$ZYearPageSep` in your vimrc (or init.vim). Example: > let $ZYearPageSep = ':' < 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, in Insert mode, type the `@` letter and one or more letters of either the last name of the first author or the reference title and press

. The matching of citation keys is case-insensitive. (See also https://github.com/jalvesaq/cmp-zotcite). To convert a Markdown document with pandoc, use the `zotref.py` filter that comes with Zotcite. The Zotcite plugin adds the directory where `zotref.py` is to the system `$PATH`. So, from within Vim/Neovim, do: > :!pandoc file_name.md -s -o file_name.html -F zotref.py --citeproc < Replace `file_name` with the actual name of the markdown document being edited, and `html` with the appropriate file extension. To compile an RMarkdown document with the Nvim-R plugin (https://github.com/jalvesaq/Nvim-R), add the following lines to the YAML header of the document (replace `pdf_document` with the desired output): > output: pdf_document: pandoc_args: ['-F', 'zotref.py', '--citeproc'] < Note: On Windows, you might have to replace `zotref.py` with its full path. Example: > output: pdf_document: pandoc_args: ['-F', '/Path/to/zotcite/python3/zotref.py', '--citeproc'] < Note: Old versions of `pandoc` require `-F pandoc-citeproc` instead of `--citeproc`. Note: On Windows, `zotref.py` will convert the bib file from "latin1" to "utf-8". If "latin1" is not the Zotero encoding in your region, set the environment variable `$Zotero_encoding` with the correct value in your |vimrc|. Example: > let $Zotero_encoding = 'latin2' < 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. - zy to see how the reference will be converted into YAML. - zv to view the (pdf or html) document generated from the current (Markdown, Rmd, or Quarto) document. You can also 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. The references displayed in the command line at the bottom of the screen will be the same that would be in an omni completion menu. Example: > :Zseek marx < The goal of Zotcite is to avoid the need for exporting bib files from Zotero. The `zotref.py` filter receives the Markdown document from its standard input, extracts all citation keys from the document, gets all corresponding references from the Zotero database, inserts all references in the YAML header of the document, and, finally, returns the enhanced document to `pandoc`. If there is a "bibliography" field in the YAML header, it will be used. If one of the bib files listed in the "bibliography" field has a name ending with the "zotcite.bib" string it will be overwritten. If there is a "bibliography" field in the YAML header, but none of the bib files listed ends in "zotcite.bib", a temporary one will be created. It is possible --- but not recommended --- to mix bib files that are generated and overwritten by zotcite with other ones because the final document may include duplicated references. Anyway, if you have an old bib file and want to complement it with Zotero references, you can put in your YAML header: > bibliography: - old.bib - new-zotcite.bib < or, simply: > bibliography: old.bib < 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 `python3` directory to help you convert the document. Example: > /path/to/zotcite/python3/odt2md.py Document.odt < Within Vim/Neovim, you can run the command `:Zodt2md` to convert the ODT document and see the resulting Markdown document in a new tab: > :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 automatize this step because LibreOffice allows the manual edition of the citation fields. ============================================================================== 3. Suggested workflow *zotcite_workflow* 1. Use Zotero's browser connector to download papers in PDF format. 2. Read the papers, highlighting important passages, and making annotations. 3. Run the command `:Zpdfnote` to extract your notes from the PDF document and insert them into the markdown document. 5. Finish editing your markdown document. ============================================================================== 4. Customization ------------------------------------------------------------------------------ 4.1 Change default maps *zotcite_mappings* To change the shortcut to open reference attachment, set the value of ZOpenAttachment in your vimrc as below: > nmap ZOpenAttachment < To change the shortcut to see basic information on the reference of a citation key, follow the example: > nmap ,I ZCitationInfo < To change the shortcut to see how the reference of a citation key is stored by Zotcite, follow the example: > nmap ,A ZCitationCompleteInfo < To change the shortcut to see how the reference is converted into YAML, follow the example: > nmap ,Y ZCitationYamlRef < To change the shortcut to view the (pdf or html) document generated from the current (Markdown, Rmd, or Quarto) document, follow the example: > nmap ,V ZViewDocument < ------------------------------------------------------------------------------ 4.2 Zotcite engine *zotcite_engine* You can change most of Zotcite's behavior by setting some environment variables in your `vimrc`/`init.vim` (or in your `~/.bashrc`, if you use bash as your shell). *ZCitationTemplate* The citation keys inserted by Zotcite have the format `@ZoteroKey#Author_Year` where `ZoteroKey` 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). The `@ZoteroKey#` part of the citation key is mandatory because `zotref.py` uses it to add the bibliographic data that is parsed by `citeproc`, but it will be concealed by Vim. The remaining of the key is customizable. 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 name of the first three authors (either `{authors}` or `{Authors}`), the first word of the title (`{title}` or `{Title}`) and the year (with either four digits `{Year}` or only two `{year}`). Examples: > let $ZCitationTemplate = '{author}{year}' let $ZCitationTemplate = '{Authors}_{Year}_{Title}' < *ZBannedWords* The following words are deleted from the title before its first word is selected: a, an, the, some, from, on, in, to, of, do, and with. If you want to ban a different set of words, define `$ZBannedWords` in your vimrc as in the examples: > " Spanish let $ZBannedWords = 'el la las lo los uno una unos unas al de en no con para' " French let $ZBannedWords = 'la les l un une quelques à un de avec pour' " Portuguese let $ZBannedWords = 'o um uma uns umas à ao de da dos em na no com para' " Italian let $ZBannedWords = 'la le l gli un una alcuni alcune all alla da dei nell con per' " German let $ZBannedWords = 'der die das ein eine einer eines einem einen einige im zu mit für von' < *ZoteroSQLpath* If Zotcite cannot find the path to Zotero's database (`zotero.sqlite`), put the correct path in your vimrc: > let $ZoteroSQLpath = '/path/to/zotero.sqlite' < *Zotcite_tmpdir* If Zotcite is trying to use a non-writable directory as its temporary and cache directory, or if for any reason you want to change this directory, follow the examples: > let $Zotcite_tmpdir = '/path/to/temporary_and_cache_directory' let $Zotcite_tmpdir = '/dev/shm/zotcite-user_name' < 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 $Zotcite_tmpdir as a directory in a file system mounted in virtual memory, as in the second example above. *Zotcite_exclude* If you want to exclude some of Zotero's fields from the YAML references generated by Zotcite, set the value of `$Zotcite_exclude` 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 YAML references) and "attachment", put this in your vimrc: > let $Zotcite_exclude = "note attachment" < *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'] ... < ------------------------------------------------------------------------------ 4.3 Syntax Highlighting *zotcite_highlighting* Syntax highlighting customization is done with Vim variables. *zotcite_hl* If you want to disable Zotcite's syntax highlighting of citation keys, put in your vimrc: > let zotcite_hl = 0 < *zotcite_conceallevel* Zotcite sets the 'conceallevel' of the Markdown document to 2. If you want a different value, follow the example: > let zotcite_conceallevel = 0 < ------------------------------------------------------------------------------ 4.4 File types *zotcite_filetypes* Zotcite is enabled only if the file type is `markdown`, `pandoc`, `rmd` or `quarto`. If you want it enabled for other file types, you should set the value of `zotcite_filetypes` in your |vimrc|. Example: > let zotcite_filetypes = ['markdown', 'pandoc', 'rmd', 'vimwiki'] < If you want zotcite's highlighting in file types other than `markdown` and `rmd`, you will have to run an autocmd in your |vimrc| to source zotcite's highlighting script. In the example below, `vimwiki` files get zotcite's references properly highlighted (of course, you have to write the correct path to `markdown.vim`: > autocmd FileType vimwiki source /path/to/zotcite/after/syntax/markdown.vim < ------------------------------------------------------------------------------ 4.5 Open attachment in Zotero *zotcite_open_in_zotero* If you want ZOpenAttachment to open PDF attachments in Zotero (as opposed to your system's default PDF viewer), put the following in your |vimrc|: > let zotcite_open_in_zotero = 1 < 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: > xdg-mime default zotero.desktop x-scheme-handler/zotero < ------------------------------------------------------------------------------ 4.6 Show errors of command to open attachment *zotcite_wait_attachment* While opening an attachment using the system's default PDF viewer, zotcite cannot catch errors because it appends an `&` to the command. If zotcite fails to open a PDF attachment, you may want to put the following in your |vimrc|: > let zotcite_wait_attachment = 1 < Then, (Neo)Vim should freeze until the attachment is closed, and, if the default system's PDF viewer finishes with non-zero status, anything output to the `stderr` will be displayed as a warning message. ------------------------------------------------------------------------------ 4.7 Quarto render options *zotcite_quarto_render* If you add the `filters` field to the YAML header of a Quarto document, the filters will be run after the `citeproc` filter. However, the `zotref.py` filter must be run before `citeproc`. The best solution for this problem might be to create a file named `citeproc.lua` with the following contents and save it somewhere: > function Pandoc (doc) return pandoc.utils.citeproc(doc) end < Then, do not use either the `bibliography` field or the `citeproc` field (if you use one of them, `citeproc` will run before `zotref.py`) and put in the header of your Quarto document: > filters: - /full/path/to/zotcite/python3/zotref.py - /full/path/to/your/citeproc.lua - /full/path/to/zotcite/python3/apafix.py < Of course, the last filter should be added only if using the APA citation style. It will replace "&" with "and" in in-text citations. If using the Brazilian citation style, you could try the `abntfix.py` filter to fix in-text citations. If editing Quarto documents, whenever the document is saved, Zotcite can run `quarto render` without any additional arguments if > let zotcite_quarto_render = 1 < or run `quarto render` with whatever arguments you choose (example): > let zotcite_quarto_render = "--quiet" < For a Lua filter to fix the APA citation style, see: https://github.com/citation-style-language/styles/issues/3748 ============================================================================== 5. 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: > :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. *:Zrefs* You can check the YAML references generated by Zotcite with the command `:Zrefs` which will insert in the document the list of references. This is useful if `citeproc` fails to parse the references. If you cannot make the `zotref.py` script work you have to manually add the references to the YAML header of your document with the command `:Zrefs` and delete and add the references again each time that you either cite or remove the citation to a reference. Then, if there are only ASCII characters in the references you will have a chance of successfully compiling the document. vim:tw=78:ts=8:ft=help:norl