Usage

Important: You must shut down Zotero before you invoking this script. Nothing goes wrong when you don’t. However, the script uses an SQLite file that the program (pessimistically) locks.

The program has two modes: show configuration (a good first step) and create the web site.

Show Structure

You can see what the program is parsing from your Zotero library:

zotsite print

Website Creation

Run the program (without the angle brackets):

zotsite export -o <sitedir>

After the program runs, sitedir will be where the tool creates/generates the the new site. Note you can also give a --datadir to tell the program where your Zotero library is. This can also be configured in your configuration file.

The website will work as served from either a website or from the local file system. You can pass levels as a URL encoded parameter to produce the number of levels when the page is loaded.

On the left you can click on the tree to select collections or attachments. You have to drill all the way down to the leaf level in the tree to get at your attachements and notes. At the leaf level you can select and unselect a node but all other nodes are note selectable.

By clicking on a non-leaf node it expands or collapses everything and gives the meta data for that collection. Note that this behavior was decided more by the way [Tree View] works more than anything else since it is designed to show the entire tree list at once.

Subcollections

The folder directory structure in Zotero are called collections. You can export and print only collections given a regular expression with the --collection flag.

To export only collections with the Deep and Learning, use the following.

zotsite export --collection '.*Deep\s*Learning.*'

This option is handy if you want to hand off a particular set of collection(s) to a colleague or shared project etc. To include entries at the time level (i.e. find those actual papers by name), see the match_children configuration in the configuration file.

The [Python regular expression] syntax. One gotcha is a .* is needed at the front of a string to match anything.

Database Filtering

The configuration file provides a way to give a database where like clause to filter collections. By default this is set to %% (a double percent is need as the percent sign itself is used to escape).

Configuration File

All command line parameters you provide can also be given in a ini style configuration file, for example:

[default]
data_dir = ${env:home}/Zotero

tells the program where the Zotero data directory is located in the user’s home directory with name .zotero (this defaults to the Zotero default).

You can indicate where the program configuration file is with the ZOTSITERC environment variable or use the --config command line program.

See the test case configuration file for example of all options. A few important options include:

  • data_dir: the directory where the Zotero DB files live

  • match_children: when using –collection, match on items as well

  • file_mapping: one of: item or long

  • id_mapping: one of: none, betterbib

  • sort: whether or not to sort items none or case (non-case might be added later)

  • library_id: the library used to generate the site, which defaults to the Personal

Keeping the Website In Sync With Zotero

Currently there is no way to do this (contributions are welcome). However there is a synchronization script I use to synchronize the output of the website with a remote host.

Platform

This project uses the SQLite Python library and should run on other platforms but assumes a directory structure that’s been tested on OSX.

URL Parameters

The generated website takes the following URL encoded parameters:

  • levels: The number of levels to display in the left navigation tree.

  • id: The document ID used to display and navigate when the page loads.

  • isView: if 1, go directly to the PDF rather than the information page.

Robust File System Access

If one file copy from the Zotero storage fails, the program will dump a stack trace and terminate. However, there might be cases where the database might have out-of-sync entries from the storage files, but you still want to export those entries that are available.

To change this behavior and robustly deal with missing entries, add the following to the configuration file:

[site_creator]
robust_fs = True

This tells the program to continue to try to export even when encountering file system copy issues. However, you’ll get a lot of verbose error output if there is some larger issue.