More Zotfile Hacks (Extract Underlines and Change/Remove Title and Color Names)

More Zotfile Hacks

I came up against some of Zotfile configuration limitations in my work and decided to write a guide about how to overcome them. This guide presumes a basic familiarity with zotero, zotfile, and file editing. For the first two, I highly recommend Cat’s excellent guide.

In this guide I show you how to:

  1. Edit the zotfile .xpi.
  2. Modify it to enable extracting comments on underlined text.
  3. Change / Remove Note Title
  4. Modify it to change or remove color category labels on notes extracted with colored highlighting.
  5. Rezip the zotfile .xpi.

1. Editing the .xpi

To install zotfile, normally one would download its .xpi file, and install it through Zotero. But .xpi files are basically renamed zip archives, so, we can modify zotfile by unzipping it and editing the files. Here’s a summary of the steps:

  1. Download the .xpi from github here. (I’m using vr 5.0.16-fx as of this writing)
  2. Change the file extension of the download from .xpi to .zip (e.g. zotfile-5.0.16-fx.xpi →
  3. Extract the the archive (using your preferred extractor).
  4. Edit files in the archive (see below).
  5. Reverse steps 2-3
    1. Re-zip the folders back into an archive (see 4 below)
    2. Rename the new .zip to .xpi.
  6. Install the new .xpi as an addon in Zotero like normal (Tools > Add-ons > Settings Gear (Upper Right) > Install Add-on From File)

Disclaimer: directly editing the zotfile .xpi might break it. I don’t know if this could mess up your Zotero system, but hack at your own risk. If you stick to what I detail below, you can feel secure in knowing it at least works for me.

Also, I wouldn’t bet this is the best way to achieve this. Someone with coding knowledge might figure out how to add a rule in the config editor to achieve the same without editing the xpi?

2. Extract Comments on Underlines

As is, Zotfile extracts the markup of underlined text, so that you can export underlined text, but not any comments attached to those underlines (see Cat’s guide 3.2.1 and 3.2.4). This is a problem for my workflow because I underline headings and then comment section summaries on them when I read texts.

To enable this feature, within the extracted zotfile archive open:


Select the code in lines 81-6:

    if (data.subtype=='Highlight') {
      var content = dict.get('Contents');
      data.content = stringToPDFString(content || '');
      var title = dict.get('T');
      data.title = stringToPDFString(title || '');

Copy the code to the following lines and replace the string “Highlight” with “Underline”:

    if (data.subtype=='Underline') {
      var content = dict.get('Contents');
      data.content = stringToPDFString(content || '');
      var title = dict.get('T');
      data.title = stringToPDFString(title || '');

Save the file. If this is all you want to change, proceed to step 5 above.

3. Change / Remove Note Title

By default, zoftile inserts a bold “Annotated Note” as a title for each extracted annotation. I prefer not to have that title.

These and the following changes are made in the same file. Within the zotfile archive open:


The note title name is set by line 217:

str_title = this.ZFgetString('extraction.noteTitle'),

To change it, replace the argument (this.ZFgetString('extraction.noteTitle')) with a quoted string like so:

str_title = "New Title",

To remove it entirely (my preference), leave the quotes empty:

str_title = "",

Note: If you remove the title entirely and use mdnotes to convert the extracted comments to markdown, the default mdnotes settings will take the first line of your comments as the note title. You can change this by modifying the value of the following preference in the config editor (see Cat’s guide 3.1.1):


To read (insert your title as “TITLE”):

{"content":"# TITLE", "field_contents": "{{content}}", "link_style": "no-links"}

4. Change / Remove Color Labels

By Default, when extensions.zotfile.pdfExtraction.colorNotes is set to true in the config editor, zotfile appends (color_category): to the start of color highlighted extractions. I want to remove this, since it clutters up my notes.

Again, open:


4.1 Change Color Labels

The labels are on lines 199-209. Edit the color name strings to whatever you want:

        // define color category based on HSL    
        if (l < 0.12) return "Black";
        if (l > 0.98) return "White";
        if (s < 0.2) return "Gray";
        if (h < 15) return "Red";
        if (h < 45) return "Orange";
        if (h < 65) return "Yellow";
        if (h < 170) return "Green";
        if (h < 190) return "Cyan";
        if (h < 270) return "Blue";
        if (h < 335) return "Magenta";
        return "Red";

Note: see this pull request for zotfile on github for a more nuanced way of messing with these settings.

4.2 Remove Color Labels

I wanted to get rid of the color labels altogether. To do so remove everything within the <strong> tags from like 281. I.e. change this:

		    anno.markup = "<span style='background-color:rgba(" + anno.color.join(',') + ",.25)'><strong>(" + color_category + ")</strong> - " + anno.markup + "</span>";

To this:

		    anno.markup = "<span style='background-color:rgba(" + anno.color.join(',') + ",.25)'> - " + anno.markup + "</span>";

Of course, you could also edit this string to, e.g. remove the parentheses, change the text decoration, etc, without getting rid of the color category. That means you could, e.g. change the names of your color categories into tags and remove the bold formatting so that highlighting a specific color automatically tags your note that color.

5. Rezipping the archive.

Note: when re-zipping the archive, you must zip the extracted files and folders directly into an archive. The add-on will not install if you zip a folder containing the extracted files and folders.

So zip the following together (the first two are folders, the second two files):

  • chrome
  • defaults
  • chrome.manifest
  • install.rdf

DO NOT zip the folder containing those files (e.fg zotfile-5.0.16-fx)


I hope this helps you. If anyone sees an error or an easier way of doing this, let me know in the comments!