From 8f9791ff56487561f426716519c195f03f3bd039 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Wed, 7 Aug 2024 20:38:43 +0000
Subject: [PATCH] Deployed d74804a to development with MkDocs 1.6.0 and mike
 2.1.2

---
 development/about/index.html         |  21 +++++++++++----------
 development/config-params/index.html |   2 +-
 development/deploying/index.html     |  12 ++++++------
 development/index.html               |   3 +++
 development/search/search_index.json |   2 +-
 development/sitemap.xml.gz           | Bin 127 -> 127 bytes
 6 files changed, 22 insertions(+), 18 deletions(-)

diff --git a/development/about/index.html b/development/about/index.html
index 0afc442..dbcf0c4 100644
--- a/development/about/index.html
+++ b/development/about/index.html
@@ -649,11 +649,12 @@ <h1 id="about">About<a class="headerlink" href="#about" title="Permanent link">&
 <p>Kerko was inspired by prior work accomplished by <a href="https://whiskyechobravo.com/">Whisky Echo
 Bravo</a> on two projects:</p>
 <ul>
-<li><a href="https://bibliomontreal.uqam.ca/bibliographie/">Bibliographie sur l’histoire de
-  Montréal</a>, developed in 2014 by
-  David Lesieur and Patrick Fournier, of Whisky Echo Bravo, for the <a href="https://lhpm.uqam.ca/">Laboratoire
+<li><a href="https://bibliographies.uqam.ca/bhm/">Bibliographie sur l’histoire de
+  Montréal</a>, developed in 2014 by David
+  Lesieur and Patrick Fournier, of Whisky Echo Bravo, for the <a href="https://lhpm.uqam.ca/">Laboratoire
   d'histoire et de patrimoine de Montréal</a> (Université du
-  Québec à Montréal, Canada).</li>
+  Québec à Montréal, Canada). The original custom application got a few minor
+  updates over time, and was eventually replaced with Kerko in 2024.</li>
 <li><a href="http://quescren.concordia.ca/">Bibliography on English-speaking Quebec</a>,
   developed in 2017 by David Lesieur, for the <a href="https://www.concordia.ca/artsci/scpa/quescren.html">Quebec English-Speaking
   Communities Research Network
@@ -666,12 +667,12 @@ <h1 id="about">About<a class="headerlink" href="#about" title="Permanent link">&
 order to be more adaptable to a variety of needs. That led to Kerko, whose
 initial development was made possible through the following project:</p>
 <ul>
-<li><a href="https://bibliopiaf.ebsi.umontreal.ca/">Bibliographie francophone sur l'archivistique</a>,
-  funded by the
-  <a href="http://www.aiaf.org/">Association internationale des archives francophones (AIAF)</a>
-  and hosted by the
-  <a href="https://ebsi.umontreal.ca/">École de bibliothéconomie et des sciences de l’information (EBSI)</a>
-  (Université de Montréal, Canada).</li>
+<li><a href="https://bibliopiaf.ebsi.umontreal.ca/">Bibliographie francophone sur
+  l'archivistique</a>, funded by the
+  <a href="https://www.piaf-archives.org/AIAF/association-internationale-des-archives-francophones">Association internationale des archives francophones
+  (AIAF)</a>
+  and hosted by the <a href="https://ebsi.umontreal.ca/">École de bibliothéconomie et des sciences de l’information
+  (EBSI)</a> (Université de Montréal, Canada).</li>
 </ul>
 <p>Since then, Kerko has continued to evolve, thanks to work by <a href="https://whiskyechobravo.com/">Whisky Echo
 Bravo</a> and other contributors, often through funding provided
diff --git a/development/config-params/index.html b/development/config-params/index.html
index 6ec2a75..3be9e3c 100644
--- a/development/config-params/index.html
+++ b/development/config-params/index.html
@@ -3877,7 +3877,7 @@ <h3 id="weight_2"><code>weight</code><a class="headerlink" href="#weight_2" titl
 <hr />
 <h2 id="kerkometa"><code>kerko.meta.</code><a class="headerlink" href="#kerkometa" title="Permanent link">&para;</a></h2>
 <h3 id="google_analytics_id"><code>google_analytics_id</code><a class="headerlink" href="#google_analytics_id" title="Permanent link">&para;</a></h3>
-<p>A Google Analytics stream ID, e.g., <code>'G-??????????'</code>.</p>
+<p>A Google Analytics measurement ID, e.g., <code>'G-??????????'</code>.</p>
 <p>If the value is not empty <em>and</em> Flask is not running in debug mode, then the
 Google Analytics tag is inserted into the pages.</p>
 <p>Type: String <br>
diff --git a/development/deploying/index.html b/development/deploying/index.html
index d55da6b..152c623 100644
--- a/development/deploying/index.html
+++ b/development/deploying/index.html
@@ -465,9 +465,9 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
         <li class="md-nav__item">
-  <a href="#deploying-on-ubuntu-2004-or-2204-with-nginx-and-gunicorn" class="md-nav__link">
+  <a href="#deploying-on-ubuntu-with-nginx-and-gunicorn" class="md-nav__link">
     <span class="md-ellipsis">
-      Deploying on Ubuntu 20.04 or 22.04 with nginx and gunicorn
+      Deploying on Ubuntu with nginx and gunicorn
     </span>
   </a>
   
@@ -599,9 +599,9 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
         <li class="md-nav__item">
-  <a href="#deploying-on-ubuntu-2004-or-2204-with-nginx-and-gunicorn" class="md-nav__link">
+  <a href="#deploying-on-ubuntu-with-nginx-and-gunicorn" class="md-nav__link">
     <span class="md-ellipsis">
-      Deploying on Ubuntu 20.04 or 22.04 with nginx and gunicorn
+      Deploying on Ubuntu with nginx and gunicorn
     </span>
   </a>
   
@@ -656,9 +656,9 @@ <h1 id="how-to-deploy">How to deploy<a class="headerlink" href="#how-to-deploy"
 <p>That said, you may refer to the guide below for step-by-step instructions. Even
 if your environment is different from the one this guide was designed for, it
 might provide you with some useful hints.</p>
-<h2 id="deploying-on-ubuntu-2004-or-2204-with-nginx-and-gunicorn">Deploying on Ubuntu 20.04 or 22.04 with nginx and gunicorn<a class="headerlink" href="#deploying-on-ubuntu-2004-or-2204-with-nginx-and-gunicorn" title="Permanent link">&para;</a></h2>
+<h2 id="deploying-on-ubuntu-with-nginx-and-gunicorn">Deploying on Ubuntu with nginx and gunicorn<a class="headerlink" href="#deploying-on-ubuntu-with-nginx-and-gunicorn" title="Permanent link">&para;</a></h2>
 <p>These instructions will detail the steps and configurations required to get
-<a href="https://github.com/whiskyechobravo/kerkoapp">KerkoApp</a> running on an Ubuntu 20.04 or 22.04 web server, using <a href="https://gunicorn.org/">Gunicorn</a> as
+<a href="https://github.com/whiskyechobravo/kerkoapp">KerkoApp</a> running on an Ubuntu 22.04 or 24.04 web server, using <a href="https://gunicorn.org/">Gunicorn</a> as
 the WSGI container and <a href="https://nginx.org/en/docs/">nginx</a> as a HTTP proxy.</p>
 <p>The procedure is similar that of any Flask application, but KerkoApp-specific
 steps are also covered here.</p>
diff --git a/development/index.html b/development/index.html
index 7ba5507..69ef47b 100644
--- a/development/index.html
+++ b/development/index.html
@@ -760,10 +760,13 @@ <h2 id="sites-using-kerko">Sites using Kerko<a class="headerlink" href="#sites-u
 <p>The following sites are powered by Kerko:</p>
 <ul>
 <li><a href="https://bibliopiaf.ebsi.umontreal.ca/">Bibliographie francophone sur l'archivistique</a></li>
+<li><a href="https://bibliographies.uqam.ca/bhm/">Bibliographie sur l'histoire de Montréal</a></li>
 <li><a href="https://ckol.quescren.ca/">Community Knowledge Open Library on English-Speaking Quebec</a></li>
 <li><a href="https://library.lipedema.org/">Lipedema Foundation LEGATO Lipedema Library</a></li>
 <li><a href="https://docs.opendeved.net/">Open Development &amp; Education Evidence Library</a></li>
+<li><a href="https://rightsandrecords.ica.org/">Rights and Records Knowledge Base</a></li>
 <li><a href="http://docs.edtechhub.org/">The EdTech Hub Evidence Library</a></li>
+<li><a href="https://library.transitionaljusticedata.org/">Transitional Justice Evaluation Tools Reference Library</a></li>
 <li><a href="https://research.usj.edu.mo/">University of Saint Joseph Research Output</a></li>
 </ul>
 <div class="admonition question">
diff --git a/development/search/search_index.json b/development/search/search_index.json
index c373f67..f651ea0 100644
--- a/development/search/search_index.json
+++ b/development/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Introduction","text":"<p>Kerko is a web application component that provides a user-friendly search and browsing interface for sharing a bibliography managed with the Zotero reference manager.</p> <p>The combination of Kerko and Zotero gives you the best of both worlds: a rich but easy to use web interface for end-users of the bibliography, and a well-established and powerful bibliographic reference management tool for individuals or teams working on the bibliography's content.</p>"},{"location":"#how-it-works","title":"How it works","text":"<p>A Kerko-powered bibliography is managed using Zotero, and stored in the cloud on zotero.org, while Kerko itself is incorporated into an application which is installed on a web server. The bibliographic references may reside in a Zotero group library, where multiple users may collaborate to manage the content, or in a Zotero private library. On the web server, Kerko maintains a search index, which is a copy of the Zotero library that is optimized for search. When users interact with the web application, Kerko gets all the required data from that search index, without ever contacting zotero.org. It is through a scheduled task, which runs at regular intervals, that Kerko automatically brings its search index up to date by using the Zotero Web API to retrieve the latest data from zotero.org.</p> <p>Kerko is implemented in Python using the Flask framework. As an application component, Kerko only works when incorporated into a Flask application. Such an application, KerkoApp, is available for you to use, and can be deployed on a web server. KerkoApp can be seen as just a thin layer over Kerko. It might work for you if you like the default appearance, and if the provided configuration options are sufficient for your needs.</p> <p>For more advanced needs, you could consider building a custom application, possibly derived from KerkoApp, where additional customizations could be implemented in Python. In this scenario, it is not recommended that you change Kerko itself, but that you use Kerko's Python API to implement your customizations. Kerko is actually a Flask \"blueprint\" (similar to what some other systems might call a plugin or an extension), which allows a modular architecture where the application integrates and extends Kerko, and possibly other blueprints as well; the Kerko-powered bibliography could be just one component of a larger Flask application.</p>"},{"location":"#demo-site","title":"Demo site","text":"<p>A demo site, which is based on KerkoApp, is available for you to try. You may also view the Zotero library that contains the source data for the demo site.</p>"},{"location":"#sites-using-kerko","title":"Sites using Kerko","text":"<p>The following sites are powered by Kerko:</p> <ul> <li>Bibliographie francophone sur l'archivistique</li> <li>Community Knowledge Open Library on English-Speaking Quebec</li> <li>Lipedema Foundation LEGATO Lipedema Library</li> <li>Open Development &amp; Education Evidence Library</li> <li>The EdTech Hub Evidence Library</li> <li>University of Saint Joseph Research Output</li> </ul> <p>Are you using Kerko?</p> <p>If you would like to add your Kerko-powered site to this list, please e-mail us or submit a pull request.</p>"},{"location":"#features","title":"Features","text":"<p>The main features provided by Kerko are:</p> <ul> <li>Faceted search interface: allows exploration of the bibliography both in   search mode and in browsing mode, potentially suiting different user needs,   behaviors, and abilities. For example, users with a prior idea of the topic or   expected results may enter keywords or a more complex query in a search field,   while those who wish to become familiar with the content of the bibliography   or discover new topics may choose to navigate along the proposed facets, to   narrow or broaden their search. Since both modes are integrated into a single   interface, it is possible to combine them.</li> <li>Keyword search features:<ul> <li>Boolean operators:<ul> <li><code>AND</code>: matches items that contain all specified terms. This is the   default relation between terms when no operator is specified, e.g.,   <code>a b</code> is the same as <code>a AND b</code>.</li> <li><code>OR</code>: matches items that contain any of the specified terms, e.g.,   <code>a OR b</code>.</li> <li><code>NOT</code>: excludes items that match the term, e.g., <code>NOT a</code>.</li> <li>Boolean operators must be specified in uppercase and may be translated   in other languages.</li> </ul> </li> <li>Logical grouping (with parentheses), e.g., <code>(a OR b) AND c</code>.</li> <li>Sequence of words (with double quotes), e.g., <code>\"a b c\"</code>. The default   difference between word positions is 1, meaning that an item will match if   it contains the words next to each other, but a different maximum distance   may be selected (with the tilde character), e.g. <code>\"web search\"~2</code> allows   up to 1 word between <code>web</code> and <code>search</code>, meaning it could match <code>web site   search</code> as well as <code>web search</code>.</li> <li>Term boosting (with the caret), e.g., <code>faceted^2 search browsing^0.5</code>   specifies that <code>faceted</code> is twice as important as <code>search</code> when computing   the relevance score of results, while <code>browsing</code> is half as important.   Boosting may be applied to a logical grouping, e.g., <code>(a b)^3 c</code>.</li> <li>Keyword search is case-insensitive, accents are folded, and punctuation is   ignored. To further improve recall (albeit at the cost of precision),   stemming is also performed on terms from most text fields, e.g., title,   abstract, notes. Stemming relieves the user from having to specify all   variants of a word when searching, e.g., terms such as <code>search</code>,   <code>searches</code>, and <code>searching</code> all return the same results. The Snowball   algorithm is used for that purpose.</li> <li>Full-text search: the text content of PDF attachments can be searched.</li> <li>Scope of search: users may choose to search everywhere, in   author/contributor names, in titles, in publication years, in all fields   (i.e., in metadata and notes), or in documents (i.e., in the text content   of attachments). Applications may provide additional choices.</li> </ul> </li> <li>Faceted browsing: allows filtering by topic (Zotero tag), by resource type   (Zotero item type), by publication year, or by resource language. Moreover,   you may define additional   facets   modeled on collections and subcollections; in such case, any collection can be   represented as a facet, and each subcollection as a value within that facet.   By taking advantage of Zotero's ability to assign any given item to multiple   collections, a faceted classification scheme can be designed, including   hierarchical subdivisions within facets.</li> <li>Relevance scoring: provided by the Whoosh library and based on the   BM25F algorithm, which determines how important a term is to a document in   the context of the whole collection of documents, while taking into account   its relation to document structure (in this regard most fields are neutral,   but the score is boosted when a term appears in specific fields, e.g., DOI,   ISBN, ISSN, title, author/contributor). Any keyword search asks the question   \"how well does this document match this query clause?\", which requires   calculating a relevance score for each document. Filtering with facets, on the   other hand, has no effect on the score because it asks \"does this document   match this query clause?\", which leads to a yes or no answer.</li> <li>Sort options: by relevance score (only applicable to keyword search), by   publication date, by author, by title.</li> <li>Citation styles: any from the Zotero Style Repository, or   custom stylesheet defined in the Citation Style Language (stylesheet   must be accessible by URL).</li> <li>Language support: the default language of the user interface is English,   but some translations are provided. Additional   translations may be created using gettext-compatible tools (see Translating   Kerko). Also to consider: locales   supported by the Zotero Data Schema (which provides the names   of fields, item types and author types displayed by Kerko); languages   supported by Whoosh (which provides the search capabilities), i.e., ar, da,   nl, en, fi, fr, de, hu, it, no, pt, ro, ru, es, sv, tr.</li> <li>Semantic markup: pages generated by Kerko embed HTML markup that can be   detected by web crawlers (helping the indexing of your records by search   engines) or by web browsers (allowing users of reference management tools to   easily import metadata in their library). Supported schemes are:<ul> <li>OpenURL COinS, in search results pages and individual   bibliographic record pages. COinS is recognized by many reference   management tools, including the Zotero   Connector browser extension.</li> <li>Highwire Press tags, in the individual bibliographic record pages of book,   conference paper, journal article, report or thesis items. These tags are   recommended for indexing by Google Scholar, and   are recognized by many other databases and reference management tools,   including the Zotero Connector browser extension.</li> </ul> </li> <li>Web feeds: users of news aggregators or feed readers may get updates when   new bibliographic records are added. They may subscribe to the main feed, or   to one or more custom feeds.<ul> <li>The main feed lists the most recently added bibliographic records.</li> <li>Any search page has a related custom feed that lists the most recently   added bibliographic records that match the search criteria. Thus, a user   can obtain a custom feed for a particular area of interest simply by   entering keywords to search and/or selecting filters.</li> <li>Feeds are provided in the Atom syndication format.</li> <li>Basic metadata is provided directly in the feeds, using both Atom and   unqualified Dublin Core elements.</li> <li>An age limit may be configured to exclude older items from the feeds. This   may be useful to bibliographies that are frequently updated and mostly   meant to promote recent literature (all resources still remain visible to   the search interface regardless of their age).</li> </ul> </li> <li>Sitemap: an XML Sitemap is automatically generated, and you   may use it to help search engines discover your bibliographic records.</li> <li>Exporting: users may export individual records as well as complete   bibliographies corresponding to search results. By default, download links are   provided for the RIS and BibTeX formats, but applications may be configured to   export any format supported by the Zotero API.</li> <li>Printing: stylesheets are provided for printing individual bibliographic   records as well as lists of search results. When printing search results, all   results get printed (not just the current page of results).</li> <li>Notes and attachments: notes, attached files, and attached links to URIs   are synchronized from zotero.org and made available to users of the   bibliography. Regular expressions may be used to include or exclude such child   items from the bibliography, based on their tags.</li> <li>DOI, ISBN and ISSN resolver: items that have such identifier in your   library can be referenced by appending their identifier to your Kerko site's   base URL.</li> <li>Relations: bibliographic record pages show links to related items, if any.   You may define such relations using Zotero's Related field. Moreover, Kerko   adds the Cites and Cited by relation types, which can be managed in Zotero   through notes (see    guide). Custom   applications can add more types of relations if desired.</li> <li>Pages: basic informational pages can be defined using content from Zotero   standalone notes (see   guide).</li> <li>Badges: custom applications can have icons conditionally displayed next to   items.</li> <li>Responsive design: the simple default implementation works on large   monitors as well as on small screens. It is based on Bootstrap.</li> <li>Google Analytics integration: just provide a Google Analytics stream ID to   have Kerko automatically include the tracking code into its pages.</li> <li>Integration: as a Flask blueprint, Kerko can be   integrated into any Flask application. For a standalone application, however,   you may simply install   KerkoApp.</li> <li>Customizable front-end: applications may partly or fully replace the   default templates, scripts and stylesheets with their own.</li> <li>Command line interface (CLI): Kerko provides commands for synchronizing or   deleting its data.</li> </ul> <p>KerkoApp is a standalone application built around Kerko. It inherits all of Kerko's features and it provides a few additions of its own:</p> <ul> <li>Configuration files: allow separation of configuration from code and   enable the Twelve-factor App methodology. Environment   variables and TOML configuration files are supported. Secrets,   server-specific parameters, and general parameters can be configured in   separate files.</li> <li>Page templates for common HTTP errors.</li> <li>Syslog logging handler (for Unix environments).</li> </ul>"},{"location":"#requirements","title":"Requirements","text":"<p>Kerko requires Python 3.8 or later.</p> <p>Required Python packages will be automatically installed when installing Kerko. The main ones are:</p> <ul> <li>Babel: utilities for internationalization and localization.</li> <li>Bootstrap-Flask: helper for integrating Bootstrap.</li> <li>Click: command line interface creation kit.</li> <li>Flask: web application framework.</li> <li>Flask-Babel: integration of Flask and Babel.</li> <li>Flask-WTF: integration of Flask and WTForms.</li> <li>Jinja2: template engine.</li> <li>Pydantic: configuration parsing and validation.</li> <li>Pyzotero: Python client for the Zotero API.</li> <li>w3lib: URL and HTML manipulation utilities.</li> <li>Werkzeug: WSGI web application library (also required by Flask).</li> <li>Whoosh: pure Python full-text indexing and searching library.</li> <li>WTForms: web forms validation and rendering library.</li> </ul> <p>The following front-end resources are loaded from CDNs by Kerko's default templates (but could be completely removed or replaced in custom templates):</p> <ul> <li>Bootstrap: front-end component library for web applications.</li> <li>FontAwesome: beautiful open source icons.</li> <li>jQuery: JavaScript library (required by Bootstrap).</li> <li>Popper.js: JavaScript library for handling tooltips, popovers, etc. (used by   Bootstrap).</li> </ul>"},{"location":"#known-limitations","title":"Known limitations","text":"<p>Before choosing Kerko for your project, you might want to review the following known limitations of Kerko:</p> <ul> <li>The system can handle relatively large bibliographies (it has been tested with   over 15,000 references), but the number of distinct facet values can have more   impact on response times than the number of records. For the best response   times, it is recommended to limit the number of distinct facet values under a   few hundreds.</li> <li>Kerko can only manage a single bibliography per application.</li> <li>Although Kerko can be integrated in a multilingual web application were the   visitor may select a language, Zotero does not provide a way to manage tags or   collections in multiple languages. Thus, there is no easy way for Kerko to   provide those names in the user's selected language.</li> <li>Whoosh does not provide much out-of-the-box support for non-Western languages.   Therefore, search might not work very well with such languages.</li> <li>Zotero is the sole reference management tool supported as a back-end to Kerko.</li> </ul>"},{"location":"about/","title":"About","text":"<p>Kerko was inspired by prior work accomplished by Whisky Echo Bravo on two projects:</p> <ul> <li>Bibliographie sur l\u2019histoire de   Montr\u00e9al, developed in 2014 by   David Lesieur and Patrick Fournier, of Whisky Echo Bravo, for the Laboratoire   d'histoire et de patrimoine de Montr\u00e9al (Universit\u00e9 du   Qu\u00e9bec \u00e0 Montr\u00e9al, Canada).</li> <li>Bibliography on English-speaking Quebec,   developed in 2017 by David Lesieur, for the Quebec English-Speaking   Communities Research Network   (QUESCREN) (Concordia   University, Canada).</li> </ul> <p>In 2019, Whisky Echo Bravo was asked to work on another similar project. That made it clear that a general solution would benefit many organizations. However, software from the prior projects had to be rewritten in order to be more adaptable to a variety of needs. That led to Kerko, whose initial development was made possible through the following project:</p> <ul> <li>Bibliographie francophone sur l'archivistique,   funded by the   Association internationale des archives francophones (AIAF)   and hosted by the   \u00c9cole de biblioth\u00e9conomie et des sciences de l\u2019information (EBSI)   (Universit\u00e9 de Montr\u00e9al, Canada).</li> </ul> <p>Since then, Kerko has continued to evolve, thanks to work by Whisky Echo Bravo and other contributors, often through funding provided by organizations needing new features or customizations of Kerko.</p>"},{"location":"about/#design-choices","title":"Design choices","text":"<p>Here are some of the design choices that have guided the development of Kerko so far:</p> <ul> <li>Do not build back-end software. Let Zotero manage the data.</li> <li>Allow Kerko to integrate into richer web applications.</li> <li>Only provide features that pertain to the exploration of a bibliography.   Other features, even when they are common to many web sites, do not belong to   Kerko and should be left to the applications to implement.</li> <li>Use a lightweight framework to avoid carrying many features that are not   needed by Kerko (Flask was selected for this reason).</li> <li>Use pure Python dependencies to keep installation and deployment simple (Hence   the use of Whoosh for search, for example, instead of Elasticsearch or Solr).</li> <li>Use a classic server-side rendering architecture. Keep it simple and avoid   asset management when possible.</li> </ul>"},{"location":"about/#etymology","title":"Etymology","text":"<p>The name Zotero reportedly derives from the Albanian word zot\u00ebroj, which means \"to learn something extremely well, that is to master or acquire a skill in learning\" (Source: Mark Dingemanse, 2008, Etymology of Zotero).</p> <p>The name Kerko is a nod to Zotero as it takes a similar etymological route: it derives from the Albanian word k\u00ebrkoj, which means \"to ask, to request, to seek, to look for, to demand, to search\" and seems fit to describe a search tool.</p>"},{"location":"changelog/","title":"Changelog","text":"<p>Before doing an upgrade, please check the \"How to upgrade\" section of the Kerko documentation.</p>"},{"location":"changelog/#120-2024-08-03","title":"1.2.0 (2024-08-03)","text":"<p>New features:</p> <ul> <li>Add the \"Resource language\" facet. It is disabled by default, but can be   enabled by setting the <code>kerko.facets.language.enabled</code> configuration parameter   to <code>true</code>. By default, Kerko will try to normalize the language names to make   the facet more usable; see <code>kerko.facets.language.</code> in the configuration   parameters documentation for details.</li> </ul> <p>Removed features:</p> <ul> <li>Custom translation management commands that depended on Setuptools and   <code>setup.py</code> have been removed. Equivalent <code>pybabel</code> commands can be used   instead (see the updated Localization section of the documentation).</li> </ul> <p>Other changes:</p> <ul> <li>Change the default configuration for some parameters:<ul> <li><code>kerko.facets.item_type.initial_limit</code>, now <code>10</code> instead of <code>0</code>.</li> <li><code>kerko.facets.item_type.initial_limit_leeway</code>, now <code>4</code> instead of <code>2</code>.</li> <li><code>kerko.facets.link.initial_limit_leeway</code>, now <code>0</code> instead of <code>2</code>.</li> <li><code>kerko.facets.tag.initial_limit</code>, now <code>10</code> instead of <code>0</code>.</li> <li><code>kerko.facets.tag.initial_limit_leeway</code>, now <code>4</code> instead of <code>2</code>.</li> <li><code>kerko.facets.year.initial_limit_leeway</code>, now <code>0</code> instead of <code>2</code>.</li> </ul> </li> <li>Update Portuguese translations. Thanks to Gon\u00e7alo Cordeiro.</li> <li>Move project metadata from <code>setup.cfg</code> to <code>pyproject.toml</code>.</li> <li>Build distribution package with Hatch instead of Setuptools.</li> <li>Use dynamic package versioning so that installers such as <code>pip</code> do not mistake   a development version for a previously published version. Version numbers are   now extracted from the tags and revisions of the Git repository.</li> <li>Reduce XML sitemaps size.</li> <li>Improve documentation.</li> </ul> <p>Deprecated APIs:</p> <ul> <li>The Python variable <code>kerko.TRANSLATION_DIRECTORIES</code> is deprecated and will be   removed in Kerko 2.x. The variable <code>kerko.TRANSLATION_DIRECTORY</code> should be   used instead, and its type is a string instead of a list. If you are using a   custom application, please adapt it accordingly (you may check KerkoApp's   <code>__init__.py</code> for an example).</li> </ul>"},{"location":"changelog/#110-2023-12-23","title":"1.1.0 (2023-12-23)","text":"<p>Features:</p> <ul> <li>Add the \"Publication year\" search scope. It is enabled by default, but can be   disabled by setting the <code>kerko.scopes.pubyear.enabled</code> configuration parameter   to <code>false</code>.</li> <li>Add new configuration parameter <code>kerko.pages.*.</code> for defining content pages   whose content come from selected Zotero standalone notes.</li> <li>Add a <code>\"page\"</code> type for the <code>kerko.link_groups.*.</code> configuration table, to   allow the creation of links to content pages.</li> <li>Add configuration parameters <code>kerko.performance.whoosh_index_memory_limit</code> and   <code>kerko.performance.whoosh_index_processors</code> to give some control over the   Whoosh search engine's indexing performance.</li> <li>Allow italic, bold, subscript, superscript and small-caps on Zotero fields   (such as titles and abstracts) where rich text formatting   tags are used.</li> <li>Add Spanish translation. Thanks to Albert   Ormazabal.</li> </ul> <p>Bug fixes:</p> <ul> <li>Fix item title missing from item pages and from Atom feeds when item type is   Case, Email, or Statute.</li> <li>Fix incorrect sorting of search results by title when item type is Case,   Email, or Statute.</li> <li>Fix incorrect escaping of HTML markup in the HTML content elements of Atom   feeds.</li> <li>Fix incorrect scope, analyzer, and boost factor associated with the <code>caseName</code>   search field.</li> <li>Fix crash when a facet specifies no sort order.</li> <li>Fix crash on empty search result pages when configuration parameter   <code>kerko.features.print_results_max_count</code> is greater than zero.</li> <li>Fix badges displayed too close to title on item pages.</li> </ul> <p>Other changes:</p> <ul> <li>Add <code>rel=\"noopener\"</code> to <code>target=\"_blank\"</code> links.</li> <li>Add <code>rel=\"noreferrer\"</code> to links derived from Zotero library data, e.g.,   user-provided URLs, DOIs, link attachments.</li> <li>Reduce the default memory limit for Whoosh's index writer from 256 MB to 128   MB. This can prevent swapping with large libraries on small machines. The   default limit may now be changed with the   <code>kerko.performance.whoosh_index_memory_limit</code> parameter.</li> <li>Improve speed of single-item search pages, i.e., search pages having the   <code>page-len=1</code> URL parameter. This is achieved through removal of the <code>id</code>   parameter from pagination URLs. Obtaining those ids was requiring extra   processing. Instead, the <code>id</code> parameter is now added through the browser   History API when a pagination link is visited.</li> <li>Add support for Python 3.12.</li> <li>Replace pylint, pycodestyle, pydocstyle with Ruff.</li> <li>Replace Yapf with Ruff formatter. Reformat whole code base.</li> <li>Add pre-commit hooks. Run Ruff and other code checks on pre-commit.</li> <li>Add template blocks to facilitate theming.</li> <li>Improve documentation.</li> </ul> <p>Backwards incompatible changes:</p> <ul> <li>Drop support for Python 3.7 (EOL).</li> </ul> <p>Possibly backwards incompatible changes (more or less internal API changes):</p> <ul> <li>Kerko no longer provides a <code>kerko.blueprint</code> global object. Applications must   now instantiate the blueprint by calling <code>kerko.make_blueprint()</code> before   registering it. This prevents attempts to mutate the object after its   registration, especially in tests.</li> <li>Upgrade many dependencies, including new major versions of Flask (3.x),   Flask-Babel (4.x), Werkzeug (3.x).</li> <li><code>kerko.extractors.TransformerExtractor</code> no longer applies transformers on   <code>None</code> values. If you need a transformer to process a <code>None</code> value (Kerko   itself has no such transformer), you now have to set the new <code>skip_none_value</code>   argument to <code>False</code> when instantiating the extractor.</li> </ul>"},{"location":"changelog/#100-2023-07-24","title":"1.0.0 (2023-07-24)","text":"<p>Features:</p> <ul> <li>Add new configuration parameter <code>kerko.features.download_item</code>.</li> </ul> <p>Bug fixes:</p> <ul> <li>Fix Gunicorn not exiting if the default TOML config has errors (use the   <code>errno.EINTR</code> error code). Not an issue anyone should have encountered!</li> </ul> <p>Backwards incompatible changes:</p> <ul> <li>Rename the following configuration parameters:<ul> <li><code>kerko.features.download_results_link</code> \u2192 <code>kerko.features.download_results</code>.</li> <li><code>kerko.features.print_item_link</code> \u2192 <code>kerko.features.print_item</code></li> <li><code>kerko.features.print_results_link</code> \u2192 <code>kerko.features.print_results</code></li> </ul> </li> </ul> <p>Other changes:</p> <ul> <li>Improve documentation.</li> </ul>"},{"location":"changelog/#100alpha2-2023-07-12","title":"1.0.0alpha2 (2023-07-12)","text":"<p>Features:</p> <ul> <li>Add new configuration parameters <code>kerko.link_groups.*.</code> for defining sets of   links that may be used for navigation.</li> <li>Add a breadcrumb trail to all pages. One or more base links can be configured   (see configuration parameters <code>kerko.breadcrumb</code> and   <code>kerko.link_groups.breadcrumb_base</code>).</li> </ul> <p>Bug fixes:</p> <ul> <li>Fix validation pattern too restrictive for the <code>kerko.zotero.csl_style</code>   configuration parameter.</li> </ul> <p>Backwards incompatible changes:</p> <ul> <li>Items from the main navigation bar are now based on the   <code>kerko.link_groups.navbar</code> configuration. There is no default translation for   it. To change the default text or to translate it, you must override the   default <code>kerko.link_groups.navbar</code> in your configuration file. If you have   overridden the <code>_navbar_items.html.jinja2</code> template and wish to use the   configuration, you might want to adapt it, or revert to the default template.</li> </ul> <p>Other changes:</p> <ul> <li>Improve documentation.</li> </ul>"},{"location":"changelog/#100alpha1-2023-06-29","title":"1.0.0alpha1 (2023-06-29)","text":"<p>Features:</p> <ul> <li>Add the <code>--full</code> option to the <code>sync</code> command line interface (CLI) command.</li> </ul> <p>Bug fixes:</p> <ul> <li>Fix validation pattern too restrictive for the <code>kerko.facets.*.collection_key</code>   configuration parameter.</li> <li>Fix incorrect typing for the <code>kerko.features.download_results_max_count</code> and   <code>kerko.features.print_results_max_count</code> configuration parameters.</li> </ul> <p>Other changes:</p> <ul> <li> <p>Rename the default branch of the repository from 'master' to 'main'. If you   have cloned the repository with Git, use the following commands to rename your   local branch:</p> <pre><code>git branch -m master main\ngit fetch origin\ngit branch -u origin/main main\ngit remote set-head origin -a\n</code></pre> </li> <li> <p>Make the <code>config</code> CLI command show the configuration in TOML format.</p> </li> <li>Make the <code>config</code> CLI command hide secrets by default. Add a <code>--show-secrets</code>   option.</li> <li>Improve documentation.</li> </ul> <p>Backwards incompatible changes:</p> <ul> <li>Prevent the <code>clean</code> CLI command from cleaning everything by default. To delete   everything, you now have to run <code>flask kerko clean everything</code>. This may help   prevent accidental deletion of the cache, which in some instances can take   long to rebuild.</li> <li>Rename the following configuration parameters:<ul> <li><code>kerko.citation_formats.*</code> \u2192 <code>kerko.bib_formats.*</code>.</li> <li><code>kerko.features.download_citations_link</code> \u2192 <code>kerko.features.download_results_link</code></li> <li><code>kerko.features.download_citations_max_count</code> \u2192 <code>kerko.features.download_results_max_count</code></li> <li><code>kerko.features.print_citations_link</code> \u2192 <code>kerko.features.print_results_link</code></li> <li><code>kerko.features.print_citations_max_count</code> \u2192 <code>kerko.features.print_results_max_count</code></li> </ul> </li> <li>Rename the following views:<ul> <li><code>item_citation_download</code> \u2192 <code>item_bib_download</code></li> <li><code>search_citation_download</code> \u2192 <code>search_bib_download</code></li> </ul> </li> </ul>"},{"location":"changelog/#100alpha0-2023-06-26","title":"1.0.0alpha0 (2023-06-26)","text":"<p>Warning: Upgrading from version 0.9 or earlier will require that you adapt your installation and configuration files, then rebuild your search index. Use the commands below, then restart the application. If you are using KerkoApp, make sure to check its changelog.</p> <pre><code>flask kerko clean index\nflask kerko sync index\n</code></pre> <p>Features:</p> <ul> <li>Add many new configuration parameters. Please refer to the configuration   parameters documentation for the full list.</li> <li>Add optional \"Open in Zotero\" and \"View on zotero.org\" buttons to item pages.   These are disabled by default (see new parameters   <code>kerko.features.open_in_zotero_app</code> and <code>kerko.features.open_in_zotero_web</code>).   Even when these are enabled, a user who wishes to use such button must first   enable it from the (also new) Preferences dialog.</li> <li>Add a web API endpoint for retrieving information about the last   synchronization from Zotero.</li> <li>Add the <code>kerko config</code> command to the Flask command line interface for   displaying all configuration parameters.</li> </ul> <p>Other changes:</p> <ul> <li>Restructure and expand documentation into a unified documentation site for   both Kerko and KerkoApp.</li> <li>Add Portuguese translation. Thanks to Gon\u00e7alo Cordeiro.</li> </ul> <p>Backwards incompatible changes:</p> <ul> <li>Raise the minimum required versions of Flask, Flask-Babel, Bootstrap-Flask,   and WTForms. If you have a custom application, some of those may introduce   breaking changes.</li> <li>The data directory has a new default location relative to the instance path.   Please check the documentation for the <code>DATA_PATH</code> and <code>INSTANCE_PATH</code>   configuration parameters. You may need to set one or both of those parameters,   and/or move your existing data directory.</li> <li>Almost all configuration parameters have been renamed and/or moved into a   hierarchical structure. Hierarchical parameters are referred to using   path-like, dot-separated parameter names, and may conveniently be set with the   <code>kerko.config_helpers.config_set()</code> function. Here is a mapping of the changed   parameters:<ul> <li><code>KERKO_BOOTSTRAP_VERSION</code> \u2192 <code>kerko.assets.bootstrap_version</code></li> <li><code>KERKO_CSL_STYLE</code> \u2192 <code>kerko.zotero.csl_style</code></li> <li><code>KERKO_COMPOSER</code> \u2192 <code>kerko_composer</code></li> <li><code>KERKO_DATA_DIR</code> \u2192 <code>DATA_PATH</code>. Now optional, relative to the instance   path, and defaulting to <code>kerko</code> instead of <code>data/kerko</code>.</li> <li><code>KERKO_DOWNLOAD_ATTACHMENT_NEW_WINDOW</code> \u2192 <code>kerko.features.download_attachment_new_window</code></li> <li><code>KERKO_DOWNLOAD_CITATIONS_LINK</code> \u2192 <code>kerko.features.download_citations_link</code></li> <li><code>KERKO_DOWNLOAD_CITATIONS_MAX_COUNT</code> \u2192 <code>kerko.features.download_citations_max_count</code></li> <li><code>KERKO_FEEDS</code> \u2192 <code>kerko.feeds.formats</code></li> <li><code>KERKO_FEEDS_FIELDS</code> \u2192 <code>kerko.feeds.fields</code></li> <li><code>KERKO_FEEDS_MAX_DAYS</code> \u2192 <code>kerko.feeds.max_days</code></li> <li><code>KERKO_FEEDS_REJECT_ANY</code> \u2192 <code>kerko.feeds.reject_any</code></li> <li><code>KERKO_FEEDS_REQUIRE_ANY</code> \u2192 <code>kerko.feeds.require_any</code></li> <li><code>KERKO_FULLTEXT_SEARCH</code> \u2192 <code>kerko.search.fulltext</code></li> <li><code>KERKO_HIGHWIREPRESS_TAGS</code> \u2192 <code>kerko.meta.highwirepress_tags</code></li> <li><code>KERKO_JQUERY_VERSION</code> \u2192 <code>kerko.assets.jquery_version</code></li> <li><code>KERKO_PAGE_LEN</code> \u2192 <code>kerko.pagination.page_len</code></li> <li><code>KERKO_PAGER_LINKS</code> \u2192 <code>kerko.pagination.pager_links</code></li> <li><code>KERKO_POPPER_VERSION</code> \u2192 <code>kerko.assets.popper_version</code></li> <li><code>KERKO_PRINT_CITATIONS_LINK</code> \u2192 <code>kerko.features.print_citations_link</code></li> <li><code>KERKO_PRINT_CITATIONS_MAX_COUNT</code> \u2192 <code>kerko.features.print_citations_max_count</code></li> <li><code>KERKO_PRINT_ITEM_LINK</code> \u2192 <code>kerko.features.print_item_link</code></li> <li><code>KERKO_RELATIONS_INITIAL_LIMIT</code> \u2192 <code>kerko.features.relations_initial_limit</code></li> <li><code>KERKO_RELATIONS_LINKS</code> \u2192 <code>kerko.features.relations_links</code></li> <li><code>KERKO_RELATIONS_SORT</code> \u2192 <code>kerko.features.relations_sort</code></li> <li><code>KERKO_RESULTS_ABSTRACTS_MAX_LENGTH</code> \u2192 <code>kerko.features.results_abstracts_max_length</code></li> <li><code>KERKO_RESULTS_ABSTRACTS_MAX_LENGTH_LEEWAY</code> \u2192 <code>kerko.features.results_abstracts_max_length_leeway</code></li> <li><code>KERKO_RESULTS_ABSTRACTS</code> \u2192 <code>kerko.features.results_abstracts</code></li> <li><code>KERKO_RESULTS_ABSTRACTS_TOGGLER</code> \u2192 <code>kerko.features.results_abstracts_toggler</code></li> <li><code>KERKO_RESULTS_ATTACHMENT_LINKS</code> \u2192 <code>kerko.features.results_attachment_links</code></li> <li><code>KERKO_RESULTS_FIELDS</code> \u2192 <code>kerko.search.result_fields</code></li> <li><code>KERKO_RESULTS_URL_LINKS</code> \u2192 <code>kerko.features.results_url_links</code></li> <li><code>KERKO_TEMPLATE_ATOM_FEED</code> \u2192 <code>kerko.templates.atom_feed</code></li> <li><code>KERKO_TEMPLATE_BASE</code> \u2192 <code>kerko.templates.base</code></li> <li><code>KERKO_TEMPLATE_ITEM</code> \u2192 <code>kerko.templates.item</code></li> <li><code>KERKO_TEMPLATE_LAYOUT</code> \u2192 <code>kerko.templates.layout</code></li> <li><code>KERKO_TEMPLATE_SEARCH</code> \u2192 <code>kerko.templates.search</code></li> <li><code>KERKO_TEMPLATE_SEARCH_ITEM</code> \u2192 <code>kerko.templates.search_item</code></li> <li><code>KERKO_TITLE</code> \u2192 <code>kerko.meta.title</code></li> <li><code>KERKO_WHOOSH_LANGUAGE</code> \u2192 <code>kerko.search.whoosh_language</code></li> <li><code>KERKO_WITH_JQUERY</code> \u2192 <code>kerko.assets.with_jquery</code></li> <li><code>KERKO_WITH_POPPER</code> \u2192 <code>kerko.assets.with_popper</code></li> <li><code>KERKO_ZOTERO_API_KEY</code> \u2192 <code>ZOTERO_API_KEY</code></li> <li><code>KERKO_ZOTERO_BATCH_SIZE</code> \u2192 <code>kerko.zotero.batch_size</code></li> <li><code>KERKO_ZOTERO_LIBRARY_ID</code> \u2192 <code>ZOTERO_LIBRARY_ID</code></li> <li><code>KERKO_ZOTERO_LIBRARY_TYPE</code> \u2192 <code>ZOTERO_LIBRARY_TYPE</code></li> <li><code>KERKO_ZOTERO_LOCALE</code> \u2192 <code>kerko.zotero.locale</code></li> <li><code>KERKO_ZOTERO_MAX_ATTEMPTS</code> \u2192 <code>kerko.zotero.max_attempts</code></li> <li><code>KERKO_ZOTERO_WAIT</code> \u2192 <code>kerko.zotero.wait</code></li> </ul> </li> <li>The Kerko configuration should now be initialized by a call like   <code>kerko.config_helpers.config_update(app.config, kerko.DEFAULTS)</code>.</li> <li><code>Composer.__init__()</code> now only takes a configuration object as argument   instead of a bunch of arguments. Thus, the initial values of the <code>Composer</code>   instance now depend solely on the configuration.</li> <li>Remove the <code>KERKO_USE_TRANSLATIONS</code> configuration variable. Kerko now relies   on the application's default Babel domain and translation directories. Custom   applications that wish to load Kerko's translations should now add   <code>kerko.TRANSLATION_DOMAIN</code> and <code>kerko.TRANSLATION_DIRECTORIES</code> to their Babel   configuration.</li> <li>The <code>__init__()</code> method of <code>FacetSpec</code> and its subclasses now only accept   keyword arguments.</li> <li>The <code>sort_key</code> argument to <code>FacetSpec.__init__()</code> is now <code>sort_by</code>.</li> <li><code>Composer</code> built-in fields <code>z_dateAdded</code> and <code>z_dateModified</code> are now named   <code>date_added</code> and <code>date_modified</code> respectively.</li> </ul>"},{"location":"changelog/#09-2022-12-29","title":"0.9 (2022-12-29)","text":"<p>Warning: Upgrading from version 0.8.x or earlier will require that you rebuild your search index. Use the following commands, then restart the application:</p> <pre><code>flask kerko clean index\nflask kerko sync index\n</code></pre> <p>Features:</p> <ul> <li>Add expand/collapse actions on facet values, allowing full exploration of   hierarchical facets without changing the current search.</li> <li>Add an optional initial limit on the number of values to show under each   facet. When the initial limit is reached, a \"show more\" button allows the user   to expand the full list.</li> <li>Add Atom syndication feeds.</li> <li>Allow searching items by their Zotero key.</li> <li>Add XML sitemap.</li> <li>Add the <code>kerko count</code> CLI command (mostly meant for development purposes).</li> </ul> <p>Bug fixes:</p> <ul> <li>Fix last sync time not displayed at the bottom of search results when   <code>KERKO_PRINT_CITATIONS_LINK</code> and <code>KERKO_DOWNLOAD_CITATIONS_LINK</code> are both set   to <code>False</code>.</li> <li>Fix the <code>kerko sync</code> CLI command not returning an error code with some types   of failures.</li> <li>Fix invalid HTML in help modal.</li> </ul> <p>Other changes:</p> <ul> <li>Handle new Zotero fields introduced with the new 'preprint' item type.</li> <li>Apply a boost factor to DOI, ISBN and ISSN fields extracted from the Extra   field (previously, only the dedicated Zotero fields had a boost factor).</li> <li>Under each facet, always show the facet's active filters first.</li> <li>Make facet values with long labels easier to read (by indenting wrapped lines   to the right of the checkbox).</li> <li>Add link to full bibliography from item pages.</li> <li>Add blocks in templates to facilitate theming.</li> <li>Remove <code>page</code> parameter from pagination links when <code>page=1</code>.</li> <li>Improve documentation.</li> <li>Make sync and schema-related error messages more helpful and user-friendly.</li> <li>Move pydocstyle config to <code>pyproject.toml</code>.</li> <li>Tag package as compatible with Python 3.10 and 3.11.</li> <li>Remove leftover code related to Python versions older than 3.7</li> </ul> <p>Backwards incompatible changes:</p> <ul> <li>Remove the <code>KERKO_FACET_COLLAPSING</code> option. The new initial limit on facets   values made this feature largely redundant.</li> <li>Remove the <code>collapsible</code> param from the <code>FacetSpec</code> class.</li> <li>Remove support for configuration variables <code>KERKO_ZOTERO_START</code> and   <code>KERKO_ZOTERO_END</code> (were only used for development and no longer practical).</li> </ul> <p>Changes that might break custom themes:</p> <ul> <li>The HTML markup and CSS styles of expand/collapse buttons have changed.</li> <li>The parameters of the <code>facet</code>, <code>facet_item</code>, <code>facet_items</code>, <code>facet_fields</code>   template macros have changed.</li> <li>The <code>facets-container</code>, <code>facets</code>, and <code>facets-modal-body</code> element ids are now   required in <code>search.html.jinja2</code>.</li> </ul> <p>Possibly backwards incompatible changes (more or less internal API changes):</p> <ul> <li>Rewrote the <code>criteria</code> module. <code>Criteria.keywords</code> and <code>Criteria.filters</code> work   pretty much as before, but everything else has changed.</li> <li>Rewrote the <code>query</code> module, which had organically grown into an tangled mess,   now replaced with the <code>searcher</code> module. This new API is completely different.</li> <li>Adapted view code to the above-mentioned <code>searcher</code> API.</li> <li>Split the monolithic <code>views</code> module into multiple modules under <code>views</code>   (<code>item_creators</code>, <code>item_facets</code>, <code>item_relations</code>, <code>routes</code>, <code>search</code>), and   moved <code>breadbox</code>, <code>meta</code> (as <code>item_meta</code>), <code>pager</code>, and <code>sorter</code> under   <code>views</code>.</li> </ul>"},{"location":"changelog/#081-2021-11-16","title":"0.8.1 (2021-11-16)","text":"<p>Bug fixes:</p> <ul> <li>Fix missing dependency for package building.</li> </ul>"},{"location":"changelog/#08-2021-11-16","title":"0.8 (2021-11-16)","text":"<p>Warning: Upgrading from version 0.7.x or earlier will require that you clean and re-sync your existing search index. Use the following commands, then restart the application:</p> <pre><code>flask kerko clean index\nflask kerko sync\n</code></pre> <p>Features:</p> <ul> <li>Allow full-text search of PDF attachments. This can be disabled by setting   <code>KERKO_FULLTEXT_SEARCH</code> to <code>False</code>. Since this feature relies on Zotero's   full-text indexing, you must make sure that it works in Zotero first; see   Zotero's   documentation.</li> <li>Add new search scopes \"Everywhere\" (to search both metadata fields and the   text content of attached documents) and \"In documents\" (to search the text   content of attached documents). The scope \"In all fields\" allows to search all   metadata fields, but not the text content of attached documents.</li> <li>Display \"View on {hostname}\" links under search result items, for quick access   to the items' URLs. These can be disabled by setting <code>KERKO_RESULTS_URL_LINKS</code>   to <code>False</code>.</li> <li>Move the \"Read\" buttons under search result items, as \"Read document\" links.   These can now be disabled by setting <code>KERKO_RESULTS_ATTACHMENT_LINKS</code> to   <code>False</code>.</li> <li>Display DOI field values as hyperlinks (both in DOI fields, and in the Extra   field when lines are prefixed with 'DOI:').</li> <li>Add support for imported file attachments, e.g., PDF files imported in your   Zotero library through the Zotero Connector. Previously, only \"attached copies   of files\" were supported.</li> <li>Standalone notes and file attachments are now allowed into the search index.   Kerko filters them out of search results, but custom applications could search   them. A new view, <code>standalone_attachment_download</code>, lets one retrieve a   standalone file attachment.</li> <li>Add configuration options for truncating long abstracts in search results   (<code>KERKO_RESULTS_ABSTRACTS_MAX_LENGTH</code> and   <code>KERKO_RESULTS_ABSTRACTS_MAX_LENGTH_LEEWAY</code>).</li> <li>Embed Highwire Press tags in item pages. This is enabled by default but can be   disabled by setting <code>KERKO_HIGHWIREPRESS_TAGS</code> to <code>False</code>.</li> <li>Allow tracking with Google Analytics (optional).</li> <li>Allow relations in child notes to be specified as HTML links, i.e., in the   <code>href</code> attribute of <code>&lt;a&gt;</code> elements.</li> <li>Allow inclusion or exclusion of items based on multiple tags (previously, only   a single pattern could be checked).</li> </ul> <p>Bug fixes:</p> <ul> <li>Fix irrelevant sync warnings, from extractors running on attachment items.</li> <li>Fix empty prev/next links in search pages metadata.</li> </ul> <p>Other changes:</p> <ul> <li>Make synchronization from Zotero much more efficient through incremental   updates. Instead of performing a full synchronization each time, Kerko now   retrieves just the newly added or updated items. This dramatically reduces the   number of Zotero API calls (and time) required to update Kerko's search index.   Note: More work is planned to eliminate some Zotero API calls that Kerko   still makes early in the synchronization process and that could be avoided   when its cache is already up-to-date.</li> <li>Add a <code>sync cache</code> command to the command line interface.</li> <li>On narrow screens, stack search form controls for better usability.</li> <li>Respond with an HTTP 503 (Service Unavailable) when the search index is empty   or unreadable.</li> <li>Make sorts more efficient by setting the <code>sortable</code> Whoosh flag on relevant   fields.</li> <li>Leading and trailing underscore characters (<code>_</code>) are now trimmed from facet   value labels. This happens after sorting the values, which means that the   underscore can still be used as a prefix to alter the alphabetical order.</li> <li>Support more timezone names. Timezone names such as 'US/Eastern' or   'Europe/London' previously did not work, and times could not be converted   to daylight saving times.</li> <li>Change labels:<ul> <li>\"Print this citation\" \u2192 \"Print this record\" (on item pages)</li> <li>\"Download this citation\" \u2192 \"Download this record\" (on item &amp; search pages)</li> </ul> </li> <li>Inject blocks in item Jinja2 template to facilitate theming.</li> <li>Slightly increase some top/bottom margins.</li> <li>Add the <code>type</code> HTML attribute to record download links.</li> <li>Add the <code>rel=\"alternate\"</code> HTML attribute to record download links on item   pages. Also add a corresponding <code>link</code> element to the page <code>head</code>.</li> <li>Added utilities for running automated integration tests. This will allow   testing many areas of Kerko that previously could hardly be tested.</li> </ul> <p>Backwards incompatible changes:</p> <ul> <li>Remove deprecated <code>kerko index</code> CLI command (use <code>kerko sync</code> instead).</li> </ul> <p>Possibly backwards incompatible changes (more or less internal API changes):</p> <ul> <li>Upgrade many dependencies, including new major versions of Flask (2.x), Jinja2   (3.x), Werkzeug (2.x), Click (8.x).</li> <li>The default list for the <code>KERKO_RESULTS_FIELDS</code> setting now includes the   <code>'url'</code> field. If you have overridden that setting in your application and   <code>KERKO_RESULTS_URL_LINKS</code> is enabled, you'll probably have to add <code>'url'</code> too.</li> <li>The schema field <code>item_type</code> has been renamed to <code>item_type_label</code>. If you   have custom templates, please review any use of <code>item.item_type</code>.</li> <li>The structure of the <code>kerko/_search-result.html.jinja2</code> template has changed   somewhat. If you have overridden it, you'll need to review the changes.</li> <li>The <code>ItemContext</code> class has been eliminated. The <code>Extractor.extract()</code> method   now receives an item's dictionary instead of an <code>ItemContext</code> object, and if   an item has children these are now available directly in the item (with the   <code>children</code> key). If you have created custom extractor classes, their   <code>extract()</code> method will need to be adapted accordingly.</li> <li>Some extractor classes have been renamed:<ul> <li><code>BaseAttachmentsExtractor</code> \u2192 <code>BaseChildAttachmentsExtractor</code></li> <li><code>BaseNotesExtractor</code> \u2192 <code>BaseChildNotesExtractor</code></li> <li><code>LinkedURIAttachmentsExtractor</code> \u2192 <code>ChildLinkedURIAttachmentsExtractor</code></li> <li><code>NotesTextExtractor</code> \u2192 <code>ChildNotesTextExtractor</code></li> <li><code>RawNotesExtractor</code> \u2192 <code>RawChildNotesExtractor</code></li> <li><code>RelationsInNotesExtractor</code> \u2192 <code>RelationsInChildNotesExtractor</code></li> <li><code>StoredFileAttachmentsExtractor</code> \u2192 <code>ChildFileAttachmentsExtractor</code></li> </ul> </li> <li>A view has been renamed:<ul> <li><code>item_attachment_download</code> \u2192 <code>child_attachment_download</code></li> </ul> </li> <li>A default field has been renamed:<ul> <li><code>alternateId</code> \u2192 <code>alternate_id</code></li> </ul> </li> </ul>"},{"location":"changelog/#071-2021-02-04","title":"0.7.1 (2021-02-04)","text":"<p>Security fixes:</p> <ul> <li>Fix unescaped date fields, causing a vulnerability to XSS attacks. This   vulnerability was introduced in version 0.7.</li> </ul> <p>Bug fixes:</p> <ul> <li>Fix wrong locale separator in the HTML lang attribute.</li> </ul> <p>Other changes:</p> <ul> <li>Remove unwanted spacing after dropdown labels.</li> </ul> <p>Documentation changes:</p> <ul> <li>Fix missing info about library groupID in configuration docs. Thanks   @drmikeuk for reporting the issue.</li> </ul>"},{"location":"changelog/#07-2021-01-08","title":"0.7 (2021-01-08)","text":"<p>Warning: Upgrading from version 0.6 or earlier will require that you clean and re-sync your existing search index. Use the following commands, then restart the application:</p> <pre><code>flask kerko clean index\nflask kerko sync\n</code></pre> <p>Features:</p> <ul> <li>Allow users to toggle the display of abstracts on search results pages.</li> <li>Allow inclusion or exclusion of items based on their tags   (#4).</li> <li>Show attached links to URIs on item pages.</li> <li>Show relations on item pages. The relation types provided by default are:</li> <li>Related, based on Zotero's Related field.</li> <li>Cites, managed through child notes containing Zotero URIs and tagged with     the <code>_cites</code> tag.</li> <li>Cited by, automatically inferred from Cites relations.</li> <li>The Extra field is now searched when searching \"in any fields\".</li> <li>Items that have a DOI, ISBN or ISSN identifier can be referenced by appending   their identifier to your Kerko site's base URL.</li> <li>Requests for the older URL of an item whose ID has changed are now   automatically redirected to the item's current URL. This relies on the   <code>dc.replaces</code> relation that's managed internally by Zotero on some operations   such as item merges.</li> <li>Help users who might mistakenly bookmark a search result's URL rather than the   item's permanent URL: Add an <code>id</code> parameter to the search result URLs, and   redirect the user to that item's permanent URL if the search result no longer   matches because of database changes.</li> <li>Redirect to the parent item's page when the user tries to request an   attachment that no longer exists.</li> <li>Improve accessibility based on WCAG recommendations and WAI-ARIA standards:</li> <li>Add labels to search form elements.</li> <li>Add landmark role <code>search</code> to the search form.</li> <li>Make the purpose of various links more obvious through improved or added     labels.</li> <li>Add the <code>aria-label</code> attribute to many elements.</li> <li>Add text to indicate the current value of widgets.</li> <li>Add the <code>aria-current</code> attribute to indicate the current value of widgets.</li> <li>Remove useless link to the current page from the pagination widget.</li> </ul> <p>Bug fixes:</p> <ul> <li>Fix crash when trying to sync a link attachment   (#3).</li> <li>Fix unhandled exception during sync when an attachment cannot be downloaded.</li> <li>Fix page numbers greater than the page count in search URLs generating wrong   page numbers for search result item URLs.</li> <li>Fix secondary keys getting sorted in reverse order with some sort options,   e.g., when sorting by newest first, results having the same date were then   sorted by creator name in reverse alphabetical order instead of alphabetical   order.</li> <li>Fix empty HTML element taking up horizontal space when there are no badges.</li> </ul> <p>Other changes:</p> <ul> <li>Display ISO 8601 calendar dates in a more readable format, using the   formatting style of the locale.</li> <li>Show a timezone abbreviation along with time of last update from Zotero.</li> <li>Add German translation. Thanks to @mmoole.</li> <li>Fix broken \"Getting started\" example in README.</li> <li>Migrate most package distribution options and metadata from <code>setup.py</code> to   <code>setup.cfg</code>.</li> <li>Migrate project to a <code>src</code> layout.</li> <li>Use Flask-Babel instead of its fork Flask-BabelEx, now that is has merged the   translation domain features from Flask-BabelEx.</li> </ul> <p>Backwards incompatible changes:</p> <ul> <li>Drop support for Python 3.6. Kerko is no longer being tested under Python 3.6.   Known issue with 3.6 at this point: some ISO 8601 dates cannot be parsed and   reformatted; instead of being displayed in a locale-sensitive manner, these   get displayed as is. More issues might arise in the future with Python 3.6 as   Kerko continues to evolve.</li> <li>All values of the <code>pager</code> dict passed to the <code>_pager.html.jinja2</code> template are   now lists. Previously, only the values at keys <code>'before'</code> and <code>'after'</code> were   lists; now the values at keys <code>'previous'</code>, <code>'first'</code>, <code>'current'</code>, <code>'last'</code>,   and <code>'next'</code> are lists as well.</li> <li>The words <code>'blacklist'</code> and <code>'whitelist'</code> in variable names are replaced with   <code>'exclude'</code> and <code>'include'</code>.</li> <li>The <code>KERKO_RESULTS_ABSTRACT</code> configuration variable is replaced by two   variables, <code>KERKO_RESULTS_ABSTRACTS</code> (note the now plural form) and   <code>KERKO_RESULTS_ABSTRACTS_TOGGLER</code>.</li> <li>Citation download URLs now have the form   <code>{url_prefix}/{itemID}/export/{format}</code> for individual items (<code>'export'</code> has   been inserted), and <code>{url_prefix}/export/{format}/</code> for search result pages   (<code>'download'</code> has been replaced by <code>'export'</code>).</li> <li>The <code>Extractor</code> class' interface has changed, improving consistency and   separation of concerns:</li> <li>All arguments to <code>__init__()</code> must now be specified as keyword arguments.</li> <li>The <code>extract()</code> method no longer have a <code>document</code> argument, and the <code>spec</code>     argument is now the last one. The method now returns a value instead of     assigning it to the document.</li> <li>The new <code>extract_and_store()</code> method handles extraction, encoding, and     assignment to the document, assigning the value only when it is not <code>None</code>.</li> <li>The <code>AttachmentsExtractor</code> class has been renamed to   <code>StoredFileAttachmentsExtractor</code>.</li> <li><code>InCollectionExtractor</code> now extends collection membership to subcollections.   To preserve the previous behavior, set the <code>check_subcollections</code> parameter to   <code>False</code> when initializing the extractor.</li> </ul> <p>Possibly backwards incompatible changes (more or less internal API changes):</p> <ul> <li>The <code>search_results</code> variable passed to the <code>search.html.jinja2</code> template is   now an iterator of tuples, where the first element of each tuple is a result,   and the second element the URL of the result.</li> </ul>"},{"location":"changelog/#06-2020-06-15","title":"0.6 (2020-06-15)","text":"<p>Security fixes:</p> <ul> <li>Fix multiple vulnerabilities to XSS attacks. All previous versions of Kerko   were vulnerable, thus an upgrade is highly recommended.</li> </ul> <p>Backwards incompatible changes:</p> <ul> <li>Remove default value for the <code>KERKO_DATA_DIR</code> configuration variable. KerkoApp   users don't need to worry about this as KerkoApp takes care of it, but custom   apps that did not already set this variable now have to.</li> </ul> <p>Features:</p> <ul> <li>Open PDF documents in the browser's built-in PDF viewer (instead of opening   the browser's file download popup).</li> <li>Add buttons for opening documents directly from search result pages (these   replace the previous paperclip badges).</li> <li>Add button at the top of item pages for opening documents (makes the   availability of such documents much more obvious).</li> <li>Add the <code>KERKO_DOWNLOAD_ATTACHMENT_NEW_WINDOW</code> configuration variable to   control whether to open documents in a new window or in the same window.</li> <li>Display the date and time of the last successful synchronization from Zotero   at the bottom of search results.</li> </ul> <p>Bug fixes:</p> <ul> <li>Preserve newlines when displaying the value of the Extra field.</li> <li>Preserve newlines when displaying abstracts in search result pages.</li> <li>Fix filters missing on search pages that have no results.</li> <li>Avoid empty box in print media when there is no search criteria.</li> <li>Avoid empty box when the search index is missing.</li> <li>Fix pluralization in CLI time elapsed messages.</li> </ul> <p>Other changes:</p> <ul> <li>Refer to attachments as \"documents\" in the interface, and replace the   paperclip icon with a file icon.</li> <li>Remove CSRF token from search form. Token expiration can impede legitimate   users, and the token is unnecessary as the form does not change the   application's state.</li> <li>Add a proper message when none of the filters provided in the URL are   recognized.</li> <li>Improve documentation.</li> <li>Add INFO-level log message to report successful synchronization from Zotero.</li> <li>Add blocks in templates to facilitate theming.</li> </ul> <p>Possibly backwards incompatible changes (more or less internal API changes):</p> <ul> <li>Rename the <code>content_with_badges</code> template macro as <code>badges</code>, and leave it to   the caller to display content.</li> <li>Remove badges that are related to attachments.</li> </ul>"},{"location":"changelog/#05-2019-11-19","title":"0.5 (2019-11-19)","text":"<p>Warning: Upgrading from version 0.4 or earlier will require that you clean and re-sync your existing search index. Use the following commands:</p> <pre><code>flask kerko clean index\nflask kerko sync\n</code></pre> <p>Features:</p> <ul> <li>Add support for Zotero attachments.</li> <li>Allow configuration of badges on items. The 'attachment' badge is provided by   default, displaying an icon on items that have one or more attachments.</li> <li>Add help modal.</li> <li>Improve customizability:</li> <li>Add <code>KERKO_TEMPLATE_*</code> configuration variables for page template names.</li> <li>Use configurable, separate templates to render facets and badges (see the     <code>renderer</code> argument to <code>kerko.specs.FacetSpec</code>, <code>kerko.specs.BadgeSpec</code>).</li> <li>Add the <code>KERKO_RESULTS_FIELDS</code> configuration variable to specify which     fields to retrieve with search queries.</li> <li>Add building blocks for creating boolean facets based on collection membership   (new class <code>kerko.extractors.InCollectionExtractor</code>, new parameters for   <code>kerko.codecs.BooleanFacetCodec</code>).</li> </ul> <p>Bug fixes:</p> <ul> <li>Fix facets not ordered by weight on item page.</li> <li>Preserve newlines in abstract display.</li> <li>Fix incorrect use of bookmark link on item pages, set canonical link instead.</li> <li>Prevent text overflow in some browsers on citations containing long URLs.</li> </ul> <p>Other changes:</p> <ul> <li>Deprecate CLI command <code>kerko index</code> in favor of new command <code>kerko sync</code>.</li> <li>Change title of the \"Refine\" panel to \"Explore\".</li> <li>Change labels of the \"Print\" and \"Download\" buttons to \"Print this citation\"   and \"Download this citation\", to prevent any confusion with attachment   downloading.</li> <li>Show the facets in a more robust and accessible Bootstrap modal, on small   screens, instead of the home-built drawer.</li> <li>Use compact pagination widget on small screens.</li> <li>Tweak sizing, positioning, and spacing of various UI elements.</li> <li>Improve accessibility of various UI elements.</li> <li>Make citation stand out more in item page.</li> <li>Hide some elements and decorations in print media.</li> <li>Make search query more efficient on item page.</li> </ul> <p>Possibly backwards incompatible changes (more or less internal API changes):</p> <ul> <li>Force keyword arguments with <code>kerko.composer.Composer.__init__()</code>.</li> <li>Rename <code>kerko.composer.Composer.__init__()</code> arguments   <code>default_note_whitelist_re</code> as <code>default_child_whitelist_re</code>,   <code>default_note_blacklist_re</code> as <code>default_child_blacklist_re</code>.</li> <li>Rename method <code>kerko.views.item()</code> as <code>kerko.views.item_view()</code>.</li> <li>Rename template file <code>_facet.html.jinja2</code> as <code>_facets.html.jinja2</code>.</li> <li>Replace argument <code>checkboxes</code> in template macro <code>field()</code> with <code>add_link_icon</code>   and <code>remove_link_icon</code>.</li> </ul>"},{"location":"changelog/#04-2019-09-28","title":"0.4 (2019-09-28)","text":"<p>Features:</p> <ul> <li>Allow search term boosting in relevance score calculation, e.g. <code>faceted^2   search browsing^0.5</code>.</li> </ul> <p>Security fixes:</p> <ul> <li>Update minimum Werkzeug version to 0.15.3. See   CVE-2019-14806: \"Pallets   Werkzeug before 0.15.3, when used with Docker, has insufficient debugger PIN   randomness because Docker containers share the same machine id.\"</li> </ul> <p>Other changes:</p> <ul> <li>Update jQuery version to 3.4.1.</li> <li>Update French translations (translate boolean search operators).</li> <li>Improve search form validation and error display.</li> <li>Disable not-so-intuitive boolean search operators (<code>AndNot</code>, <code>AndMaybe</code>,   <code>Require</code> were unwanted but enabled by default by Whoosh's <code>OperatorsPlugin</code>).</li> <li>Improve documentation.</li> <li>Code cleanup.</li> </ul>"},{"location":"changelog/#03-2019-07-29","title":"0.3 (2019-07-29)","text":"<p>Features:</p> <ul> <li>Exporting: users may export individual citations as well as complete   bibliographies corresponding to search results. By default, download links are   provided for the RIS and BibTeX formats, but applications may be configured to   export any format supported by the Zotero API.</li> </ul> <p>Bug fixes:</p> <ul> <li>Fix bad alignment of field names in print mode.</li> <li>Remove warning when indexing an item with no authors   (#1).</li> </ul> <p>Other changes:</p> <ul> <li>Move print button to bottom of search pages (next to the new download   dropdown).</li> <li>Improve documentation.</li> <li>Compile message catalog before building sdist and wheel.</li> </ul> <p>Possibly backwards incompatible changes (more or less internal API changes):</p> <ul> <li>Method <code>kerko.composer.Composer.get_ordered_specs()</code> replaces   <code>get_ordered_scopes()</code>, <code>get_ordered_facets()</code> and <code>get_ordered_sorts()</code>.</li> </ul>"},{"location":"changelog/#03alpha1-2019-07-17","title":"0.3alpha1 (2019-07-17)","text":"<ul> <li>Fix broken links in documentation.</li> </ul>"},{"location":"changelog/#03alpha0-2019-07-16","title":"0.3alpha0 (2019-07-16)","text":"<ul> <li>First PyPI release.</li> </ul>"},{"location":"config-basics/","title":"Configuration basics","text":"<p>In this section, we will assume that you are using Kerko through KerkoApp. Some elements may not apply if you have integrated Kerko into your own custom Flask application (see Configuration in custom applications).</p>"},{"location":"config-basics/#parameter-styles","title":"Parameter styles","text":"<p>When looking at Kerko configuration options, you will quickly notice two styles of parameter names, uppercase names and lowercase names.</p> <p>Uppercase names, such as <code>SECRET_KEY</code>, <code>ZOTERO_LIBRARY_ID</code>, <code>DATA_PATH</code>, <code>BABEL_DEFAULT_LOCALE</code>, follow the usual convention for environment variables. Most Flask and Flask extensions parameter names follow this convention. Some Kerko parameters have uppercase names too, but only those parameters that may usefully be set as environment variables. Internally, those parameters are stored into a flat Python dictionary.</p> <p>Most of Kerko parameters use lowercase names. They are also organized into a hierarchy, and are usually referenced using dot-separated paths. Examples are: <code>kerko.features.results_abstracts</code>, <code>kerko.meta.title</code>, <code>kerko.facets.item_type.enabled</code>. Internally, those parameters are stored into nested Python dictionaries.</p> <p>Documentation convention</p> <p>In this manual, we will generally refer to a hierarchical parameter using its full dot-separated path, for example <code>kerko.meta.title</code>, except when context makes repeating the full path redundant.</p>"},{"location":"config-basics/#configuration-methods","title":"Configuration methods","text":"<p>KerkoApp provides two ways to set configuration parameters:</p> <ol> <li>As parameters in one or more TOML files.</li> <li>As environment variables.</li> </ol> <p>The above list is in ascending order of precedence. This means that a given parameter set in a TOML file can be overridden by an environment variable.</p> <p>We do not recommend configuring the same parameter in multiple places, as that might confuse systems administrators, but a layered approach is useful in implementing the Twelve-factor App methodology.</p> <p>TOML files are the preferred and most convenient way of configuring KerkoApp. Environment variables, however, are still supported, as some parameters cannot be set in TOML files, such as <code>FLASK_APP</code> and <code>KERKOAPP_CONFIG_FILES</code>.</p>"},{"location":"config-basics/#toml-files","title":"TOML files","text":"<p>The TOML syntax allows organizing parameters under headers to avoid repetition and to make the file more readable. Therefore, two following two examples are equivalent ways of setting the <code>kerko.meta.title</code> parameter:</p> TOML example 1<pre><code>kerko.meta.title = \"My Awesome Bibliography\"\n</code></pre> TOML example 2<pre><code>[kerko.meta]\ntitle = \"My Awesome Bibliography\"\n</code></pre> <p>Note that if headers are used in a TOML file, any top-level parameter must be set above the first header:</p> Correct TOML example<pre><code>ZOTERO_LIBRARY_ID = \"123456\"\n\n[kerko.meta]\ntitle = \"My Awesome Bibliography\"\n</code></pre> Incorrect TOML example<pre><code>[kerko.meta]\ntitle = \"My Awesome Bibliography\"\n\nZOTERO_LIBRARY_ID = \"123456\"\n</code></pre> <p>By default, KerkoApp will look for a series of TOML files:</p> <ol> <li><code>config.toml</code></li> <li><code>instance.toml</code></li> <li><code>.secrets.toml</code></li> </ol> <p>For each of those, KerkoApp first looks for the file into the current working directory. If it does not find it there, it searches by traversing directories upwards until it finds the file or reaches the root directory. At this point, if the file is still not found, the same scanning process is reapplied, but this time starting from the instance path. After that, whether the file was found or not, KerkoApp continues with the next filename in the list.</p> <p>The files are loaded in the specified order. The parameters from each file get merged into the previously known configuration. If a given parameter was already set, its value is overwritten by the one from the later file.</p> <p>This approach allows a layered configuration where:</p> <ul> <li><code>config.toml</code> contains general (public) parameters. It is safe (and wise) to   manage this file in a code repository.</li> <li><code>instance.toml</code> contains server-specific parameters such as those that might   refer to paths or systems that only exist on the server. This file is usually   not put into a code repository.</li> <li><code>.secrets.toml</code> contains secrets (private parameters) that ought to be known   only to the server, such as API keys. This file should never be added to a   code repository.</li> </ul> <p>You do not have to use all three files. One might, for example, use just <code>config.toml</code> and <code>.secrets.toml</code>, and not create <code>instance.toml</code>.</p> <p>You may replace the default list of TOML file paths by setting the <code>KERKOAPP_CONFIG_FILES</code> environment variable.</p> <p>In the example below, the default list of TOML files is replaced by a list of two file paths, one relative and the other absolute:</p> POSIXWindows <pre><code>KERKOAPP_CONFIG_FILES=\"first_config.toml;/absolute/path/to/second_config.toml\"\n</code></pre> <pre><code>KERKOAPP_CONFIG_FILES=\"first_config.toml;C:\\absolute\\path\\to\\second_config.toml\"\n</code></pre>"},{"location":"config-basics/#environment-variables","title":"Environment variables","text":"<p>KerkoApp requires environment variable names to be prefixed with <code>KERKOAPP_</code>. The <code>SECRET_KEY</code> parameter, for example, becomes <code>KERKOAPP_SECRET_KEY</code> when specified as an environment variable.</p> <p>For hierarchical parameters, each dot separator (<code>.</code>) must be replaced by two underscore characters (<code>__</code>). The <code>kerko.meta.title</code> parameter, for example, becomes <code>KERKOAPP_kerko__meta__title</code> when specified as an environment variable. Such conversion is not necessary in TOML files.</p> <p>Note that Windows does not allow lowercase environment variable names. Consequently, Windows users have no choice but to set lowercase parameters in TOML files.</p> <p>Environment variables may be set from various locations, in the following order (refer to the Flask documentation for more details):</p> <ol> <li>As entries in a <code>.flaskenv</code> file.</li> <li>As entries in a <code>.env</code> file.</li> <li>As entries in a file specified by the <code>--env-file</code> command line option.</li> <li>As environment variables.</li> </ol> <p>The above list is in ascending order of precedence. This means that a given parameter set earlier can be overridden later as values get loaded. Files are located by scanning directories upwards from the directory you call flask from.</p>"},{"location":"config-basics/#configuration-in-custom-applications","title":"Configuration in custom applications","text":"<p>If you are using a custom Flask application instead of KerkoApp, some of the present documentation may not fully apply to you. For example:</p> <ul> <li>TOML files might not be supported at all.</li> <li>Environment variables might require a prefix other than <code>KERKOAPP_</code>, or no   prefix at all.</li> </ul> <p>In a custom application, hierarchical parameters may be set in Python using the API provided by Kerko, as in the following example:</p> Setting a configuration parameter in Python<pre><code>from kerko.config_helpers import config_set\nconfig_set(app.config, \"kerko.meta.title\", \"My Awesome Bibliography\")\n</code></pre> <p>Such assignments must be done during the initialization process. The application cannot change a setting while responding to a request.</p>"},{"location":"config-basics/#viewing-the-configuration","title":"Viewing the configuration","text":"<p>With configuration parameters potentially taking values from different sources (default values, configuration files, environment variables), you may sometimes want to verify the actual values taken by each parameter.</p> <p>The following command will show the configuration parameters of the application and their values:</p> <pre><code>flask kerko config\n</code></pre>"},{"location":"config-guides/","title":"Configuration guides","text":"<p>This sections provides guidance on configuring specific aspects of Kerko.</p>"},{"location":"config-guides/#defining-custom-facets-based-on-zotero-collections","title":"Defining custom facets based on Zotero collections","text":"<p>Zotero collections can be mapped to custom facets in Kerko. With this scheme, a collection in the Zotero library represents a facet, and its subcollections correspond to values (or user-selectable filters) within the facet. Figure 1 below illustrates such mapping, taken from the demo library and its corresponding demo site.</p> <p></p> Figure 1. Side-by-side comparison between the structure of collections in a Zotero library and the resulting faceted browsing interface in Kerko. <p>For such mapping to work, the following conditions must be met:</p> <ul> <li>The collection that is to be mapped to a facet must be a top-level   collection. In other words, it must be directly under the root of your   Zotero library.</li> <li>At least one subcollection must be present within the chosen top-level   collection, and that subcollection (or one of its own subcollections) must   contain at least one item.</li> </ul> <p>Once your Zotero library it set up to meet those conditions, you may configure the facets. For the example in Figure 1, the configuration looks like this:</p> <pre><code>[kerko.facets.topic]\nenabled = true\ntype = \"collection\"\ncollection_key = \"KY3BNA6T\"\nfilter_key = \"topic\"\ntitle = \"Topic\"\nweight = 110\ninitial_limit = 5\ninitial_limit_leeway = 2\n\n[kerko.facets.field_of_study]\nenabled = true\ntype = \"collection\"\ncollection_key = \"7H2Q7L6I\"\nfilter_key = \"field-of-study\"\ntitle = \"Field of study\"\nweight = 120\ninitial_limit = 5\ninitial_limit_leeway = 2\n\n[kerko.facets.contribution]\nenabled = true\ntype = \"collection\"\ncollection_key = \"JFQRH4X2\"\nfilter_key = \"contribution\"\ntitle = \"Contribution\"\nweight = 130\ninitial_limit = 5\ninitial_limit_leeway = 2\n</code></pre> <p>For details on each parameter, please refer to the parameters documentation. However, we can highlight some elements:</p> <ul> <li><code>collection_key</code> is the key assigned by Zotero to identify the collection. An   easy way to find this key is to visit your library using Zotero's web   interface. Click the collection, and check its URL in your browser's address   bar. In our example, the URL of the \"Topic\" collection is   https://www.zotero.org/groups/2348869/kerko_demo/collections/KY3BNA6T,   hence the use of <code>\"KY3BNA6T\"</code> as the collection key.</li> <li><code>filter_key</code> tells Kerko the key to use in URLs when a user of your Kerko site   selects a filter within the facet. In our example, for the \"Topic\" facet we   chose to set this parameter to <code>\"topic\"</code> and, consequently, the search URL   will look like   https://demo.kerko.whiskyechobravo.com/bibliography/?topic=Z8LT6QZG.2ZGZH2E2.</li> <li><code>title</code> is the heading that Kerko will show for the facet. If desired, you may   choose a title that is different from the collection's name in Zotero.</li> <li><code>weight</code> determines the relative position of the facet. Small numbers (low   weights) rise above large ones (heavier weights). This explains why, in our   example, Kerko displays \"Topic\" (weighting 110) above \"Field of study\" (120)   and \"Contribution\" (130).</li> </ul> <p>Other things to know:</p> <ul> <li> <p>After adding a new facet, you must clean and re-sync the search index. Please   check the documentation on synchronization, but in short   you have to use the following commands:</p> <pre><code>flask kerko clean index\nflask kerko sync index\n</code></pre> </li> <li> <p>Kerko allows a facet to have any number of hierarchical sublevels (nested   subcollections).</p> </li> <li>Any new subcollection will automatically appear under the facet after a sync,   if it (or one of its own subcollections) contains at least one item.   Collection structures that contain no items will not show up in Kerko.</li> <li>An item may belong to multiple collections in Zotero. Take advantage of that   capability when designing your faceted classification. Ideally, facets   complement each other in describing different perspectives on the same   objects. If you are unfamiliar with faceted classification, we highly   recommend this paper by William Denton (2003): How to Make a Faceted   Classification and Put It On the   Web.</li> <li>In Zotero, an item only needs to be assigned to the hierarchical level that is   most relevant for it. You do not need to also add the item to the parent   collections. The reason is that in Kerko a given filter automatically includes   the items from its corresponding subcollection and all of its subcollections.</li> <li>You do not have to expose all of your Zotero library's top-level collections   to Kerko. Kerko will only use those that are given in the configuration, and   ignore the others. Note, however, that unless you use item   inclusion or   exclusion parameters, items will be   visible in your Kerko site regardless of the collections they belong to.</li> </ul> <p>Phew! We think that this is simpler to setup in practice than it looks in writing. Hopefully you will agree.</p>"},{"location":"config-guides/#creating-custom-content-pages-based-on-zotero-standalone-notes","title":"Creating custom content pages based on Zotero standalone notes","text":"<p>If you wish to provide informational pages along with your bibliography, you can add standalone notes to your Zotero library, and configure Kerko to provide pages whose content will come from those notes.</p> <p>Say you want to provide \"About\" and \"Contact Us\" pages with simple text content, you could implement them by following these steps:</p> <ul> <li>Create a standalone note in Zotero. In the Zotero note editor, enter the   desired text for your \"About\" page.</li> <li>Create another standalone note in Zotero. In the Zotero note editor, enter the   desired text for your \"Contact Us\" page.</li> <li>For each note, find its item ID. One way to find it is to visit your library   using Zotero's web interface. Click the note, and check its URL in your   browser's address bar. It should look a bit like   https://www.zotero.org/groups/2348869/kerko_demo/items/Y48RBWDB/item-list.   In this example, <code>\"Y48RBWDB\"</code> is the item ID.</li> <li> <p>Define the \"About\" and \"Contact Us\" pages by adding the following snippet to   your Kerko configuration:</p> <pre><code>[kerko.pages.about]\npath = \"/about\"\nitem_id = \"Y48RBWDB\"\ntitle = \"About\"\n\n[kerko.pages.contact_us]\npath = \"/contact\"\nitem_id = \"REG3CL25\"\ntitle = \"Contact Us\"\n</code></pre> <p>... where:</p> <ul> <li><code>path</code> is the desired URL path for the page;</li> <li><code>item_id</code> is the note's item ID (as found earlier);</li> <li><code>title</code> is the desired title for the page in the Kerko site.</li> </ul> <p>For more details on each parameter, please refer to the parameters documentation.</p> </li> <li> <p>Then, you will probably want the navigation bar to provide links to your   pages. The following configuration code defines a navigation bar with three   links \u2014 a link to the bibliography, and links to the \"About\" and \"Contact Us\"   pages:</p> <pre><code>[[kerko.link_groups.navbar]]\ntype = \"endpoint\"\nendpoint = \"kerko.search\"\ntext = \"Bibliography\"\n\n[[kerko.link_groups.navbar]]\ntype = \"page\"\npage = \"about\"\ntext = \"About\"\n\n[[kerko.link_groups.navbar]]\ntype = \"page\"\npage = \"contact_us\"\ntext = \"Contact Us\"\n</code></pre> <p>... where:</p> <ul> <li>the <code>type</code> parameter indicates the type of link (<code>\"endpoint\"</code> indicates a   core Kerko link, while <code>\"page\"</code> indicates a link to a page defined under   <code>kerko.pages.*</code>);</li> <li>the <code>page</code> parameter specifies the target of the link, e.g., the unique   key of the page (which replaces the <code>*</code> in the <code>kerko.pages.*</code> header);</li> <li>the <code>text</code> parameter provides the link's text to show in the navigation   bar.</li> </ul> <p>Navigation bar links will be displayed in the order they appear in the configuration file.</p> <p>For more details on this configuration section, please refer to the parameters documentation</p> </li> <li> <p>Make sure Kerko's database is up-to-date with your new note by running the   following command:</p> <pre><code>flask kerko sync\n</code></pre> </li> <li> <p>Restart your Kerko application to load the configuration changes. If all goes   well, you will have new \"About\" and \"Contact Us\" pages accessible from the   navigation bar.</p> </li> </ul> <p>Please note that Kerko does not restructure the HTML that Zotero generates for notes. If you use headings in your notes, we recommend that you start with the \"Heading 2\" heading level, because \"Heading 1\" should be reserved to Kerko (for the page title).</p> <p>Kerko is not, and never will be, a web content management system. Its sole purpose is to provide a nice interface for a Zotero library. Thus, Kerko content pages are just a very rudimentary way of providing simple informational content along with the library. For more advanced content needs, you might have to consider integrating Kerko into a custom Flask application backed with proper content editing features.</p>"},{"location":"config-guides/#ensuring-full-text-indexing-of-your-attachments-in-zotero","title":"Ensuring full-text indexing of your attachments in Zotero","text":"<p>Kerko's full-text indexing relies on text content extracted from attachments by Zotero. Consequently, for Kerko's full-text search to work, you must make sure that full-text indexing works in Zotero first; see Zotero's documentation on full-text indexing.</p> <p>Individual attachments in Zotero can be indexed, partially indexed, or unindexed. Various conditions may cause an attachment to be partially indexed or unindexed, e.g., file is large, has not been processed yet, or does not contain text.</p> <p>Zotero shows the indexing status in the attachment's right pane. If it shows \"Indexed: Yes\", all is good. If it shows \"Indexed: No\" or \"Indexed: Partial\", then clicking the \"Reindex Item\" button (next to the indexing status) should ensure that the attachment gets fully indexed, that is if the file actually contains text. If there is no \"Reindex Item\" button, it probably means that Zotero does not support that file type for full-text indexing (at the moment, it only supports PDF and plain text files).</p> <p>It can be tedious to go through hundreds of attachments just to find out whether they are indexed or not. To make things easier, you could create a saved search in your Zotero library to get an always up-to-date list of unindexed PDFs. Use the following search conditions:</p> <ul> <li>Match all of the following:<ul> <li>Attachment File Type \u2014 is \u2014 PDF</li> <li>Attachment Content \u2014 does not contain \u2014 . (that's a period; also   select RegExp in the small dropdown list, as that will make the period   match any character)</li> </ul> </li> </ul> <p>This search might return a long list of unindexed attachments. To reindex them all at once, you may select them, then right-click to get the contextual menu, and select \"Reindex items\". It may require some time to update your library on zotero.org. Note that documents that have no text content, as well as missing documents, will still be considered as unindexed and appear in the results of the saved search.</p> <p>Controlling the indexing status will not only improve full-text search on your Kerko site, but also full-text search from within Zotero!</p>"},{"location":"config-guides/#providing-cites-and-cited-by-relations","title":"Providing Cites and Cited by relations","text":"<p>Zotero allows one to link items together through its Related field. However, such relations are not typed nor directed, making it impossible (1) to indicate the nature of the relation, or (2) to distinguish which of two related items is the citing entity, and which is the one being cited. Consequently, Kerko has its own method for setting up those relations.</p> <p>To establish Cites relations in your Zotero library, you must follow the procedure below:</p> <ul> <li>Install the Zutilo plugin for Zotero. Once it is installed, go to Tools &gt;   Zutilo Preferences... in Zotero. Then, under Zotero item menu, select   Zotero context menu next to the Copy Zotero URIs menu item. This   configuration step only needs to be done once.</li> <li>Select one or more items from your library that you wish to show as cited by   another. Right-click on one of the selected items to open the context menu,   and select Copy Zotero URIs from that menu. This copies the references of   the selected items items to the clipboard.</li> <li>Right-click the item from your library that cites the items. Select Add Note   from that item's context menu to add a child note.</li> <li>In the note editor, paste the content of the clipboard. The note should then   contain a series of URIs looking like   <code>https://www.zotero.org/groups/9999999/items/ABCDEFGH</code> or   <code>https://www.zotero.org/users/9999999/items/ABCDEFGH</code>.</li> <li>At the bottom of the note editor, click into the Tags field and type   <code>_cites</code>. That tag that will tell Kerko that this particular note is special,   that it contains relations.</li> </ul> <p>At the next synchronization, Kerko will retrieve the references found in notes tagged with <code>_cites</code>. Afterwards, proper hyperlinked citations will appear in the Cites and Cited by sections of the related bibliographic records.</p> <p>Remarks:</p> <ul> <li>Enter only the Cites relations. The reverse Cited by relations will be   inferred automatically.</li> <li>You may only relate items that belong to the same Zotero library.</li> <li>You may use Zotero Item Selects (URIs starting with <code>zotero://select/</code>) in the   notes, if you prefer those to Zotero URIs.</li> <li>If entered as plain text, URIs must be separated by one or more whitespace   character(s). Alternatively, URIs may be entered in HTML links, i.e., in the   <code>href</code> attribute of <code>&lt;a&gt;</code> elements.</li> <li>Hopefully, Zotero will provide nicer ways for handling relation   types in the future.   In the meantime, using child notes is how Kerko handles it. If relation types   are important to you, consider describing your use case in the Zotero   forums.</li> <li>Custom Kerko applications can provide more types of relations, if desired, in   addition to Cites and Cited by.</li> </ul>"},{"location":"config-params/","title":"Configuration parameters","text":"<p>This section describes most configuration parameters available to Kerko and KerkoApp.</p> <p>Unless indicated otherwise, all parameters are optional and will take a default value if omitted from your configuration.</p> <p>Note</p> <p>Flask and Flask extensions loaded by the application may provide additional configuration parameters that are not described in this manual. To find those, please refer to the documentation of the relevant package.</p> <p>Changing the Kerko configuration can be disruptive</p> <p>Making any change to a Kerko configuration file requires that you at least restart the application afterwards for the change to become effective.</p> <p>Moreover, some parameters have an effect on the structure of the cache or the search index that Kerko depends on. Changing this kind of parameter may require that you rebuild either. Refer to the documentation of the parameter to check if specific actions need to be taken after a change.</p> <p>Prefix your environment variables</p> <p>KerkoApp users must prefix parameter names with <code>KERKOAPP_</code> when configuring them as environment variables. However, that prefix should be omitted when the same parameter is set in a TOML file. See environment variables for details.</p> <p>Be a minimalist, only set a parameter when necessary</p> <p>If a parameter's default value works for you, just omit that parameter from your configuration file. Your configuration file will be much smaller and easier to read, and you will have less things to check when eventually upgrading Kerko.</p>"},{"location":"config-params/#babel_default_locale","title":"<code>BABEL_DEFAULT_LOCALE</code>","text":"<p>The default language of the user interface.</p> <p>Type: String  Default value: <code>\"en\"</code></p>"},{"location":"config-params/#babel_default_timezone","title":"<code>BABEL_DEFAULT_TIMEZONE</code>","text":"<p>The timezone to use for user facing times. Any timezone name supported by the pytz package should work.</p> <p>Type: String  Default value: <code>\"UTC\"</code></p>"},{"location":"config-params/#config_files","title":"<code>CONFIG_FILES</code>","text":"<p>Specifies where to look for one or more TOML configuration files. The value must be a semicolon-separated list of file paths.</p> <p>The files are loaded in the specified order. The parameters from each file get merged into the previously known configuration. If a given parameter was already set, its value is overwritten by the one from the later file.</p> <p>Paths may be absolute or relative. Relative paths are resolved from the current working directory. If a specified file is not found there, it is searched by traversing the directories upwards. If the root directory is reached and the file is still not found, then the same search method is reapplied, but this time starting from the <code>INSTANCE_PATH</code>.</p> <p>Type: String  Default value: <code>\"config.toml;instance.toml;.secrets.toml\"</code></p> <p>Environment variable only</p> <p>This parameter is specific to KerkoApp and cannot be set in a TOML file. It can only be set as an environment variable, therefore it should actually be referenced as <code>KERKOAPP_CONFIG_FILES</code>. See environment variables for details.</p>"},{"location":"config-params/#data_path","title":"<code>DATA_PATH</code>","text":"<p>The data path specifies a directory where Kerko may store its cache, search index, and file attachments. This may be provided as an absolute path or as a relative path. If a relative path is given, it will be relative to <code>INSTANCE_PATH</code>.</p> <p>Type: String  Default value: <code>\"kerko\"</code></p>"},{"location":"config-params/#instance_path","title":"<code>INSTANCE_PATH</code>","text":"<p>The instance path specifies a directory where the application may store data and configuration files.</p> <p>Type: String  Default value: Determined by Flask. In practice, the default for KerkoApp users is a directory named <code>instance</code> located at the same level as the <code>wsgi.py</code> file. You may set <code>INSTANCE_PATH</code> to a different directory, which you must specify as an absolute path.</p> <p>Environment variable only</p> <p>This parameter is specific to KerkoApp and cannot be set in a TOML file. It can only be set as an environment variable, therefore it should actually be referenced as <code>KERKOAPP_INSTANCE_PATH</code>. See environment variables for details.</p>"},{"location":"config-params/#logging_address","title":"<code>LOGGING_ADDRESS</code>","text":"<p>Address to send log messages to. Used only if <code>LOGGING_HANDLER</code> is set to <code>\"syslog\"</code>.</p> <p>Type: String  Default value: <code>\"/dev/log\"</code></p>"},{"location":"config-params/#logging_format","title":"<code>LOGGING_FORMAT</code>","text":"<p>Log message format string, with %-style placeholders. Refer to the Python logging documentation for allowed attributes.</p> <p>Type: String  Default value: <code>\"[%(asctime)s] %(levelname)s in %(module)s: %(message)s\"</code></p>"},{"location":"config-params/#logging_handler","title":"<code>LOGGING_HANDLER</code>","text":"<p>Logging handler to use. At this time, the sole allowed value is <code>\"syslog\"</code>. If no value is set, the default handler will write to the default stream (usually <code>sys.stderr</code>).</p> <p>Type: String</p>"},{"location":"config-params/#logging_level","title":"<code>LOGGING_LEVEL</code>","text":"<p>Severity of events to log. Allowed values are <code>\"DEBUG\"</code>, <code>\"INFO\"</code>, <code>\"WARNING\"</code>, <code>\"ERROR\"</code>, and <code>\"CRITICAL\"</code>.</p> <p>Type: String  Default value: <code>\"DEBUG\"</code> if the application is running in debug mode, or <code>\"WARNING\"</code> otherwise.</p>"},{"location":"config-params/#secret_key","title":"<code>SECRET_KEY</code>","text":"<p>This parameter is required for generating secure tokens in web forms. It should have a hard to guess value, and should really remain secret.</p> <p>This parameter is required and has no default value.</p> <p>Type: String</p>"},{"location":"config-params/#zotero_api_key","title":"<code>ZOTERO_API_KEY</code>","text":"<p>This parameter specifies your Zotero API key, as created on zotero.org.</p> <p>Kerko does not need to write to your library. Thus, we recommend that your API key be read-only, and that it does not grant any more access to your Zotero data than strictly necessary.</p> <p>On zotero.org, the API key creation options vary on whether you want to connect Kerko to a personal library or to a group library:</p> Personal libraryGroup library <p>Make sure to check Allow library access, as well as Allow notes access, unless you are certain you won't need any Kerko feature that relies on notes. If you are unsure at this point, we recommend that you allow notes access, otherwise some features might not work, and when that happens you might not remember that it is the API key that is blocking notes access. You can always edit the API key later.</p> <p>We recommend that you use Per group permissions so that access is strictly restricted to the chosen group. Make sure that Read Only is selected for that group. This will grant read-only access to all items of that group, including notes.</p> <p>This parameter is required and has no default value.</p> <p>Type: String</p>"},{"location":"config-params/#zotero_library_id","title":"<code>ZOTERO_LIBRARY_ID</code>","text":"<p>The identifier of the Zotero library to get data from.</p> <p>Finding your library ID:</p> Personal libraryGroup library <p>For a personal library, the value is your userID, as found on zotero.org (you must be logged-in).</p> <p>For a group library this value is the groupID of the library, as found in the URL of the library (e.g., the groupID of the library at <code>https://www.zotero.org/groups/2348869/kerko_demo</code> is <code>\"2348869\"</code>).</p> <p>This parameter is required and has no default value.</p> <p>Type: String</p>"},{"location":"config-params/#zotero_library_type","title":"<code>ZOTERO_LIBRARY_TYPE</code>","text":"<p>The type of library to get data from, either <code>\"user\"</code> for a personal library, or <code>\"group\"</code> for a group library.</p> <p>This parameter is required and has no default value.</p> <p>Type: String</p>"},{"location":"config-params/#kerkobib_formats","title":"<code>kerko.bib_formats.*.</code>","text":"<p>Bibliographic record download formats, where <code>*</code> is a format key.</p> <p>The default formats are:</p> <ul> <li><code>bibtex</code></li> <li><code>ris</code></li> </ul> <p>The configuration system does not allow adding new formats.</p>"},{"location":"config-params/#enabled","title":"<code>enabled</code>","text":"<p>Enable the format. If this is set to <code>false</code>, the format will not be available through any download link.</p> <p>Type: Boolean</p> <p>Modifies the cache and the search index</p> <p>Changing this parameter from <code>false</code> to <code>true</code> will require that you run the <code>sync cache --full</code> and <code>sync index</code> commands. See synchronization commands for details.</p>"},{"location":"config-params/#extension","title":"<code>extension</code>","text":"<p>File extension of the downloadable file.</p> <p>Type: String</p>"},{"location":"config-params/#help_text","title":"<code>help_text</code>","text":"<p>Description of the format, to show in the help window.</p> <p>Type: String</p>"},{"location":"config-params/#label","title":"<code>label</code>","text":"<p>Label to use in the format selector.</p> <p>Type: String</p>"},{"location":"config-params/#mime_type","title":"<code>mime_type</code>","text":"<p>MIME type of the downloadable format.</p> <p>Type: String</p>"},{"location":"config-params/#weight","title":"<code>weight</code>","text":"<p>Relative position of the format in lists. Formats with low weights (small numbers) rise above heavier ones (large numbers).</p> <p>Type: Integer</p>"},{"location":"config-params/#kerkobreadcrumb","title":"<code>kerko.breadcrumb.</code>","text":"<p>A breadcrumb is a navigational aid that displays the location of the current page in relation to the structure of a website.</p> <p>If enabled, the breadcrumb works in relation with the <code>kerko.link_groups.breadcrumb_base</code> parameter, which defines the base (starting links) of the breadcrumb trail, which Kerko dynamically completes with one or more links based on the current location within Kerko.</p>"},{"location":"config-params/#enabled_1","title":"<code>enabled</code>","text":"<p>Enable the breadcrumb.</p> <p>Type: Boolean  Default value: <code>true</code></p>"},{"location":"config-params/#include_current","title":"<code>include_current</code>","text":"<p>Include the current page at the end of the breadcrumb trail. If set to <code>false</code>, the breadcrumb trail will end with the parent page instead of the current page.</p> <p>Type: Boolean  Default value: <code>true</code></p>"},{"location":"config-params/#text_max_length","title":"<code>text_max_length</code>","text":"<p>Maximum length for a breadcrumb item's text (in number of characters). If text is to be truncated in the middle of a word, the whole word is discarded instead. Truncated text is appended with an ellipsis sign (\"...\").</p> <p>If set to <code>0</code>, no truncation will be applied.</p> <p>Type: Integer  Default value: <code>50</code></p>"},{"location":"config-params/#text_max_length_leeway","title":"<code>text_max_length_leeway</code>","text":"<p>If the length of a breadcrumb item's text only exceeds <code>kerko.breadcrumb.text_max_length</code> by this tolerance margin or less (in number of characters), the text will not be truncated.</p> <p>This parameter has no effect if <code>text_max_length</code> is set to <code>0</code> (no truncation).</p> <p>Type: Integer  Default value: <code>10</code></p>"},{"location":"config-params/#kerkofacets","title":"<code>kerko.facets.*.</code>","text":"<p>Facets to provide in the search interface, where <code>*</code> is a facet key. The facet key is used internally by Kerko to identify the facet.</p> <p>The default facets are:</p> <ul> <li><code>item_type</code> (item types facet, enabled by default)</li> <li><code>language</code> (item languages facet, disabled by default)</li> <li><code>link</code> (items with links facet, disabled by default)</li> <li><code>tag</code> (item tags facet, enabled by default)</li> <li><code>year</code> (item years facet, enabled by default)</li> </ul> <p>You may define additional facets. See Defining custom facets based on Zotero collections.</p> <p>Modifies the search index</p> <p>Most of the <code>kerko.facets.*</code> parameters require that you run the <code>clean index</code> and <code>sync index</code> commands after you have changed them. See synchronization commands for details.</p>"},{"location":"config-params/#collection_key","title":"<code>collection_key</code>","text":"<p>Key of the Zotero collection to map the facet to. This must refer to a top-level collection containing at least one hierarchical level of subcollections. Each subcollection will be mapped to a filter under the facet, if it contains at least one item that is not excluded through the <code>kerko.zotero.item_include_re</code> or <code>kerko.zotero.item_exclude_re</code> parameters.</p> <p>This parameter has no default value and is required for facets whose <code>type</code> parameter is set to <code>\"collection\"</code>.</p> <p>Type: String </p>"},{"location":"config-params/#enabled_2","title":"<code>enabled</code>","text":"<p>Enable the facet.</p> <p>Type: Boolean  Default value: depends on which facet you are looking at.</p>"},{"location":"config-params/#filter_key","title":"<code>filter_key</code>","text":"<p>Key to use in URLs when filtering with the facet.</p> <p>Type: String  Default value: depends on which facet you are looking at.</p>"},{"location":"config-params/#initial_limit","title":"<code>initial_limit</code>","text":"<p>Maximum number of filters to show by default under the facet. Excess filters will be shown if the user clicks a \"view more\" button. A value of <code>0</code> means no limit.</p> <p>Type: Integer  Default value: depends on which facet you are looking at.</p>"},{"location":"config-params/#initial_limit_leeway","title":"<code>initial_limit_leeway</code>","text":"<p>If the number of filters under the facet exceeds <code>initial_limit</code> by this tolerance margin or less, all filters will be shown. A value of <code>0</code> means no tolerance margin.</p> <p>Type: Integer  Default value: depends on which facet you are looking at.</p>"},{"location":"config-params/#item_view","title":"<code>item_view</code>","text":"<p>Show the facet on item view pages.</p> <p>Type: Boolean  Default value: depends on which facet you are looking at.</p>"},{"location":"config-params/#sort_by","title":"<code>sort_by</code>","text":"<p>List of criteria used for sorting the filters under the facet. Allowed values in this list are <code>\"count\"</code> and <code>\"label\"</code>.</p> <p>Type: Array of strings  Default value: depends on which facet you are looking at.</p>"},{"location":"config-params/#sort_reverse","title":"<code>sort_reverse</code>","text":"<p>Reverse the sort order of the filters under the facet.</p> <p>Type: Boolean  Default value: depends on which facet you are looking at.</p>"},{"location":"config-params/#title","title":"<code>title</code>","text":"<p>Heading of the facet.</p> <p>Type: String  Default value: depends on which facet you are looking at.</p>"},{"location":"config-params/#type","title":"<code>type</code>","text":"<p>Type of facet. Determines the data source of the facet.</p> <p>Allowed values are:</p> <ul> <li><code>\"collection\"</code>: Use a Zotero collection as source.</li> <li><code>\"item_type\"</code>: Use the item type as source.</li> <li><code>\"language\"</code>: Use item Language field as source.</li> <li><code>\"link\"</code>: Use item URL field as source.</li> <li><code>\"tag\"</code>: Use Zotero tags as source.</li> <li><code>\"year\"</code>: Use the item year field as source.</li> </ul> <p>This parameter is required and has no default value.</p> <p>Type: String</p>"},{"location":"config-params/#weight_1","title":"<code>weight</code>","text":"<p>Relative position of the facet in lists. Facets with low weights (small numbers) rise above heavier ones (large numbers).</p> <p>Type: Integer  Default value: depends on which facet you are looking at.</p>"},{"location":"config-params/#kerkofacetslanguage","title":"<code>kerko.facets.language.</code>","text":"<p>The parameters in this section only apply to the <code>language</code> facet.</p> <p>Source values for the language facet are extracted from the Language field of Zotero items.</p>"},{"location":"config-params/#allow_invalid","title":"<code>allow_invalid</code>","text":"<p>Allow values that are not found in the pycountry language database.</p> <p>This parameter has an effect only if <code>normalize</code> is set to <code>true</code>.</p> <p>If this parameter is set to <code>true</code>, non-standard or badly entered language names will be allowed to appear in the language facet. You may find that you have to clean your data in Zotero if you wish to make the facet usable.</p> <p>If this parameter is set to <code>false</code>, non-standard or badly entered language names will be omitted from the language facet. The facet will only show recognized languages but may give an incomplete picture of all the languages present in your library.</p> <p>Type: Boolean  Default value: <code>true</code></p>"},{"location":"config-params/#locale","title":"<code>locale</code>","text":"<p>The locale to use when displaying language names in the language facet. Translations are provided by pycountry.</p> <p>This parameter has an effect only if <code>normalize</code> is set to <code>true</code>.</p> <p>Type: String  Default value: <code>\"en\"</code></p>"},{"location":"config-params/#normalize","title":"<code>normalize</code>","text":"<p>Normalize language names using the pycountry language database.</p> <p>If this parameter is set to <code>true</code>, slight inconsistencies in your data can be attenuated, preventing unwanted duplicates in the facet. For example, values such as <code>fr</code>, <code>FR</code>, <code>fra</code>, <code>Fra</code>, <code>fre</code>, <code>fr-FR</code>, <code>fr-fr</code>, <code>fr-CA</code>, or <code>French</code> will all fall under a single <code>French</code> term in the facet. The normalization process is case insensitive, ignores country or area codes, and recognizes:</p> <ul> <li>3-letter ISO 639-3 language codes;</li> <li>3-letter ISO 639-2 bibliographic (B) codes;</li> <li>2-letter ISO 639-1 codes;</li> <li>English language names.</li> </ul> <p>Terms not falling into any of the above categories will be considered invalid. To choose what to do with invalid terms, see the <code>allow_invalid</code> parameter.</p> <p>For the best results with the <code>normalize</code> option, we recommend that you record languages in Zotero using 2-letter ISO 639-1 codes (because they also happen to be supported by the Citation Style Language), or 3-letter ISO 639-3 codes for languages not covered by ISO 639-1.</p> <p>If <code>normalize</code> is set to <code>false</code>, item language values will be used verbatim. In that case, the facet will work equally well if your language data is well controlled and consistent. This is the way to go if languages are consistently recorded using their non-English names in your Zotero library.</p> <p>Type: Boolean  Default value: <code>true</code></p>"},{"location":"config-params/#values_separator_re","title":"<code>values_separator_re</code>","text":"<p>Regular expression to use for splitting the content of Zotero's Language field into multiple languages, e.g., <code>en; de; it</code>. We do not necessarily recommend recording multiple languages in the Language field, but in practice some people do when describing multilingual resources.</p> <p>Type: String  Default value: <code>\";\"</code></p>"},{"location":"config-params/#kerkofeatures","title":"<code>kerko.features.</code>","text":""},{"location":"config-params/#download_attachment_new_window","title":"<code>download_attachment_new_window</code>","text":"<p>Open attachments in new tabs. In other words: add the HTML <code>target=\"_blank\"</code> attribute to attachment links.</p> <p>Type: Boolean  Default value: <code>false</code></p>"},{"location":"config-params/#download_item","title":"<code>download_item</code>","text":"<p>Provide a record download button on item pages.</p> <p>To configure the bibliographic formats made available for downloading, see <code>kerko.bib_formats</code>.</p> <p>Type: Boolean  Default value: <code>true</code></p>"},{"location":"config-params/#download_results","title":"<code>download_results</code>","text":"<p>Provide a record download button on search results pages.</p> <p>To configure the bibliographic formats made available for downloading, see <code>kerko.bib_formats</code>.</p> <p>Type: Boolean  Default value: <code>true</code></p>"},{"location":"config-params/#download_results_max_count","title":"<code>download_results_max_count</code>","text":"<p>Limit over which the record download button should be hidden from search results pages.</p> <p>Type: Integer  Default value: <code>0</code> (i.e., no limit)</p>"},{"location":"config-params/#open_in_zotero_app","title":"<code>open_in_zotero_app</code>","text":"<p>On item pages, show a button for opening the corresponding item in the Zotero application (through a link using the <code>zotero://</code> protocol). If this parameter is set to <code>true</code>, a user will still need to first enable the button from the Preferences menu (which can be accessed from the footer of item pages and saves the user's choices in browser cookies). For the link to work, the user must also have the Zotero application installed, and have access to the Zotero library. This feature is generally only useful to library editors and might confuse other users, especially if your Zotero library is private. Thus you should probably enable this option only if there is a strong need from the editors.</p> <p>Type: Boolean  Default value: <code>false</code></p>"},{"location":"config-params/#open_in_zotero_web","title":"<code>open_in_zotero_web</code>","text":"<p>On item pages, show a button for viewing the corresponding item on zotero.org (through a regular hyperlink). If this parameter is set to <code>true</code>, a user will still need to first enable the button from the Preferences menu (which can be accessed from the footer of item pages and saves the user's choices in browser cookies). For the link to work, the user must also have access to the Zotero library. This feature is generally only useful to library editors and might confuse other users, especially if your Zotero library is private. Thus you should probably enable this option only if there is a strong need from the editors.</p> <p>Type: Boolean  Default value: <code>false</code></p>"},{"location":"config-params/#print_item","title":"<code>print_item</code>","text":"<p>Provide a print button on item pages.</p> <p>Type: Boolean  Default value: <code>false</code></p>"},{"location":"config-params/#print_results","title":"<code>print_results</code>","text":"<p>Provide a print button on search results pages.</p> <p>Type: Boolean  Default value: <code>false</code></p>"},{"location":"config-params/#print_results_max_count","title":"<code>print_results_max_count</code>","text":"<p>Limit over which the print button should be hidden from search results pages.</p> <p>Type: Integer  Default value: <code>0</code> (i.e., no limit)</p>"},{"location":"config-params/#relations_initial_limit","title":"<code>relations_initial_limit</code>","text":"<p>Number of related items to show above the \"show more\" link.</p> <p>Type: Integer  Default value: <code>5</code></p>"},{"location":"config-params/#relations_links","title":"<code>relations_links</code>","text":"<p>Show item links in lists of related items.</p> <p>Enabling this only has an effect if at least one of the following variables is also set to <code>true</code>: <code>kerko.features.results_attachment_links</code>, <code>kerko.features.results_url_links</code>.</p> <p>Type: Boolean  Default value: <code>false</code></p>"},{"location":"config-params/#results_abstracts","title":"<code>results_abstracts</code>","text":"<p>Show abstracts on search result pages.</p> <p>Type: Boolean  Default value: <code>false</code> (i.e., hide abstracts)</p>"},{"location":"config-params/#results_abstracts_toggler","title":"<code>results_abstracts_toggler</code>","text":"<p>Show a button letting users show or hide abstracts on search results pages.</p> <p>Type: Boolean  Defaults value: <code>true</code> (i.e., toggle is displayed)</p>"},{"location":"config-params/#results_abstracts_max_length","title":"<code>results_abstracts_max_length</code>","text":"<p>Truncate abstracts at the given length (in number of characters). If text is to be truncated in the middle of a word, the whole word is discarded instead. Truncated text is appended with an ellipsis sign (\"...\").</p> <p>Type: Integer  Default value: <code>0</code> (i.e., abstracts get displayed in their full length, without any truncation)</p>"},{"location":"config-params/#results_abstracts_max_length_leeway","title":"<code>results_abstracts_max_length_leeway</code>","text":"<p>If the length of an abstract only exceeds <code>kerko.features.results_abstracts_max_length</code> by this tolerance margin or less (in number of characters), it will not be truncated.</p> <p>This parameter has no effect if <code>results_abstracts_max_length</code> is set to <code>0</code> (no truncation).</p> <p>Type: Integer  Default value: <code>0</code> (i.e., no tolerance margin).</p>"},{"location":"config-params/#results_attachment_links","title":"<code>results_attachment_links</code>","text":"<p>Provide links to attachments in search results.</p> <p>Type: Boolean  Default value: <code>true</code></p>"},{"location":"config-params/#results_url_links","title":"<code>results_url_links</code>","text":"<p>Provide links to online resources in search results (for items whose URL field has a value).</p> <p>Type: Boolean  Default value: <code>true</code></p>"},{"location":"config-params/#kerkofeeds","title":"<code>kerko.feeds.</code>","text":""},{"location":"config-params/#formats","title":"<code>formats</code>","text":"<p>A list of syndication feed formats to publish.</p> <p>If set to an empty array, no web feed will be provided. The only supported format at this time is <code>'atom'</code>.</p> <p>Type: Array of strings  Default value: <code>[\"atom\"]</code></p>"},{"location":"config-params/#fields","title":"<code>fields</code>","text":"<p>List of fields to retrieve for each feed item. Values in this list are keys identifying fields defined in the <code>kerko_composer</code> object, and the list must contain all fields that are used by the <code>kerko.templates.atom_feed</code> template.</p> <p>One probably only needs to change the default list when overriding the template to display additional fields.</p> <p>Note that some fields from the default list may be required by Kerko, and removing those could cause crashes.</p> <p>Type: Dictionary</p>"},{"location":"config-params/#max_days","title":"<code>max_days</code>","text":"<p>The age (in number of days) of the oldest items allowed into web feeds. The date field of the items is used for that purpose, and when no date is available, the date the item was added to Zotero is used instead.</p> <p>Unless your goal is to promote recent literature only, you should probably keep the default value.</p> <p>Items with missing dates will be considered as very recent, to prevent them from being excluded from feeds. For the same reason, items whose date lack the month and/or the day will be considered as from the 12<sup>th</sup> month of the year and/or the last day of the month.</p> <p>Type: Integer  Default value: <code>0</code> (i.e., no age limit)</p>"},{"location":"config-params/#kerkolink_groups","title":"<code>kerko.link_groups.*.</code>","text":"<p>Link groups, where <code>*</code> is an arbitrary key used for identifying the group. Each group is a list which must contain at least one link defined using one or more of the sub-parameters described below.</p> <p>Link groups can be used for navigation or anywhere hyperlinks are needed. Templates can use the key to retrieve a desired link group.</p> <p>Kerko provides default <code>navbar</code> and <code>breadcrumb_base</code> link groups. In TOML format, these are defined as below (the double brackets indicate a list item):</p> <pre><code>[[kerko.link_groups.navbar]]\ntype = \"endpoint\"\nendpoint = \"kerko.search\"\ntext = \"Bibliography\"\n\n[[kerko.link_groups.breadcrumb_base]]\ntype = \"endpoint\"\nendpoint = \"kerko.search\"\ntext = \"Bibliography\"\n</code></pre>"},{"location":"config-params/#anchor","title":"<code>anchor</code>","text":"<p>Anchor to append to the endpoint's URL.</p> <p>This optional parameter is only allowed when the <code>type</code> parameter is set to <code>\"endpoint\"</code>.</p> <p>Type: String</p>"},{"location":"config-params/#endpoint","title":"<code>endpoint</code>","text":"<p>Name of the endpoint within the application to use as target for the link. Use this for internal links. For example, the endpoint for the Kerko search page is <code>\"kerko.search\"</code>.</p> <p>This parameter is required if the <code>type</code> parameter is set to <code>\"endpoint\"</code> and has no default value.</p> <p>Type: String</p>"},{"location":"config-params/#external","title":"<code>external</code>","text":"<p>Generate a full URL (with scheme and domain) for the endpoint instead of an internal URL.</p> <p>This parameter is only allowed when the <code>type</code> parameter is set to <code>\"endpoint\"</code>.</p> <p>Type: Boolean  Default value: <code>false</code></p>"},{"location":"config-params/#new_window","title":"<code>new_window</code>","text":"<p>Open the link in a new tab.</p> <p>Type: Boolean  Default value: <code>false</code></p>"},{"location":"config-params/#page","title":"<code>page</code>","text":"<p>Key of the page to use as target for the link. That page must have been defined in <code>kerko.pages.*</code>.</p> <p>This parameter is required if the <code>type</code> parameter is set to <code>\"page\"</code> (and cannot be used with other <code>type</code> values).</p> <p>Type: String </p>"},{"location":"config-params/#parameters","title":"<code>parameters</code>","text":"<p>Dictionary of parameters to pass to the endpoint. Unknown keys are appended to the URL as query string arguments, like <code>?a=b&amp;c=d</code>.</p> <p>This optional parameter is only allowed when the <code>type</code> parameter is set to <code>\"endpoint\"</code>.</p> <p>Type: Dictionary</p>"},{"location":"config-params/#scheme","title":"<code>scheme</code>","text":"<p>Protocol to use in the endpoint's URL.</p> <p>This parameter is only allowed when the <code>type</code> parameter is set to <code>\"endpoint\"</code> and the <code>external</code> parameter is set to <code>true</code>.</p> <p>Type: String  Default value: Same protocol as the current request</p>"},{"location":"config-params/#text","title":"<code>text</code>","text":"<p>Text to use for the link.</p> <p>This parameter is required and has no default value.</p> <p>Type: String</p>"},{"location":"config-params/#type_1","title":"<code>type</code>","text":"<p>Type of link being configured. Other parameters may or may not be available depending on this value.</p> <p>Allowed values are:</p> <ul> <li><code>\"endpoint\"</code>: Link to an application page (served by a Flask endpoint).</li> <li><code>\"page\"</code>: Link to a page defined in <code>kerko.pages.*</code>.</li> <li><code>\"url\"</code>: Link to an arbitrary URL.</li> </ul> <p>This parameter is required and has no default value.</p> <p>Type: String</p>"},{"location":"config-params/#url","title":"<code>url</code>","text":"<p>URL of the external link.</p> <p>This parameter is required if the <code>type</code> parameter is set to <code>\"url\"</code>.</p> <p>Type: String</p>"},{"location":"config-params/#weight_2","title":"<code>weight</code>","text":"<p>Relative position of the link in lists. Links with low weights (small numbers) rise above heavier ones (large numbers). At equal weights, links are ordered based on their order of appearance in the configuration.</p> <p>Type: Integer  Default value: <code>0</code></p>"},{"location":"config-params/#kerkometa","title":"<code>kerko.meta.</code>","text":""},{"location":"config-params/#google_analytics_id","title":"<code>google_analytics_id</code>","text":"<p>A Google Analytics stream ID, e.g., <code>'G-??????????'</code>.</p> <p>If the value is not empty and Flask is not running in debug mode, then the Google Analytics tag is inserted into the pages.</p> <p>Type: String  Default value: <code>\"\"</code></p>"},{"location":"config-params/#highwirepress_tags","title":"<code>highwirepress_tags</code>","text":"<p>Embed Highwire Press tags into the HTML of item pages. This should help search engines such as Google Scholar index your items more accurately, but works only with book, conference paper, journal article, report or thesis items.</p> <p>Type: Boolean  Default value: <code>true</code> (i.e., enabled).</p>"},{"location":"config-params/#title_1","title":"<code>title</code>","text":"<p>The title to display in web pages.</p> <p>Type: String</p>"},{"location":"config-params/#kerkopages","title":"<code>kerko.pages.*.</code>","text":"<p>Simple content pages, where <code>*</code> is an arbitrary key you must choose to uniquely identify the page. The content of the page will come from a Zotero standalone note of your choosing.</p> <p>The key can be used in <code>kerko.link_groups.*</code> tables to define hyperlinks to the page.</p>"},{"location":"config-params/#path","title":"<code>path</code>","text":"<p>The path to use in the URL of the page. Must start with a slash (<code>/</code>) character.</p> <p>Type: String </p>"},{"location":"config-params/#item_id","title":"<code>item_id</code>","text":"<p>The Zotero item ID of the note to use as content for the page.</p> <p>Type: String </p>"},{"location":"config-params/#title_2","title":"<code>title</code>","text":"<p>The title of the page.</p> <p>Type: String </p>"},{"location":"config-params/#kerkopagination","title":"<code>kerko.pagination.</code>","text":""},{"location":"config-params/#page_len","title":"<code>page_len</code>","text":"<p>The number of search results per page.</p> <p>Type: Integer  Default value: <code>20</code></p>"},{"location":"config-params/#pager_links","title":"<code>pager_links</code>","text":"<p>Number of pages to show in the pager (not counting the current page).</p> <p>Type: Integer  Default value: <code>4</code></p>"},{"location":"config-params/#kerkoperformance","title":"<code>kerko.performance.</code>","text":""},{"location":"config-params/#whoosh_index_memory_limit","title":"<code>whoosh_index_memory_limit</code>","text":"<p>Maximum memory (in megabytes) the Whoosh index writer will use for the indexing pool. The higher the number, the faster indexing will be.</p> <p>The actual memory used will be higher than this value because of interpreter overhead (up to twice as much!). Other operations performed by Kerko at indexing time use memory too. Thus, although useful as a tuning parameter, this setting does not allow to exactly control the memory usage.</p> <p>Type: Integer  Default value: 128</p>"},{"location":"config-params/#whoosh_index_processors","title":"<code>whoosh_index_processors</code>","text":"<p>Controls the number of processors Whoosh will use for indexing.</p> <p>Note that when you use multiprocessing, the <code>whoosh_index_memory_limit</code> parameter controls the amount of memory used by each process, so the actual memory used will be <code>whoosh_index_memory_limit</code> \u00d7 <code>whoosh_index_processors</code>.</p> <p>Type: Integer  Default value: 1</p>"},{"location":"config-params/#kerkoscopes","title":"<code>kerko.scopes.*.</code>","text":"<p>Keyword search scopes, where <code>*</code> is a scope key. The scope key is used internally by Kerko to identify the scope. Scopes allow users to restrict the search to some fields.</p> <p>The default scopes are:</p> <ul> <li><code>all</code></li> <li><code>creator</code></li> <li><code>fulltext</code></li> <li><code>metadata</code></li> <li><code>pubyear</code></li> <li><code>title</code></li> </ul> <p>You may define additional scopes.</p> <p>To link fields to scopes, see <code>kerko.search_fields.scopes</code>.</p>"},{"location":"config-params/#breadbox_label","title":"<code>breadbox_label</code>","text":"<p>Label to use when the scope appears in the breadbox, i.e. in the list of search criteria.</p>"},{"location":"config-params/#enabled_3","title":"<code>enabled</code>","text":"<p>Enable the scope.</p> <p>Type: Boolean</p>"},{"location":"config-params/#help_text_1","title":"<code>help_text</code>","text":"<p>Description of the scope, to show in the help window.</p> <p>Type: String</p>"},{"location":"config-params/#selector_label","title":"<code>selector_label</code>","text":"<p>Label to use in the scope selector.</p> <p>Type: String</p>"},{"location":"config-params/#weight_3","title":"<code>weight</code>","text":"<p>Relative position of the scope in lists. Scopes with low weights (small numbers) rise above heavier ones (large numbers).</p> <p>Type: Integer</p>"},{"location":"config-params/#kerkosearch","title":"<code>kerko.search.</code>","text":""},{"location":"config-params/#fulltext","title":"<code>fulltext</code>","text":"<p>Allow full-text search of PDF attachments.</p> <p>Type: Boolean  Default value: <code>true</code></p> <p>Tip</p> <p>To get consistent results with full-text search, see Ensuring full-text indexing of your attachments in Zotero.</p> <p>Tip</p> <p>When setting <code>kerko.search.fulltext</code> to <code>false</code>, it is recommended that you set <code>kerko.scopes.fulltext.enabled</code> and <code>kerko.scopes.metadata.enabled</code> to <code>false</code> as well. With full-text data unavailable, the <code>fulltext</code> scope is useless, and the <code>metadata</code> scope gives the same results as the <code>all</code> scope.</p> <p>Modifies the cache and the search index</p> <p>Changing this parameter will require that you run the <code>sync cache --full</code> and <code>sync index</code> commands. See synchronization commands for details.</p>"},{"location":"config-params/#result_fields","title":"<code>result_fields</code>","text":"<p>List of item fields to retrieve for search results (most notably used by the <code>kerko.templates.search_item</code> template).</p> <p>Values in this list are keys identifying fields defined in the <code>kerko.composer.Composer</code> instance. One probably only needs to change the default list when overriding the template to display additional fields.</p> <p>Note that some fields from the default list may be required by Kerko, and removing those could cause crashes.</p> <p>Type: Array of strings  Default value: <code>[\"id\", \"attachments\", \"bib\", \"coins\", \"data\", \"url\"]</code></p>"},{"location":"config-params/#whoosh_language","title":"<code>whoosh_language</code>","text":"<p>The language of search requests.</p> <p>As of this writing, Whoosh supports the following languages: ar, da, nl, en, fi, fr, de, hu, it, no, pt, ro, ru, es, sv, tr. You may refer to Whoosh's source code to get the list of supported languages (see <code>whoosh.lang.languages</code>) and the list of languages that support stemming (see <code>whoosh.lang.has_stemmer()</code>).</p> <p>Type: String  Default value: <code>\"en\"</code></p> <p>Modifies the search index</p> <p>Changing this parameter will require that you run the <code>sync index --full</code> command. See synchronization commands for details.</p>"},{"location":"config-params/#kerkosearch_fields","title":"<code>kerko.search_fields.*.</code>","text":"<p>Searchable fields, where <code>*</code> is a field key. The default fields fall into different tables:</p> <ul> <li><code>core.optional.*</code>: These fields have limited parameters. Their only allowed   parameters are <code>boost</code>, <code>enabled</code>, and <code>scopes</code>.</li> <li><code>core.required.*</code>: These fields cannot be disabled. Their only allowed   parameters are <code>boost</code> and <code>scopes</code>.</li> <li><code>zotero.*</code>: These fields derive directly from Zotero item fields and allow all   field parameters.</li> </ul> <p>The configuration system does not allow adding new fields.</p> <p>Modifies the search index</p> <p>Changing any of the <code>kerko.search_fields.*</code> parameters will require that you run the <code>clean index</code> and <code>sync index</code> commands, except if you are just disabling a field or changing its <code>scopes</code> parameter. See synchronization commands for details.</p>"},{"location":"config-params/#analyzer","title":"<code>analyzer</code>","text":"<p>Type of analysis to apply to the field value when building the search index.</p> <p>Allowed values:</p> <ul> <li><code>\"id\"</code>: Index the entire value of the field as one token.</li> <li><code>\"name\"</code>: Apply standard tokenization and filtering, but without stemming.</li> <li><code>\"text\"</code>: Apply standard tokenization, stemming and filtering.</li> </ul> <p>Type: String</p>"},{"location":"config-params/#boost","title":"<code>boost</code>","text":"<p>Scaling factor to apply to score when matches are found in the field.</p> <p>Type: Float</p>"},{"location":"config-params/#enabled_4","title":"<code>enabled</code>","text":"<p>Enable the field.</p> <p>Type: Boolean</p>"},{"location":"config-params/#scopes","title":"<code>scopes</code>","text":"<p>List of keyword search scopes that will exploit the field.</p> <p>Allowed values are determined by <code>kerko.scopes</code>.</p> <p>Type: Array of strings</p>"},{"location":"config-params/#kerkosorts","title":"<code>kerko.sorts.*.</code>","text":"<p>Search results sorting options, where <code>*</code> is a sort option key.</p> <p>The default sort options are:</p> <ul> <li><code>author_asc</code></li> <li><code>author_desc</code></li> <li><code>date_asc</code></li> <li><code>date_desc</code></li> <li><code>score</code></li> <li><code>title_asc</code></li> <li><code>title_desc</code></li> </ul> <p>The configuration system does not allow adding new sort options.</p>"},{"location":"config-params/#enabled_5","title":"<code>enabled</code>","text":"<p>Enable the sort option.</p> <p>Type: Boolean</p>"},{"location":"config-params/#label_1","title":"<code>label</code>","text":"<p>Label of the sort option.</p> <p>Type: String</p>"},{"location":"config-params/#weight_4","title":"<code>weight</code>","text":"<p>Relative position of the sort option in lists. Sort options with low weights (small numbers) rise above heavier ones (large numbers).</p> <p>The default sort option will be the one with the lowest weight.</p> <p>Type: Integer</p> <p>Tip</p> <p>It is recommended that <code>kerko.sorts.score.weight</code> has the smallest value of all your sort options. Thus, when a keyword search is performed, sorting by relevance score will be the default, and when no keywords are used in the search, then the sort option with the second smallest weight will be the default one.</p>"},{"location":"config-params/#kerkotemplates","title":"<code>kerko.templates.</code>","text":""},{"location":"config-params/#search","title":"<code>search</code>","text":"<p>Name of the Jinja2 template to render for the search page with list of results.</p> <p>Type: String  Default value: <code>\"kerko/search.html.jinja2\"</code></p>"},{"location":"config-params/#search_item","title":"<code>search_item</code>","text":"<p>Name of the Jinja2 template to render for the search page with a single bibliographic record.</p> <p>Type: String  Default value: <code>\"kerko/search-item.html.jinja2\"</code></p>"},{"location":"config-params/#item","title":"<code>item</code>","text":"<p>Name of the Jinja2 template to render for the bibliographic record view.</p> <p>Type: String  Default value: <code>\"kerko/item.html.jinja2\"</code></p>"},{"location":"config-params/#atom_feed","title":"<code>atom_feed</code>","text":"<p>Name of the Jinja2 template used to render an Atom feed.</p> <p>Type: String  Default value: <code>\"kerko/atom.xml.jinja2\"</code></p>"},{"location":"config-params/#layout","title":"<code>layout</code>","text":"<p>Name of the Jinja2 template that is extended by the search, search-item, and item templates.</p> <p>Type: String  Default value: <code>\"kerko/layout.html.jinja2\"</code></p>"},{"location":"config-params/#base","title":"<code>base</code>","text":"<p>Name of the Jinja2 template that is extended by the layout template.</p> <p>Type: String  Default value: <code>\"kerko/base.html.jinja2\"</code></p>"},{"location":"config-params/#kerkozotero","title":"<code>kerko.zotero.</code>","text":""},{"location":"config-params/#attachment_mime_types","title":"<code>attachment_mime_types</code>","text":"<p>List of allowed MIME types for attachments.</p> <p>Type: Array of strings  Default value: <code>[\"application/pdf\"]</code></p> <p>Modifies the attachments</p> <p>Changing this parameter will require that you run the <code>sync attachments</code> command. See synchronization commands for details.</p>"},{"location":"config-params/#csl_style","title":"<code>csl_style</code>","text":"<p>The citation style to use for formatted references.</p> <p>Allowed values are either a file name (without the <code>.csl</code> extension) found in the Zotero Styles Repository (e.g., <code>\"apa\"</code>) or the publicly accessible URL of a remote CSL file.</p> <p>Type: String  Default value: <code>\"apa\"</code>.</p> <p>Modifies the cache and the search index</p> <p>Changing this parameter will require that you run the <code>sync cache --full</code> and <code>sync index</code> commands. See synchronization commands for details.</p>"},{"location":"config-params/#batch_size","title":"<code>batch_size</code>","text":"<p>Number of items to request on each call to the Zotero API.</p> <p>Type: Integer  Default value: <code>100</code> (this is the maximum currently allowed by the Zotero API)</p>"},{"location":"config-params/#child_include_re","title":"<code>child_include_re</code>","text":"<p>Regular expression to use to include children (e.g. notes, attachments) based on their tags. Any child which does not have a tag that matches this regular expression will be ignored. If this value is empty (which is the default), all children will be accepted unless <code>kerko.zotero.child_exclude_re</code> is set and causes some to be rejected.</p> <p>Type: String  Default value: <code>\"\"</code></p> <p>Modifies the search index and attachments</p> <p>Changing this parameter will require that you run the <code>sync index --full</code> and <code>sync attachments</code> commands. See synchronization commands for details.</p>"},{"location":"config-params/#child_exclude_re","title":"<code>child_exclude_re</code>","text":"<p>Regular expression to use to exclude children (e.g. notes, attachments) based on their tags. Any child that have a tag that matches this regular expression will be ignored. If empty, no children will be rejected unless <code>kerko.zotero.child_include_re</code> is set and the tags of those children do not match it. By default, any child having at least one tag that begins with an underscore character (<code>_</code>) is rejected.</p> <p>Type: String  Default value: <code>\"^_\"</code></p> <p>Modifies the search index and attachments</p> <p>Changing this parameter will require that you run the <code>sync index --full</code> and <code>sync attachments</code> commands. See synchronization commands for details.</p>"},{"location":"config-params/#item_include_re","title":"<code>item_include_re</code>","text":"<p>Regular expression to use to include items based on their tags. Any item which does not have a tag that matches this regular expression will be ignored. If this value is empty (which is the default), all items will be accepted unless <code>kerko.zotero.item_exclude_re</code> is set which can cause some items to be rejected.</p> <p>Type: String  Default value: <code>\"\"</code></p> <p>Modifies the search index and attachments</p> <p>Changing this parameter will require that you run the <code>sync index --full</code> and <code>sync attachments</code> commands. See synchronization commands for details.</p>"},{"location":"config-params/#item_exclude_re","title":"<code>item_exclude_re</code>","text":"<p>Regular expression to use to exclude items based on their tags. Any item that have a tag that matches this regular expression will be excluded. If empty (which is the default), no items will be excluded unless <code>kerko.zotero.item_include_re</code> is set, in which case items that do not have any tag that matches it will be excluded.</p> <p>Type: String  Default value: <code>\"\"</code></p> <p>Modifies the search index and attachments</p> <p>Changing this parameter will require that you run the <code>sync index --full</code> and <code>sync attachments</code> commands. See synchronization commands for details.</p>"},{"location":"config-params/#locale_1","title":"<code>locale</code>","text":"<p>The locale to use with Zotero API calls. This dictates the locale of Zotero item types, field names, creator types and citations. Supported locales are listed at https://api.zotero.org/schema, under \"locales\".</p> <p>Type: String  Default value: <code>\"en-US\"</code></p> <p>Modifies the cache and the search index</p> <p>Changing this parameter will require that you run the <code>sync cache --full</code> and <code>sync index</code> commands. See synchronization commands for details.</p>"},{"location":"config-params/#max_attempts","title":"<code>max_attempts</code>","text":"<p>Maximum number of tries after the Zotero API has returned an error or has not responded during indexing.</p> <p>Type: Integer  Default value: <code>10</code></p>"},{"location":"config-params/#tag_include_re","title":"<code>tag_include_re</code>","text":"<p>Regular expression to use to include tags. By default, all tags are accepted.</p> <p>Note that record exports (downloads) always include all tags regardless of this parameter, which only applies to information displayed by Kerko (exports are generated by the Zotero API, not by Kerko).</p> <p>Type: String  Default value: <code>\"\"</code></p> <p>Modifies the search index</p> <p>Changing this parameter will require that you run the <code>sync index --full</code> command. See synchronization commands for details.</p>"},{"location":"config-params/#tag_exclude_re","title":"<code>tag_exclude_re</code>","text":"<p>Regular expression to use to exclude tags. The default value causes any tag that begins with an underscore character (<code>_</code>) to be ignored by Kerko.</p> <p>Note that record exports (downloads) always include all tags regardless of this parameter, which only applies to information displayed by Kerko (exports are generated by the Zotero API, not by Kerko).</p> <p>Type: String  Default value: <code>\"^_\"</code></p> <p>Modifies the search index</p> <p>Changing this parameter will require that you run the <code>sync index --full</code> command. See synchronization commands for details.</p>"},{"location":"config-params/#wait","title":"<code>wait</code>","text":"<p>Time to wait (in seconds) between failed attempts to call the Zotero API.</p> <p>Type: Integer  Default value: <code>120</code></p>"},{"location":"config-params/#kerkoappproxy_fix","title":"<code>kerkoapp.proxy_fix.</code>","text":"<p>When an application is running behind a proxy server, WSGI may see the request as coming from that server rather than the real client. Proxies set various headers to track where the request actually came from.</p> <p>In that case you must tell the application how many proxies set each header so it knows what values to trust. However, enable this ONLY if the application is actually running behind a proxy; it would be a security issue to trust values that came directly from the client rather than a proxy.</p> <p>Refer to Tell Flask it is behind a proxy for details.</p> <p>Warning</p> <p>This parameter is specific to KerkoApp.</p>"},{"location":"config-params/#enabled_6","title":"<code>enabled</code>","text":"<p>Enable the proxy parameters.</p> <p>All other <code>kerkoapp.proxy_fix</code> parameters are ignored unless this is set to <code>true</code>.</p> <p>Type: Boolean  Default value: <code>false</code></p>"},{"location":"config-params/#x_for","title":"<code>x_for</code>","text":"<p>Number of values to trust for <code>X-Forwarded-For</code>.</p> <p>Type: Integer  Default value: <code>1</code></p>"},{"location":"config-params/#x_proto","title":"<code>x_proto</code>","text":"<p>Number of values to trust for <code>X-Forwarded-Proto</code>.</p> <p>Type: Integer  Default value: <code>1</code></p>"},{"location":"config-params/#x_host","title":"<code>x_host</code>","text":"<p>Number of values to trust for <code>X-Forwarded-Host</code>.</p> <p>Type: Integer  Default value: <code>0</code></p>"},{"location":"config-params/#x_port","title":"<code>x_port</code>","text":"<p>Number of values to trust for <code>X-Forwarded-Port</code>.</p> <p>Type: Integer  Default value: <code>0</code></p>"},{"location":"config-params/#x_prefix","title":"<code>x_prefix</code>","text":"<p>Number of values to trust for <code>X-Forwarded-Prefix</code>.</p> <p>Type: Integer  Default value: <code>0</code></p>"},{"location":"contributing/","title":"Contributing","text":"<p>This section provides guidance on how to contribute to the Kerko project.</p>"},{"location":"contributing/#reporting-issues","title":"Reporting issues","text":"<p>Before reporting an issue, please consider the following guidelines:</p> <ul> <li>Try to identify whether the issue belongs to Kerko or to KerkoApp. Then   submit the issue to the proper issue tracker, either Kerko's,   or KerkoApp's.</li> <li>Search existing issues, in case the same issue has already been reported or   even fixed in the repository.</li> <li>Describe what happened when you experienced the issue. Include the full   traceback if an exception was raised.</li> <li>Describe what you expected to happen.</li> <li>If possible, include a minimal reproducible example to help others identify   the issue.</li> </ul>"},{"location":"contributing/#making-code-changes","title":"Making code changes","text":"<p>Clone the Kerko repository into a local directory. Set up a virtual environment, then install that local version of Kerko in the virtual environment, including development and testing dependencies by running the following command from Kerko's root directory, i.e., where <code>setup.cfg</code> resides:</p> <pre><code>pip install -e .[dev,docs,tests]\n</code></pre>"},{"location":"contributing/#running-the-tests","title":"Running the tests","text":"<p>To run the test suite:</p> <pre><code>python -m unittest\n</code></pre> <p>To check code coverage as well, use these commands instead:</p> <pre><code>coverage run -m unittest\ncoverage report\n</code></pre> <p>To run the full test suite under different environments (using the various Python interpreters available on your machine):</p> <pre><code>tox\n</code></pre> <p>Note</p> <p>Test coverage is still low at the moment. You are welcome to contribute new tests!</p>"},{"location":"contributing/#running-the-pre-commit-hooks","title":"Running the pre-commit hooks","text":"<p>Pre-commit checks should be performed automatically whenever you perform a <code>git commit</code>. If you wish to run the checks manually, use this command:</p> <pre><code>pre-commit run --all-files\n</code></pre>"},{"location":"contributing/#working-on-the-documentation","title":"Working on the documentation","text":"<p>To start a local live-reloading documentation server:</p> <pre><code>mkdocs serve\n</code></pre> <p>Then view the documentation in your browser at http://localhost:8000/.</p>"},{"location":"contributing/#building-the-distribution-package","title":"Building the distribution package","text":"<p>When building the distribution package, a version number is dynamically extracted from the Git repository. For an official release, the Git head revision must be tagged prior to building the distribution package. When the revision is not tagged, a dev version number gets derived from the branch's most recent tag, with a suffix appended.</p> <p>To check the version number that will be generated:</p> <pre><code>hatch version\n</code></pre> <p>To build the distribution package in sdist and wheel formats:</p> <pre><code>hatch build\n</code></pre>"},{"location":"contributing/#submitting-code-changes","title":"Submitting code changes","text":"<p>Pull requests may be submitted against Kerko's repository. Please consider the following guidelines:</p> <ul> <li>Before submitting, run the tests and make sure they pass. Add tests relevant   to your change (those should fail if ran without your patch).</li> <li>Use Ruff to format Python code.</li> <li>If a Jinja2 template represents a page fragment or a collection of macros,   prefix its file name with the underscore character.</li> <li>Update the relevant sections of the documentation.</li> <li>Include a string like \"Fixes #123\" in your commit message (where 123 is the   issue you fixed). See Closing issues using   keywords.</li> </ul>"},{"location":"contributing/#submitting-a-translation","title":"Submitting a translation","text":"<p>Some guidelines:</p> <ul> <li>The PO file encoding must be UTF-8.</li> <li>The header of the PO file must be filled out appropriately.</li> <li>All messages of the PO file must be translated.</li> </ul> <p>Please submit your translation as a pull request against the proper repository, either Kerko's, or KerkoApp's, or by e-mail, with the PO file included as an attachment (do not copy the PO file's content into an e-mail's body, since that could introduce formatting or encoding issues).</p>"},{"location":"contributing/#supporting-the-project","title":"Supporting the project","text":"<p>Nurturing an open source project, following up on issues and helping others in working with the system is a lot of work. Hiring the original developers of Kerko can help make the project sustainable. It is the best way to ensure continued support and development of the project.</p> <p>If you need professional support related to Kerko, have requirements not currently implemented in Kerko, want to make sure that some Kerko issue important to you gets resolved, or if you just like our work and would like to hire us for an unrelated project, please e-mail us.</p>"},{"location":"deploying/","title":"How to deploy","text":"<p>As there is a great diversity of operating systems, hosting environments, and WSGI servers, it is hard to provide universal and useful instructions for setting up KerkoApp for use in production.</p> <p>You can expect a procedure similar to that of any Flask application, and there are many guides on the web covering this topic for various environments.</p> <p>That said, you may refer to the guide below for step-by-step instructions. Even if your environment is different from the one this guide was designed for, it might provide you with some useful hints.</p>"},{"location":"deploying/#deploying-on-ubuntu-2004-or-2204-with-nginx-and-gunicorn","title":"Deploying on Ubuntu 20.04 or 22.04 with nginx and gunicorn","text":"<p>These instructions will detail the steps and configurations required to get KerkoApp running on an Ubuntu 20.04 or 22.04 web server, using Gunicorn as the WSGI container and nginx as a HTTP proxy.</p> <p>The procedure is similar that of any Flask application, but KerkoApp-specific steps are also covered here.</p> <p>Install some required packages, including Python 3:</p> <pre><code>sudo apt install git nginx python3 python3-pip python3-venv\n</code></pre> <p>Create the user who will run the app:</p> <pre><code>sudo groupadd --system kerkoapp\nsudo useradd --gid kerkoapp --shell /bin/bash --create-home --home-dir /home/kerkoapp --groups www-data kerkoapp\n</code></pre> <p>Switch to that user and clone the desired version of KerkoApp. If you want to use version 1.0.0, for example, replace <code>VERSION</code> in the command below with <code>1.0.0</code>:</p> <pre><code>sudo su kerkoapp\ngit clone --branch VERSION https://github.com/whiskyechobravo/kerkoapp.git ~/kerkoapp\n</code></pre> <p>Still as user <code>kerkoapp</code>, create a Python virtual environment and install the Python packages required by KerkoApp:</p> <pre><code>python3 -m venv ~/venv\nsource ~/venv/bin/activate\npip3 install -r ~/kerkoapp/requirements/run.txt\npip3 install gunicorn\n</code></pre> <p>Always as user <code>kerkoapp</code>, create the <code>~/.secrets.toml</code> file. This is where you will put secret keys that should only be known to your server. Its content should look like the following:</p> .secrets.toml<pre><code>SECRET_KEY = \"MY_SECRET_KEY\"\nZOTERO_API_KEY = \"MY_ZOTERO_API_KEY\"\n</code></pre> <p>You must set <code>SECRET_KEY</code> with a random string, and <code>ZOTERO_API_KEY</code> with an appropriate value (see configuration parameters).</p> <p>Then create the <code>~/instance.toml</code> file. This file will contain settings that are specific to your server, but are not secret. Its content should look like the following:</p> instance.toml<pre><code>LOGGING_HANDLER = \"syslog\"\n\n[kerkoapp.proxy_fix]\nenabled = true\nx_for = 1\nx_proto = 1\nx_host = 1\nx_port = 0\nx_prefix = 0\n</code></pre> <p>We are enabling the <code>kerkoapp.proxy_fix</code> parameters because we will configure nginx as a reverse proxy.</p> <p>Then create the <code>~/config.toml</code> file. This file will contain general settings for Kerko. You might have already tested KerkoApp on your desktop computer and created such file. If so, you could just copy that file to your server. At the very least it should contain the following settings:</p> config.toml<pre><code>ZOTERO_LIBRARY_ID = \"MY_ZOTERO_LIBRARY_ID\"\nZOTERO_LIBRARY_TYPE = \"MY_ZOTERO_LIBRARY_TYPE\"\n\n[kerko.meta]\ntitle = \"My Bibliography\"\n</code></pre> <p>You must set <code>ZOTERO_LIBRARY_ID</code> and <code>ZOTERO_LIBRARY_TYPE</code> with appropriate values (see configuration parameters) so that Kerko can connect to your Zotero library.</p> <p>It is not absolutely necessary to use three separate configuration files for KerkoApp as we just did. You could, for example, have just <code>~/instance.toml</code> and put all of the settings there. However, it is a good practice to split the configuration, and that allows you to copy <code>config.toml</code> from or to other machines, or even share it with other people, without worrying about leaking secret keys or messing up your server-specific settings.</p> <p>Once the configuration files are ready, Kerko should be able to talk to Zotero. Have Kerko retrieve your Zotero library's data by running the following command:</p> <pre><code>flask --debug kerko sync\n</code></pre> <p>The <code>--debug</code> switch is optional. If you use it, some messages will give you an better idea of the progress of the sync process. If you omit it, the command will run silently unless there are warnings or errors.</p> <p>Depending on the size of your library, this process can complete within less than a minute or take an hour or more. Zotero throttles API requests to prevent its servers from getting overloaded, so sometimes the process might seem to freeze, but be patient and Kerko will resume synchronization a few minutes later.</p> <p>Now that synchronization works, configure the cron task that will synchronize data from your Zotero library on a regular basis. Run the following command (always from the <code>kerkoapp</code> user):</p> <pre><code>crontab -e\n</code></pre> <p>That will launch the default <code>nano</code> editor. Add the following line at the very bottom, then save the file and exit the editor:</p> crontab<pre><code>10 4 * * * cd /home/kerkoapp/kerkoapp &amp;&amp; /home/kerkoapp/venv/bin/flask kerko sync\n</code></pre> <p>That will synchronize the data once a day, at 4:10am. You may specify a different time, of course.</p> <p>Now exit from the <code>kerkoapp</code> user's shell, and go back to your usual sudoer account to finish the installation.</p> <p>Configure a socket that will let Gunicorn to speak with nginx. As the superuser, create the <code>/etc/systemd/system/kerkoapp.socket</code> file, with the following content:</p> kerkoapp.socket<pre><code>[Unit]\nDescription=KerkoApp socket\n\n[Socket]\nListenStream=/run/kerkoapp.socket\n\n[Install]\nWantedBy=kerkoapp.target\n</code></pre> <p>Configure a service that will run Gunicorn. As the superuser, create the <code>/etc/systemd/system/kerkoapp.service</code> file, with the following content:</p> kerkoapp.service<pre><code>[Unit]\nDescription=KerkoApp daemon\nRequires=kerkoapp.socket\nAfter=network.target\n\n[Service]\nWorkingDirectory=/home/kerkoapp/kerkoapp\nExecStart=/home/kerkoapp/venv/bin/gunicorn wsgi:app --name kerkoapp --user kerkoapp --group www-data --workers 4 --log-level warning --error-logfile - --access-logfile - --bind unix:/run/kerkoapp.socket\nExecReload=/bin/kill -s HUP $MAINPID\nExecStop=/bin/kill -s TERM $MAINPID\nPrivateTmp=true\n\n[Install]\nWantedBy=multi-user.target\n</code></pre> <p>Reload the systemd configurations, then enable and start the new service by running the following commands:</p> <pre><code>sudo systemctl daemon-reload\nsudo systemctl enable kerkoapp.socket\nsudo systemctl enable kerkoapp.service\nsudo systemctl start kerkoapp.socket\n</code></pre> <p>You can check whether the socket is active with this command:</p> <pre><code>sudo systemctl status kerkoapp.socket\n</code></pre> <p>If it shows up as 'active (listening)', you may now verify that it triggers the service:</p> <pre><code>curl --unix-socket /run/kerkoapp.socket localhost\nsudo systemctl status kerkoapp.service\n</code></pre> <p>The <code>curl</code> command should output some HTML, and the <code>systemctl</code> command should now show the KerkoApp daemon as 'active (running)'.</p> <p>If either the socket or the service doesn't work, you might want to check for errors in the log:</p> <pre><code>sudo journalctl --unit=kerkoapp\n</code></pre> <p>Once all of the above works, configure nginx to pass requests to Gunicorn. As the superuser, create the <code>/etc/nginx/sites-available/kerkoapp.conf</code> file with the following content, replacing <code>example.com</code> with your actual domain name:</p> kerkoapp.conf<pre><code>server {\n    listen 80;\n    server_name example.com;\n\n    location / {\n        proxy_redirect off;\n        proxy_set_header Host $http_host;\n        proxy_set_header X-Real-IP $remote_addr;\n        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n        proxy_set_header X-Forwarded-Host $server_name;\n        proxy_set_header X-Forwarded-Proto $scheme;\n\n        if (!-f $request_filename) {\n            proxy_pass http://unix:/run/kerkoapp.socket;\n            break;\n        }\n    }\n}\n</code></pre> <p>Enable the site by running the following command:</p> <pre><code>sudo ln -s /etc/nginx/sites-available/kerkoapp.conf /etc/nginx/sites-enabled/\n</code></pre> <p>Have nginx test the configuration:</p> <pre><code>sudo nginx -t\n</code></pre> <p>If the command reports the configuration test as successful, reload nginx to make the configuration changes effective:</p> <pre><code>sudo service nginx reload\n</code></pre> <p>You should now be able to view your KerkoApp site at http://example.com!</p> <p>The nginx configuration above will serve the application using the HTTP protocol. As for any website, HTTPS is strongly recommended. That will require that you install a SSL certificate and configure nginx to use it; that exercise is left to the reader.</p> <p>Changing the configuration can be disruptive</p> <p>Making any change to a configuration file requires that you at least restart the application afterwards for the change to become effective.</p> <p>Moreover, some parameters have an effect on the structure of the cache or the search index that Kerko depends on. Changing this kind of parameter may require that you rebuild either. Refer to the documentation of the parameter to check if specific actions need to be taken after a change.</p> <p>The commands below, for example, will allow you to clean and rebuild the search index, and to restart KerkoApp:</p> <pre><code>sudo -iu kerkoapp bash -c 'cd /home/kerkoapp/kerkoapp &amp;&amp; /home/kerkoapp/venv/bin/flask kerko clean index'\nsudo -iu kerkoapp bash -c 'cd /home/kerkoapp/kerkoapp &amp;&amp; /home/kerkoapp/venv/bin/flask kerko sync'\nsudo systemctl stop kerkoapp.socket\nsudo systemctl start kerkoapp.socket\n</code></pre>"},{"location":"deploying/#submitting-your-sitemap-to-search-engines","title":"Submitting your sitemap to search engines","text":"<p>Kerko generates an XML Sitemap that can help search engines discover your bibliographic records.</p> <p>The path of the sitemap is <code>BASE_URL/sitemap.xml</code>, where <code>BASE_URL</code> should be replaced with the protocol, domain, port, and Kerko URL path prefix that are relevant to your installation, e.g., <code>https://example.com/bibliography/sitemap.xml</code>.</p> <p>Different search engines may have different procedures for submitting sitemaps (Google, Bing, Yandex).</p> <p>However, a standard method consists in adding a <code>Sitemap</code> directive to a <code>robots.txt</code> file served at the root of your site, to tell web crawlers where to find your sitemap. For example, one might add the following line to <code>robots.txt</code>:</p> <pre><code>Sitemap: https://example.com/bibliography/sitemap.xml\n</code></pre> <p>A <code>robots.txt</code> file can have multiple <code>Sitemap</code> directives, thus the Kerko sitemap can be specified alongside any other sitemaps you might already have.</p>"},{"location":"getting-started/","title":"Getting started","text":"<p>For getting started with Kerko, we recommend that you use KerkoApp. However, if KerkoApp is not suited to your use case, we also have instructions for creating a custom application.</p>"},{"location":"getting-started/#getting-started-with-kerkoapp","title":"Getting started with KerkoApp","text":"<p>To install KerkoApp, you may choose between a \"standard\" installation and a Docker installation. Just go with the option you feel most comfortable with. If you don't know Docker, you should be fine with the standard installation. But if you prefer to keep your distance from Python-related stuff, perhaps the Docker installation will suit you best.</p>"},{"location":"getting-started/#standard-installation","title":"Standard installation","text":"<p>This procedure requires that you have Python, pip, and Git installed on your computer.</p> <ol> <li> <p>The first step is to install the desired version of KerkoApp. You may check    the list of available versions, but make sure to choose    one that matches the documentation version you are currently reading! For    version 1.0.0, for example, replace <code>VERSION</code> with <code>1.0.0</code> in the commands    below:</p> POSIXWindows <pre><code>git clone --branch VERSION https://github.com/whiskyechobravo/kerkoapp.git\ncd kerkoapp\npython -m venv venv\nsource venv/bin/activate\npip install -r requirements/run.txt\n</code></pre> <pre><code>git clone --branch VERSION https://github.com/whiskyechobravo/kerkoapp.git\ncd kerkoapp\npython -m venv venv\nvenv\\Scripts\\activate.bat\npip install -r requirements\\run.txt\n</code></pre> <p>This will install all packages required by Kerko and KerkoApp within a virtual environment.</p> </li> <li> <p>Copy the <code>sample.secrets.toml</code> file to <code>.secrets.toml</code> in the same directory.    Open <code>.secrets.toml</code> in a text editor to assign proper values to the    parameters outlined below:</p> <ul> <li><code>SECRET_KEY</code>: This parameter is required for generating secure tokens in   web forms. It should have a hard to guess value, and should really remain   secret. For this reason, never add your <code>.secrets.toml</code> file to a code   repository.</li> <li><code>ZOTERO_API_KEY</code>: Your Zotero API key. See API key creation   instructions.</li> </ul> </li> <li> <p>Copy the <code>sample.config.toml</code> file to <code>config.toml</code> in the same directory.    Open <code>config.toml</code> in a text editor to assign proper values to the parameters    outlined below:</p> <ul> <li><code>ZOTERO_LIBRARY_ID</code>: The identifier of the Zotero library to get   data from. For a personal library the value is your userID, as found on   https://www.zotero.org/settings/keys (you must be logged-in). For a group   library this value is the groupID of the library, as found in the URL of   the library (e.g., the groupID of the library at   https://www.zotero.org/groups/2348869/kerko_demo is <code>\"2348869\"</code>).</li> <li><code>ZOTERO_LIBRARY_TYPE</code>: The type of library to get data from,   either <code>\"user\"</code> for a personal library, or <code>\"group\"</code> for a group library.</li> </ul> <p>You do not need to edit other parameters at this point, but later on <code>config.toml</code> is where your configuration changes will take place.</p> </li> <li> <p>Have KerkoApp synchronize your data from zotero.org:</p> <pre><code>flask --debug kerko sync\n</code></pre> <p>If you have a large Zotero library and/or large file attachments, that command may take a while to complete. Wait until the command finishes. In production use, this command is usually added to the crontab file for regular execution.</p> <p>The <code>--debug</code> switch is optional. If you use it, some messages will give you an idea of the sync process' progress. If you omit it, the command will run silently unless there are warnings or errors.</p> <p>To list all commands provided by Kerko:</p> <pre><code>flask kerko --help\n</code></pre> </li> <li> <p>Run KerkoApp:</p> <pre><code>flask --debug run\n</code></pre> </li> <li> <p>Open http://localhost:5000/ in your browser and explore the bibliography!</p> </li> </ol> <p>Running your installed application</p> <p>To launch the application again in a future session, make sure to reactivate the virtual environment first. The command sequence should look like:</p> POSIXWindows <pre><code>cd kerkoapp\nsource venv/bin/activate\nflask --debug run\n</code></pre> <pre><code>cd kerkoapp\nvenv\\Scripts\\activate.bat\nflask --debug run\n</code></pre> <p>Not suitable for production</p> <p>The above procedure relies on Flask's built-in server, which is not suitable for production. For production use, you should consider better options such as the WSGI servers suggested in the Flask documentation.</p>"},{"location":"getting-started/#docker-installation","title":"Docker installation","text":"<p>This procedure requires that Docker is installed on your computer.</p> <ol> <li> <p>Copy the <code>Makefile</code>, <code>sample.secrets.toml</code>, and <code>sample.config.toml</code> files    from the most recent stable branch of the KerkoApp repository (e.g.    https://github.com/whiskyechobravo/kerkoapp/tree/stable/1.0.x) to an empty    directory on your computer.</p> </li> <li> <p>Under the same directory, create a subdirectory named <code>instance</code>. This is    where you will put your configuration files, and where Kerko will save its    data.</p> </li> <li> <p>Copy <code>sample.secrets.toml</code> as <code>.secrets.toml</code> into the <code>instance</code>    subdirectory. Open <code>instance/.secrets.toml</code> in a text editor to assign proper    values to the configuration parameters outlined below:</p> <ul> <li><code>SECRET_KEY</code>: This parameter is required for generating secure tokens in   web forms. It should have a hard to guess value, and should really remain   secret. For this reason, never add your <code>.secrets.toml</code> file to a code   repository.</li> <li><code>ZOTERO_API_KEY</code>: Your Zotero API key. See API key creation   instructions.</li> </ul> </li> <li> <p>Copy <code>sample.config.toml</code> as <code>config.toml</code> into the <code>instance</code> subdirectory.    Open <code>instance/config.toml</code> in a text editor to assign proper values to the    configuration parameters outlined below:</p> <ul> <li><code>ZOTERO_LIBRARY_ID</code>: The identifier of the Zotero library to get   data from. For a personal library the value is your userID, as found on   https://www.zotero.org/settings/keys (you must be logged-in). For a group   library this value is the groupID of the library, as found in the URL of   the library (e.g., the groupID of the library at   https://www.zotero.org/groups/2348869/kerko_demo is <code>\"2348869\"</code>).</li> <li><code>ZOTERO_LIBRARY_TYPE</code>: The type of library to get data from,   either <code>\"user\"</code> for a personal library, or <code>\"group\"</code> for a group library.</li> </ul> <p>It should not be necessary to change other settings at this point. You can always come back later to this file in order to configure KerkoApp to your liking. For now, we suggest that you proceed to the next step and get it running.</p> </li> <li> <p>From the same directory as <code>Makefile</code>, run KerkoApp:</p> <pre><code>make run\n</code></pre> <p>This command should do many things:</p> <ul> <li>Download and install the latest KerkoApp Docker image from DockerHub.</li> <li>Run the Docker container to have KerkoApp retrieve your data from   zotero.org.</li> <li>Run the Docker container to launch the KerkoApp server.</li> </ul> <p>If your configuration files have errors, the process may be interrupted; if that happens, retry <code>make run</code> after correcting the problem. Otherwise, if all goes well, you will only have to wait a bit for the data synchronization process to complete. This may take a long time if you have a large Zotero library.</p> <p>Kerko's data will be stored in the <code>instance</code> subdirectory.</p> <p>KerkoApp should launch once the synchronization process has completed. When you see the following message in the terminal, proceed to the next step:</p> <pre><code>[INFO] Listening at: http://0.0.0.0:80\n</code></pre> </li> <li> <p>Open http://localhost:8080/ in your browser and explore the bibliography!</p> </li> </ol> <p>To stop the KerkoApp server, press Ctrl+C in the terminal where the container is running.</p> <p>The next time you execute <code>make run</code>, it will find that the image has been already been downloaded and the data synchronized, and thus it will just launch the server.</p> <p>Using the Kerko command line interface (CLI) with Docker</p> <p>To use Kerko's command line interface, enter this command from the same directory as <code>Makefile</code>:</p> <pre><code>make shell\n</code></pre> <p>This will start an interactive shell within the Docker container. From there, you may run Kerko commands to clean Kerko's data, to synchronize from zotero.org, or to check Kerko's configuration. The command below lists all the commands provided by Kerko:</p> <pre><code>flask kerko --help\n</code></pre> <p>To exit the interactive shell, enter <code>exit</code> or press Ctrl+D at the command prompt.</p> <p>Building a Docker image for production</p> <p>The <code>Makefile</code> is just an example that shows how to build and interact with a dockerized KerkoApp. For production use, you might want to clone the full KerkoApp repository, make some changes to its <code>Dockerfile</code>, and build your own image.</p> <p>For full documentation on how to run Docker containers, including port mapping and volume binding, see the Docker documentation.</p>"},{"location":"getting-started/#creating-a-custom-application","title":"Creating a custom application","text":"<p>This section should help you understand the minimal steps required for setting up Kerko within a custom Flask application.</p> <p>Tip</p> <p>For a ready-to-use standalone application, you will be better off using KerkoApp instead.</p> <p>Some familiarity with Flask should help you make more sense of the instructions, but should not be absolutely necessary for getting them to work. Let's now build a minimal app:</p> <ol> <li> <p>Create an empty directory <code>myapp</code> where your application reside.</p> </li> <li> <p>Install Kerko in a new virtual environment:</p> POSIXWindows <pre><code>cd myapp\npython -m venv venv\nsource venv/bin/activate\npip install kerko\n</code></pre> <pre><code>cd myapp\npython -m venv venv\nvenv\\Scripts\\activate.bat\npip install kerko\n</code></pre> </li> <li> <p>In the <code>myapp</code> directory, create a file named <code>.env</code>, where parameters    required by Kerko will be configured, with content such as the example below:</p> <pre><code>MYAPP_SECRET_KEY=\"your-random-secret-key\"\nMYAPP_ZOTERO_API_KEY=\"xxxxxxxxxxxxxxxxxxxxxxxx\"\nMYAPP_ZOTERO_LIBRARY_ID=\"9999999\"\nMYAPP_ZOTERO_LIBRARY_TYPE=\"group\"\n</code></pre> <p>Replace each value with a proper one. The meaning of each parameter is outlined below:</p> <ul> <li><code>MYAPP_SECRET_KEY</code>: This parameter is required for generating secure   tokens in web forms. It should have a hard to guess value, and should   really remain secret. For this reason, never add your <code>.env</code> file to a   code repository.</li> <li><code>MYAPP_ZOTERO_API_KEY</code>: Your Zotero API key. See API key creation   instructions.</li> <li><code>MYAPP_ZOTERO_LIBRARY_ID</code>: The identifier of the Zotero library to get   data from. For a personal library the value is your userID, as found on   https://www.zotero.org/settings/keys (you must be logged-in). For a group   library this value is the groupID of the library, as found in the URL of   the library (e.g., the groupID of the library at   https://www.zotero.org/groups/2348869/kerko_demo is <code>\"2348869\"</code>).</li> <li><code>MYAPP_ZOTERO_LIBRARY_TYPE</code>: The type of library to get data from,   either <code>\"user\"</code> for a personal library, or <code>\"group\"</code> for a group library.</li> </ul> <p>A <code>.env</code> file is a good place to store an application's secrets. It is good practice to keep this file only on the machine where the application is hosted, and to never push it to a code repository.</p> </li> <li> <p>Create a file named <code>wsgi.py</code> with the following content:</p> wsgi.py<pre><code>import kerko\nfrom flask import Flask\nfrom flask_babel import Babel\nfrom flask_bootstrap import Bootstrap4\nfrom kerko.composer import Composer\nfrom kerko.config_helpers import config_set, config_update, validate_config\n\napp = Flask(__name__)\n</code></pre> <p>The above imports required modules and creates the Flask application object (<code>app</code>). Then, load the default Kerko configuration, and update it from values set in <code>.env</code>:</p> wsgi.py<pre><code># Initialize app configuration with Kerko's defaults.\nconfig_update(app.config, kerko.DEFAULTS)\n\n# Update app configuration from environment variables.\napp.config.from_prefixed_env(prefix=\"MYAPP\")\n</code></pre> <p>Next, adjust general application parameters to your liking. For example, we can use the <code>config_set</code> function to set the main title of the web application to <code>\"My App\"</code>. This function can be called each time you wish to set a configuration option.</p> wsgi.py<pre><code># Make changes to the Kerko configuration here, if desired.\nconfig_set(app.config, \"kerko.meta.title\", \"My App\")\n</code></pre> <p>Next, have Kerko parse and validate the configuration. Then create the <code>kerko_composer</code> object, which provides key elements needed by Kerko such as the fields to display and search, and the facets made available for filtering:</p> wsgi.py<pre><code># Validate configuration and save its parsed version.\nparse_config(app.config)\n\n# Initialize the Composer object.\napp.config[\"kerko_composer\"] = Composer(app.config)\n\n# Make changes to the Kerko composer object here, if desired.\n</code></pre> <p>Using methods of the <code>Composer</code> class, your application could alter the <code>kerko_composer</code> object if needed, to add, remove or alter fields, facets, sort options, search scopes, record download formats, or badges.</p> <p>Finally, initialize extensions required by Kerko (see the respective documentations of Flask-Babel and Bootstrap-Flask for more details), and register the Kerko blueprint with the application object:</p> wsgi.py<pre><code>babel = Babel(app)\nbootstrap = Bootstrap4(app)\n\napp.register_blueprint(kerko.make_blueprint(), url_prefix=\"/bibliography\")\n</code></pre> <p>The <code>url_prefix</code> argument given above defines the base path for every URL provided by Kerko.</p> <p>Note</p> <p>The full code example is available on GitHub.</p> </li> <li> <p>In the same directory as <code>wsgi.py</code> with your virtual environment active, run    the following shell commands:</p> <pre><code>flask --debug kerko sync\n</code></pre> <p>If you have a large Zotero library and/or large file attachments, that command may take a while to complete. Wait until the command finishes. In production use, this command is usually added to the crontab file for regular execution.</p> <p>The <code>--debug</code> switch is optional. If you use it, some messages will give you an idea of the sync process' progress. If you omit it, the command will run silently unless there are warnings or errors.</p> <p>To list all commands provided by Kerko:</p> <pre><code>flask kerko --help\n</code></pre> </li> <li> <p>Run your application:</p> <pre><code>flask --debug run\n</code></pre> </li> <li> <p>Open http://127.0.0.1:5000/bibliography/ in your browser and explore the    bibliography!</p> </li> </ol> <p>You have just built a really minimal application for Kerko. However, if you are looking at developing a custom Kerko application, we recommend that you still look at KerkoApp for a more advanced starting point. While still small, KerkoApp adds some structure as well as features such as TOML configuration files, translations loading, a syslog logging handler, and error pages.</p>"},{"location":"localization/","title":"Localization","text":"<p>This section is about adapting Kerko for specific regions or languages. For this purpose, the main issues to consider are:</p> <ul> <li>The language of the user interface. Kerko defaults to English but translations   for languages are available. To configure a language other than English, see   <code>BABEL_DEFAULT_LOCALE</code>. If no   translation is available for the desired language, or if the existing   translation needs to be updated, see Translating Kerko   and Translating KerkoApp below.</li> <li>The timezone to apply when displaying times. To configure the timezone, see   <code>BABEL_DEFAULT_TIMEZONE</code>.</li> <li>The language and locale used by Zotero, which determines the display names of   fields, item types, and author types, and can impact citation formatting as   well. To configure this, see <code>kerko.zotero.locale</code>.</li> <li>The language analysis applied by the Whoosh search engine. To configure this,   see <code>kerko.search.whoosh_language</code>.</li> </ul>"},{"location":"localization/#translating-kerko","title":"Translating Kerko","text":"<p>Kerko translations are managed with Babel.</p> <p>The following commands should be executed from the root Kerko directory (the one that contains <code>babel.cfg</code>), and the virtual environment must have been activated beforehand.</p> <p>Create or update the PO template (POT) file. Replace <code>CURRENT_VERSION</code> with the current Kerko version:</p> <pre><code>pybabel extract -F babel.cfg -o src/kerko/translations/kerko.pot --project=Kerko --version=CURRENT_VERSION --copyright-holder=\"Kerko Contributors\" src/kerko\n</code></pre> <p>Create a new PO file (for a new locale) based on the POT file. Replace <code>YOUR_LOCALE</code> with the appropriate language code, e.g., <code>de</code>, <code>es</code>, <code>fr</code>:</p> <pre><code>pybabel init -l YOUR_LOCALE -D kerko -i src/kerko/translations/kerko.pot -d src/kerko/translations\n</code></pre> <p>Update an existing PO file based on the POT file:</p> <pre><code>pybabel update -l YOUR_LOCALE -D kerko -i src/kerko/translations/kerko.pot -d src/kerko/translations\n</code></pre> <p>Compile MO files:</p> <pre><code>pybabel compile -l YOUR_LOCALE -D kerko -d src/kerko/translations --statistics\n</code></pre> <p>Contributing your translation</p> <p>You are welcome to contribute your translation. See Submitting a translation. It is only thanks to user contributions that Kerko is available in multiple languages.</p>"},{"location":"localization/#translating-kerkoapp","title":"Translating KerkoApp","text":"<p>Although most user interface messages come from Kerko, KerkoApp also has messages of its own, and thus its own separate translation file.</p> <p>KerkoApp translations are managed with Babel.</p> <p>The following commands should be executed from the root KerkoApp directory (the one that contains <code>babel.cfg</code>), and the virtual environment must have been activated beforehand.</p> <p>Create or update the PO file template (POT). Replace <code>CURRENT_VERSION</code> with your current KerkoApp version:</p> <pre><code>pybabel extract -F babel.cfg -o kerkoapp/translations/messages.pot --project=KerkoApp --version=CURRENT_VERSION --copyright-holder=\"Kerko Contributors\" kerkoapp\n</code></pre> <p>Create a new PO file (for a new locale) based on the POT file. Replace <code>YOUR_LOCALE</code> with the appropriate language code, e.g., <code>de</code>, <code>es</code>, <code>it</code>:</p> <pre><code>pybabel init -l YOUR_LOCALE -i kerkoapp/translations/messages.pot -d kerkoapp/translations\n</code></pre> <p>Update an existing PO file based on the POT file:</p> <pre><code>pybabel update -l YOUR_LOCALE -i kerkoapp/translations/messages.pot -d kerkoapp/translations\n</code></pre> <p>Compile MO files:</p> <pre><code>pybabel compile -l YOUR_LOCALE -d kerkoapp/translations\n</code></pre>"},{"location":"synchronization/","title":"Synchronization","text":"<p>Kerko synchronizes its data from Zotero through a 3-step process:</p> <ol> <li>Update a cache of the Zotero library.</li> <li>Update the search index from the cache.</li> <li>Download file attachments from Zotero.</li> </ol> <p>The first step is an incremental update of the cache, which is a local copy of the library. To this end, Kerko uses the Zotero API to request items and collections from the library on zotero.org. Unless the library is getting synchronized for the first time by Kerko, this will only request new and changed items from Zotero in order to reduce the number of API requests.</p> <p>The second step reads data from the cache to update the search index. If the cache has changed since the last update, a full update of the search index is performed. No Zotero API calls are made during this step. Any changes to the search index are only committed at the end of this step, thus while the update is taking place users still see the data as it was prior to the synchronization run.</p> <p>The third and last step reads the list of file attachments from the search index, with their MD5 hashes. It compares the hashes with those of the available local copies of the files, and downloads new or changed files from Zotero. It also deletes any local files that may no longer be used.</p> <p>Usually, all synchronization steps should be executed. But under certain circumstances it can be useful to run a specific step alone. For example, after changing certain configuration settings, instead of cleaning all data and performing a lengthy full synchronization from Zotero, one may clean just the search index and rebuild it from the cache.</p> <p>Note</p> <p>The synchronization process is unidirectional, where Kerko pulls data from Zotero. Kerko will never try to write anything to your Zotero library.</p>"},{"location":"synchronization/#command-line-interface-cli","title":"Command line interface (CLI)","text":"<p>Kerko provides an integration with the Flask command line interface. The <code>flask</code> command will work with your virtual environment active.</p> <p>Before running a command, go to the application's directory (where the <code>wsgi.py</code> file is found). That is the easiest way to help Flask discover the application.</p> <p>Some frequently used commands are:</p> <code>flask kerko --help</code> <p>Lists all commands provided by Kerko.</p> <code>flask kerko sync</code> <p>Synchronizes everything: the cache (from Zotero), the search index (from the   cache), the attachments (from files in Zotero, based on list in search index).</p> <p>Tip: Making commands more verbose</p> <p>The <code>--debug</code> option may be used with any Flask command and will cause Kerko to output more information. It will tell quite a bit more about what is happening during the synchronization process. For example:</p> <pre><code>flask --debug kerko sync\n</code></pre> <code>flask kerko sync --help</code> <p>Shows help specifically about the <code>sync</code> command:</p> <code>flask kerko sync index</code> <p>Synchronizes just the search index (from the cache).</p> <code>flask kerko sync cache --full</code> <p>When possible, the synchronization process performs an incremental update of   just the new or changed items. Here, the <code>--full</code> option forces a full   synchronization of the cache, even if no or just some items have been updated   since the last synchronization of the cache.</p> <p>This can be useful after changing certain configuration parameters.</p> <code>flask kerko clean everything</code> <p>Deletes all of Kerko's data: cache, search index, attachments.</p> <code>flask kerko clean --help</code> <p>Shows help about the clean command.</p> <code>flask kerko clean cache</code> <p>Deletes just the cache. A subsequent execution of <code>flask kerko sync</code> will   perform a full update from Zotero, but it will not re-download all file   attachments.</p> <p>This does not affect the search index. Thus, if the index was built before a <code>clean cache</code>, users will still be able to access the bibliography using the Kerko web interface.</p> <code>flask kerko clean index</code> <p>Deletes just the search index. The bibliography will become unavailable to the   Kerko web interface until the index gets synchronized again.</p> <p>It can be necessary to use this command after changing certain configuration parameters, and you will usually want to run <code>flask kerko sync index</code> immediately after.</p> <code>flask kerko config</code> <p>Output a consolidated view of all configuration parameters, from all of your   configuration files, and including the defaults provided by Kerko that you may   not have explicitly configured.</p>"},{"location":"synchronization/#monitoring-data-synchronization","title":"Monitoring data synchronization","text":"<p>Kerko provides a web API endpoint that you could use to monitor data synchronization.</p> <p>In the description below, <code>BASE_URL</code> should be replaced with the protocol, domain, port, and Kerko URL path prefix that are relevant to your installation, e.g., <code>https://example.com/bibliography</code>.</p> <p>The web API endpoint is:</p> <code>BASE_URL/api/last-sync</code> <p>Returns a JSON object with information about the last synchronization from   Zotero. If no sync has been performed yet, it returns an empty JSON object,   otherwise the returned object contains the following values:</p> <code>hours_ago</code> <p>Number of hours since the last sync.</p> <code>when</code> <p>ISO 8601 date string with the date and time of the last sync.</p> Sample JSON output<pre><code>{\n  \"hours_ago\": 17.029,\n  \"when\": \"2023-05-24T11:10:29.093335-04:00\"\n}\n</code></pre>"},{"location":"troubleshooting/","title":"Troubleshooting","text":""},{"location":"troubleshooting/#no-such-command-kerko-error-when-running-flask","title":"No such command \"kerko\" error when running Flask","text":"<p>Make sure to run the <code>flask</code> command from the application's directory (where the <code>wsgi.py</code> file is found).</p> <p>To run it from other directories, you could use the <code>--app</code> option, or to set the <code>FLASK_APP</code> environment variable. See application discovery for details.</p> <p>For example:</p> <pre><code>flask --app=/path/to/kerkoapp/wsgi:app kerko sync\n</code></pre>"},{"location":"troubleshooting/#configuration-parameter-change-has-no-effect","title":"Configuration parameter change has no effect","text":"<p>Restart the application. This is required for any configuration change to take effect.</p> <p>If the change still appears to have no effect after a restart, use the following command to verify that the desired parameter value is actually being used:</p> <pre><code>flask --debug kerko config\n</code></pre> <p>If the parameter's value is not the expected one, check your configuration files. If you are uncertain about which configuration files are being loaded by the application, check the first few lines printed by the above command; these list the TOML files in their loading order. Remember that a later file can override values set in a previous one. If you are still unable to trace the source of an incorrect parameter value, check your environment variables. Environment variables can override parameter values set in TOML configuration files.</p> <p>If, on the other hand, the parameter's value is the desired one, then review the documentation for that parameter. Make sure you understand the effect of the parameter value, and check for any notes or warnings. Some parameters require a rebuild of the cache or the search index to become effective.</p>"},{"location":"troubleshooting/#custom-application-conflicting-package-versions-with-standard-installation","title":"Custom application: Conflicting package versions with standard installation","text":"<p>The <code>requirements/run.txt</code> file specifies a precise version for each required package, ensuring consistent results with the last environment KerkoApp was tested with. If some of these packages are already present in your Python environment, their versions are likely to be different and some Python code outside KerkoApp might require those versions. In that case, try replacing <code>run.txt</code> with <code>run.in</code> in the install command:</p> <pre><code>pip install -r requirements/run.in\n</code></pre> <p>Requirements in <code>run.in</code> are more flexible regarding the versions. If you still have version conflicts with those requirements, you'll have to find out which version to use, checking that it is compatible with both KerkoApp and your other Python code.</p>"},{"location":"upgrading/","title":"How to upgrade","text":"<p>Before attempting any upgrade, it is highly recommended that you do a backup of all of your code, configuration files, data files, and Python virtual environment.</p>"},{"location":"upgrading/#from-10x-to-11x-or-12x","title":"From 1.0.x to 1.1.x or 1.2.x","text":""},{"location":"upgrading/#kerkoapp","title":"KerkoApp","text":"<p>The instructions below make the assumption that you have cloned KerkoApp from its Git repository.</p> <ul> <li>Go to the KerkoApp directory.</li> <li> <p>Get the desired version of KerkoApp. You may check the list of available   versions. For version 1.1.0, for example, replace   <code>VERSION</code> with <code>1.1.0</code> in the command below:</p> <pre><code>git fetch &amp;&amp; git checkout VERSION\n</code></pre> </li> <li> <p>Activate your Python virtual environment.</p> </li> <li> <p>Install Python dependencies:</p> <pre><code>pip install --force-reinstall -r requirements/run.txt\n</code></pre> </li> <li> <p>Adapt your configuration file:</p> <ul> <li>Make sure the <code>kerko.feeds.fields</code> parameter is either omitted or has at   least the following values: <code>[\"id\", \"data\", \"item_fields\"]</code>.</li> </ul> </li> <li> <p>Rebuild your search index using the following commands:</p> <pre><code>flask kerko clean index\nflask kerko sync index\n</code></pre> </li> <li> <p>Restart the application.</p> </li> </ul>"},{"location":"upgrading/#custom-applications","title":"Custom applications","text":"<p>If you have a custom application, the following changes will need to be applied:</p> <ul> <li> <p>The application is now responsible for instantiating the blueprint by calling   <code>kerko.make_blueprint()</code>. Any previous uses of the global <code>kerko.blueprint</code>   object must be replaced, as Kerko no longer provides it. If registration was   your application's only use of that object, the change could look like:</p> Before<pre><code>app.register_blueprint(kerko.blueprint, url_prefix='/bibliography')\n</code></pre> After<pre><code>app.register_blueprint(kerko.make_blueprint(), url_prefix='/bibliography')\n</code></pre> <p>... where <code>app</code> is the <code>Flask</code> object.</p> </li> </ul>"},{"location":"upgrading/#from-09-to-10x","title":"From 0.9 to 1.0.x","text":"<p>Version 1.0.x brings significant changes on how Kerko can be configured. Before you attempt an upgrade, reading Configuration basics is a must.</p>"},{"location":"upgrading/#kerkoapp_1","title":"KerkoApp","text":"<p>The instructions below make the assumption that you have cloned KerkoApp from its Git repository.</p> <ul> <li>Go to the KerkoApp directory.</li> <li> <p>Rename the default branch of your local KerkoApp repository:</p> <pre><code>git branch -m master main\ngit fetch origin\ngit branch -u origin/main main\ngit remote set-head origin -a\n</code></pre> </li> <li> <p>Get the desired version of KerkoApp. You may check the list of available   versions. For version 1.0.0, for example, replace   <code>VERSION</code> with <code>1.0.0</code> in the command below:</p> <pre><code>git checkout VERSION\n</code></pre> </li> <li> <p>Activate your Python virtual environment.</p> </li> <li> <p>Install Python dependencies:</p> <pre><code>pip install --force-reinstall -r requirements/run.txt\n</code></pre> </li> <li> <p>Rename the <code>.env</code> file to <code>dotenv.old</code>. We no longer want KerkoApp to use that   file, but it might be useful to keep it as reference while we migrate the   configuration.</p> </li> <li>Create two files, <code>.secrets.toml</code> and <code>config.toml</code>, in the KerkoApp   directory, i.e., the directory where <code>wsgi.py</code> is found.</li> <li>Copy the <code>SECRET_KEY</code> and <code>KERKO_ZOTERO_API_KEY</code> lines from <code>dotenv.old</code> into   <code>.secrets.toml</code>. In <code>.secrets.toml</code>, rename the <code>KERKO_ZOTERO_API_KEY</code>   parameter to <code>ZOTERO_API_KEY</code>. For each of the two parameters, make sure the   value following the equal sign (<code>=</code>) is surrounded by double quotes (<code>\"</code>). To   ascertain the syntax, you may have a look at the <code>sample.secrets.toml</code> file   provided by KerkoApp.</li> <li>Copy the remaining lines from <code>dotenv.old</code> to <code>config.toml</code>. For each   parameter, use the list below to determine if something special needs to be   done to migrate it. Almost all configuration parameters have been renamed   and/or moved into a hierarchical structure (indicated by an arrow (\u2192)). Check   the parameter values too as the syntax of a TOML file is slightly different   from that of a <code>.env</code> file, e.g., in TOML string values must be surrounded by   double quotes (<code>\"</code>), and booleans values must be either <code>true</code> or <code>false</code>   (lowercase, no quotes). Refer to the parameters   documentation for additional information, and have a look   at the <code>sample.config.toml</code> file provided by KerkoApp.<ul> <li><code>DEBUG</code>: Remove. Debug mode is now activated with the <code>--debug</code> command   line option.</li> <li><code>FLASK_APP</code>: Probably not needed anymore. In doubt, please refer to the   Flask documentation on application   discovery.   If you do need this variable, then a <code>.env</code> file could be the right place.   It will not work from a TOML file. Note also that the application is now   referenced as <code>wsgi.app</code> instead of <code>kerkoapp.app</code>.</li> <li><code>FLASK_ENV</code>: Remove. Flask 2.3 stopped supporting it. Debug mode is now   activated with the <code>--debug</code> command line option.</li> <li><code>KERKO_BOOTSTRAP_VERSION</code> \u2192 <code>kerko.assets.bootstrap_version</code></li> <li><code>KERKO_CSL_STYLE</code> \u2192 <code>kerko.zotero.csl_style</code></li> <li><code>KERKO_COMPOSER</code> \u2192 <code>kerko_composer</code></li> <li><code>KERKO_DATA_DIR</code> \u2192 <code>DATA_PATH</code>. Now optional, relative to the instance   path, and defaulting to <code>kerko</code> instead of <code>data/kerko</code>.</li> <li><code>KERKO_DOWNLOAD_ATTACHMENT_NEW_WINDOW</code> \u2192 <code>kerko.features.download_attachment_new_window</code></li> <li><code>KERKO_DOWNLOAD_CITATIONS_LINK</code> \u2192 <code>kerko.features.download_results</code></li> <li><code>KERKO_DOWNLOAD_CITATIONS_MAX_COUNT</code> \u2192 <code>kerko.features.download_results_max_count</code></li> <li><code>KERKO_FEEDS</code> \u2192 <code>kerko.feeds.formats</code></li> <li><code>KERKO_FEEDS_FIELDS</code> \u2192 <code>kerko.feeds.fields</code></li> <li><code>KERKO_FEEDS_MAX_DAYS</code> \u2192 <code>kerko.feeds.max_days</code></li> <li><code>KERKO_FEEDS_REJECT_ANY</code> \u2192 <code>kerko.feeds.reject_any</code></li> <li><code>KERKO_FEEDS_REQUIRE_ANY</code> \u2192 <code>kerko.feeds.require_any</code></li> <li><code>KERKO_FULLTEXT_SEARCH</code> \u2192 <code>kerko.search.fulltext</code></li> <li><code>KERKO_HIGHWIREPRESS_TAGS</code> \u2192 <code>kerko.meta.highwirepress_tags</code></li> <li><code>KERKO_JQUERY_VERSION</code> \u2192 <code>kerko.assets.jquery_version</code></li> <li><code>KERKO_PAGE_LEN</code> \u2192 <code>kerko.pagination.page_len</code></li> <li><code>KERKO_PAGER_LINKS</code> \u2192 <code>kerko.pagination.pager_links</code></li> <li><code>KERKO_POPPER_VERSION</code> \u2192 <code>kerko.assets.popper_version</code></li> <li><code>KERKO_PRINT_CITATIONS_LINK</code> \u2192 <code>kerko.features.print_results</code></li> <li><code>KERKO_PRINT_CITATIONS_MAX_COUNT</code> \u2192 <code>kerko.features.print_results_max_count</code></li> <li><code>KERKO_PRINT_ITEM_LINK</code> \u2192 <code>kerko.features.print_item</code></li> <li><code>KERKO_RELATIONS_INITIAL_LIMIT</code> \u2192 <code>kerko.features.relations_initial_limit</code></li> <li><code>KERKO_RELATIONS_LINKS</code> \u2192 <code>kerko.features.relations_links</code></li> <li><code>KERKO_RELATIONS_SORT</code> \u2192 <code>kerko.features.relations_sort</code></li> <li><code>KERKO_RESULTS_ABSTRACTS</code> \u2192 <code>kerko.features.results_abstracts</code></li> <li><code>KERKO_RESULTS_ABSTRACTS_MAX_LENGTH</code> \u2192 <code>kerko.features.results_abstracts_max_length</code></li> <li><code>KERKO_RESULTS_ABSTRACTS_MAX_LENGTH_LEEWAY</code> \u2192 <code>kerko.features.results_abstracts_max_length_leeway</code></li> <li><code>KERKO_RESULTS_ABSTRACTS_TOGGLER</code> \u2192 <code>kerko.features.results_abstracts_toggler</code></li> <li><code>KERKO_RESULTS_ATTACHMENT_LINKS</code> \u2192 <code>kerko.features.results_attachment_links</code></li> <li><code>KERKO_RESULTS_FIELDS</code> \u2192 <code>kerko.search.result_fields</code></li> <li><code>KERKO_RESULTS_URL_LINKS</code> \u2192 <code>kerko.features.results_url_links</code></li> <li><code>KERKO_TEMPLATE_ATOM_FEED</code> \u2192 <code>kerko.templates.atom_feed</code></li> <li><code>KERKO_TEMPLATE_BASE</code> \u2192 <code>kerko.templates.base</code></li> <li><code>KERKO_TEMPLATE_ITEM</code> \u2192 <code>kerko.templates.item</code></li> <li><code>KERKO_TEMPLATE_LAYOUT</code> \u2192 <code>kerko.templates.layout</code></li> <li><code>KERKO_TEMPLATE_SEARCH</code> \u2192 <code>kerko.templates.search</code></li> <li><code>KERKO_TEMPLATE_SEARCH_ITEM</code> \u2192 <code>kerko.templates.search_item</code></li> <li><code>KERKO_TITLE</code> \u2192 <code>kerko.meta.title</code></li> <li><code>KERKO_USE_TRANSLATIONS</code>: Remove.</li> <li><code>KERKO_WHOOSH_LANGUAGE</code> \u2192 <code>kerko.search.whoosh_language</code></li> <li><code>KERKO_WITH_JQUERY</code> \u2192 <code>kerko.assets.with_jquery</code></li> <li><code>KERKO_WITH_POPPER</code> \u2192 <code>kerko.assets.with_popper</code></li> <li><code>KERKO_ZOTERO_API_KEY</code> \u2192 <code>ZOTERO_API_KEY</code></li> <li><code>KERKO_ZOTERO_BATCH_SIZE</code> \u2192 <code>kerko.zotero.batch_size</code></li> <li><code>KERKO_ZOTERO_LIBRARY_ID</code> \u2192 <code>ZOTERO_LIBRARY_ID</code></li> <li><code>KERKO_ZOTERO_LIBRARY_TYPE</code> \u2192 <code>ZOTERO_LIBRARY_TYPE</code></li> <li><code>KERKO_ZOTERO_LOCALE</code> \u2192 <code>kerko.zotero.locale</code></li> <li><code>KERKO_ZOTERO_MAX_ATTEMPTS</code> \u2192 <code>kerko.zotero.max_attempts</code></li> <li><code>KERKO_ZOTERO_WAIT</code> \u2192 <code>kerko.zotero.wait</code></li> <li><code>KERKOAPP_CHILD_EXCLUDE_RE</code> \u2192 <code>kerko.zotero.child_exclude_re</code></li> <li><code>KERKOAPP_CHILD_INCLUDE_RE</code> \u2192 <code>kerko.zotero.child_include_re</code></li> <li><code>KERKOAPP_COLLECTION_FACETS</code> \u2192 <code>kerko.facets.*</code>. See sub-parameters <code>type</code>   (set it to <code>\"collection\"</code>), <code>collection_key</code>, <code>weight</code>, and <code>title</code>.</li> <li><code>KERKOAPP_EXCLUDE_DEFAULT_BADGES</code>: Remove. There is no replacement since   Kerko does not provide any default badges at this point.</li> <li><code>KERKOAPP_EXCLUDE_DEFAULT_CITATION_FORMATS</code> \u2192 <code>kerko.citation_formats.*</code>.   See sub-parameter <code>enable</code>.</li> <li><code>KERKOAPP_EXCLUDE_DEFAULT_FACETS</code> \u2192 <code>kerko.facets.*</code>. See sub-parameter   <code>enable</code>.</li> <li><code>KERKOAPP_EXCLUDE_DEFAULT_FIELDS</code> \u2192 <code>kerko.search_fields.*</code>. See   sub-parameter <code>enable</code>.</li> <li><code>KERKOAPP_EXCLUDE_DEFAULT_SCOPES</code> \u2192 <code>kerko.scopes.*</code>. See sub-parameter   <code>enable</code>.</li> <li><code>KERKOAPP_EXCLUDE_DEFAULT_SORTS</code> \u2192 <code>kerko.sorts.*</code>. See sub-parameter   <code>enable</code>.</li> <li><code>KERKOAPP_FACET_INITIAL_LIMIT_LEEWAY</code> \u2192   <code>kerko.facets.*.initial_limit_leeway</code>. This is now set individually for   each facet, and there is no longer a global parameter.</li> <li><code>KERKOAPP_FACET_INITIAL_LIMIT</code> \u2192 <code>kerko.facets.*.initial_limit</code>. This is   now set individually for each facet, and there is no longer a global   parameter.</li> <li><code>KERKOAPP_ITEM_EXCLUDE_RE</code> \u2192 <code>kerko.zotero.item_exclude_re</code></li> <li><code>KERKOAPP_ITEM_INCLUDE_RE</code> \u2192 <code>kerko.zotero.item_include_re</code></li> <li><code>KERKOAPP_MIME_TYPES</code> \u2192 <code>kerko.zotero.attachment_mime_types</code></li> <li><code>KERKOAPP_TAG_EXCLUDE_RE</code> \u2192 <code>kerko.zotero.tag_exclude_re</code></li> <li><code>KERKOAPP_TAG_INCLUDE_RE</code> \u2192 <code>kerko.zotero.tag_include_re</code></li> <li><code>PROXY_FIX</code> \u2192 <code>kerkoapp.proxy_fix.*</code></li> </ul> </li> <li>If you are using a translated version of Kerko, the default \"Bibliography\"   link of the navigation bar no longer gets translated because it is now defined   by a configuration parameter. To replace it, set the   <code>kerko.link_groups.navbar</code> parameter (see the parameters   documentation for details).</li> <li>If your configuration changes neither the <code>DATA_PATH</code> nor the <code>INSTANCE_PATH</code>   parameters, then rename KerkoApp's <code>data</code> directory to <code>instance</code>.</li> <li>Make sure your WSGI server now references the application as <code>wsgi.app</code> (or   <code>wsgi:app</code>) instead of <code>kerkoapp.app</code> (or <code>kerkoapp:app</code>).</li> <li> <p>Rebuild your search index using the following commands:</p> <pre><code>flask kerko clean index\nflask kerko sync index\n</code></pre> </li> <li> <p>Restart the application.</p> </li> </ul>"},{"location":"upgrading/#custom-templates","title":"Custom templates","text":"<p>Occurrences of parameter names in custom templates will need to be edited. For example:</p> <ul> <li><code>config.KERKO_COMPOSER</code> \u2192 <code>config.kerko_composer</code></li> <li><code>config.KERKO_TITLE</code> \u2192 <code>config.kerko.meta.title</code></li> <li>... for the full list, please refer to the above section.</li> </ul> <p>The following item fields have been renamed. Occurrences of these in your templates will need to be edited:</p> <ul> <li><code>z_dateAdded</code> \u2192 <code>date_added</code></li> <li><code>z_dateModified</code> \u2192 <code>date_modified</code></li> </ul> <p>The following views have been renamed. Occurrences of these in your templates (perhaps in calls to <code>url_for</code>) will need to be edited:</p> <ul> <li><code>item_citation_download</code> \u2192 <code>item_bib_download</code></li> <li><code>search_citation_download</code> \u2192 <code>search_bib_download</code></li> </ul>"},{"location":"upgrading/#custom-applications_1","title":"Custom applications","text":"<p>Configuration initialization and loading has greatly changed. If you have a custom application, it will need to be adapted even if you do not plan to use TOML files. See Creating a custom application for a working example, and refer to the changelog for other breaking changes.</p>"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Introduction","text":"<p>Kerko is a web application component that provides a user-friendly search and browsing interface for sharing a bibliography managed with the Zotero reference manager.</p> <p>The combination of Kerko and Zotero gives you the best of both worlds: a rich but easy to use web interface for end-users of the bibliography, and a well-established and powerful bibliographic reference management tool for individuals or teams working on the bibliography's content.</p>"},{"location":"#how-it-works","title":"How it works","text":"<p>A Kerko-powered bibliography is managed using Zotero, and stored in the cloud on zotero.org, while Kerko itself is incorporated into an application which is installed on a web server. The bibliographic references may reside in a Zotero group library, where multiple users may collaborate to manage the content, or in a Zotero private library. On the web server, Kerko maintains a search index, which is a copy of the Zotero library that is optimized for search. When users interact with the web application, Kerko gets all the required data from that search index, without ever contacting zotero.org. It is through a scheduled task, which runs at regular intervals, that Kerko automatically brings its search index up to date by using the Zotero Web API to retrieve the latest data from zotero.org.</p> <p>Kerko is implemented in Python using the Flask framework. As an application component, Kerko only works when incorporated into a Flask application. Such an application, KerkoApp, is available for you to use, and can be deployed on a web server. KerkoApp can be seen as just a thin layer over Kerko. It might work for you if you like the default appearance, and if the provided configuration options are sufficient for your needs.</p> <p>For more advanced needs, you could consider building a custom application, possibly derived from KerkoApp, where additional customizations could be implemented in Python. In this scenario, it is not recommended that you change Kerko itself, but that you use Kerko's Python API to implement your customizations. Kerko is actually a Flask \"blueprint\" (similar to what some other systems might call a plugin or an extension), which allows a modular architecture where the application integrates and extends Kerko, and possibly other blueprints as well; the Kerko-powered bibliography could be just one component of a larger Flask application.</p>"},{"location":"#demo-site","title":"Demo site","text":"<p>A demo site, which is based on KerkoApp, is available for you to try. You may also view the Zotero library that contains the source data for the demo site.</p>"},{"location":"#sites-using-kerko","title":"Sites using Kerko","text":"<p>The following sites are powered by Kerko:</p> <ul> <li>Bibliographie francophone sur l'archivistique</li> <li>Bibliographie sur l'histoire de Montr\u00e9al</li> <li>Community Knowledge Open Library on English-Speaking Quebec</li> <li>Lipedema Foundation LEGATO Lipedema Library</li> <li>Open Development &amp; Education Evidence Library</li> <li>Rights and Records Knowledge Base</li> <li>The EdTech Hub Evidence Library</li> <li>Transitional Justice Evaluation Tools Reference Library</li> <li>University of Saint Joseph Research Output</li> </ul> <p>Are you using Kerko?</p> <p>If you would like to add your Kerko-powered site to this list, please e-mail us or submit a pull request.</p>"},{"location":"#features","title":"Features","text":"<p>The main features provided by Kerko are:</p> <ul> <li>Faceted search interface: allows exploration of the bibliography both in   search mode and in browsing mode, potentially suiting different user needs,   behaviors, and abilities. For example, users with a prior idea of the topic or   expected results may enter keywords or a more complex query in a search field,   while those who wish to become familiar with the content of the bibliography   or discover new topics may choose to navigate along the proposed facets, to   narrow or broaden their search. Since both modes are integrated into a single   interface, it is possible to combine them.</li> <li>Keyword search features:<ul> <li>Boolean operators:<ul> <li><code>AND</code>: matches items that contain all specified terms. This is the   default relation between terms when no operator is specified, e.g.,   <code>a b</code> is the same as <code>a AND b</code>.</li> <li><code>OR</code>: matches items that contain any of the specified terms, e.g.,   <code>a OR b</code>.</li> <li><code>NOT</code>: excludes items that match the term, e.g., <code>NOT a</code>.</li> <li>Boolean operators must be specified in uppercase and may be translated   in other languages.</li> </ul> </li> <li>Logical grouping (with parentheses), e.g., <code>(a OR b) AND c</code>.</li> <li>Sequence of words (with double quotes), e.g., <code>\"a b c\"</code>. The default   difference between word positions is 1, meaning that an item will match if   it contains the words next to each other, but a different maximum distance   may be selected (with the tilde character), e.g. <code>\"web search\"~2</code> allows   up to 1 word between <code>web</code> and <code>search</code>, meaning it could match <code>web site   search</code> as well as <code>web search</code>.</li> <li>Term boosting (with the caret), e.g., <code>faceted^2 search browsing^0.5</code>   specifies that <code>faceted</code> is twice as important as <code>search</code> when computing   the relevance score of results, while <code>browsing</code> is half as important.   Boosting may be applied to a logical grouping, e.g., <code>(a b)^3 c</code>.</li> <li>Keyword search is case-insensitive, accents are folded, and punctuation is   ignored. To further improve recall (albeit at the cost of precision),   stemming is also performed on terms from most text fields, e.g., title,   abstract, notes. Stemming relieves the user from having to specify all   variants of a word when searching, e.g., terms such as <code>search</code>,   <code>searches</code>, and <code>searching</code> all return the same results. The Snowball   algorithm is used for that purpose.</li> <li>Full-text search: the text content of PDF attachments can be searched.</li> <li>Scope of search: users may choose to search everywhere, in   author/contributor names, in titles, in publication years, in all fields   (i.e., in metadata and notes), or in documents (i.e., in the text content   of attachments). Applications may provide additional choices.</li> </ul> </li> <li>Faceted browsing: allows filtering by topic (Zotero tag), by resource type   (Zotero item type), by publication year, or by resource language. Moreover,   you may define additional   facets   modeled on collections and subcollections; in such case, any collection can be   represented as a facet, and each subcollection as a value within that facet.   By taking advantage of Zotero's ability to assign any given item to multiple   collections, a faceted classification scheme can be designed, including   hierarchical subdivisions within facets.</li> <li>Relevance scoring: provided by the Whoosh library and based on the   BM25F algorithm, which determines how important a term is to a document in   the context of the whole collection of documents, while taking into account   its relation to document structure (in this regard most fields are neutral,   but the score is boosted when a term appears in specific fields, e.g., DOI,   ISBN, ISSN, title, author/contributor). Any keyword search asks the question   \"how well does this document match this query clause?\", which requires   calculating a relevance score for each document. Filtering with facets, on the   other hand, has no effect on the score because it asks \"does this document   match this query clause?\", which leads to a yes or no answer.</li> <li>Sort options: by relevance score (only applicable to keyword search), by   publication date, by author, by title.</li> <li>Citation styles: any from the Zotero Style Repository, or   custom stylesheet defined in the Citation Style Language (stylesheet   must be accessible by URL).</li> <li>Language support: the default language of the user interface is English,   but some translations are provided. Additional   translations may be created using gettext-compatible tools (see Translating   Kerko). Also to consider: locales   supported by the Zotero Data Schema (which provides the names   of fields, item types and author types displayed by Kerko); languages   supported by Whoosh (which provides the search capabilities), i.e., ar, da,   nl, en, fi, fr, de, hu, it, no, pt, ro, ru, es, sv, tr.</li> <li>Semantic markup: pages generated by Kerko embed HTML markup that can be   detected by web crawlers (helping the indexing of your records by search   engines) or by web browsers (allowing users of reference management tools to   easily import metadata in their library). Supported schemes are:<ul> <li>OpenURL COinS, in search results pages and individual   bibliographic record pages. COinS is recognized by many reference   management tools, including the Zotero   Connector browser extension.</li> <li>Highwire Press tags, in the individual bibliographic record pages of book,   conference paper, journal article, report or thesis items. These tags are   recommended for indexing by Google Scholar, and   are recognized by many other databases and reference management tools,   including the Zotero Connector browser extension.</li> </ul> </li> <li>Web feeds: users of news aggregators or feed readers may get updates when   new bibliographic records are added. They may subscribe to the main feed, or   to one or more custom feeds.<ul> <li>The main feed lists the most recently added bibliographic records.</li> <li>Any search page has a related custom feed that lists the most recently   added bibliographic records that match the search criteria. Thus, a user   can obtain a custom feed for a particular area of interest simply by   entering keywords to search and/or selecting filters.</li> <li>Feeds are provided in the Atom syndication format.</li> <li>Basic metadata is provided directly in the feeds, using both Atom and   unqualified Dublin Core elements.</li> <li>An age limit may be configured to exclude older items from the feeds. This   may be useful to bibliographies that are frequently updated and mostly   meant to promote recent literature (all resources still remain visible to   the search interface regardless of their age).</li> </ul> </li> <li>Sitemap: an XML Sitemap is automatically generated, and you   may use it to help search engines discover your bibliographic records.</li> <li>Exporting: users may export individual records as well as complete   bibliographies corresponding to search results. By default, download links are   provided for the RIS and BibTeX formats, but applications may be configured to   export any format supported by the Zotero API.</li> <li>Printing: stylesheets are provided for printing individual bibliographic   records as well as lists of search results. When printing search results, all   results get printed (not just the current page of results).</li> <li>Notes and attachments: notes, attached files, and attached links to URIs   are synchronized from zotero.org and made available to users of the   bibliography. Regular expressions may be used to include or exclude such child   items from the bibliography, based on their tags.</li> <li>DOI, ISBN and ISSN resolver: items that have such identifier in your   library can be referenced by appending their identifier to your Kerko site's   base URL.</li> <li>Relations: bibliographic record pages show links to related items, if any.   You may define such relations using Zotero's Related field. Moreover, Kerko   adds the Cites and Cited by relation types, which can be managed in Zotero   through notes (see    guide). Custom   applications can add more types of relations if desired.</li> <li>Pages: basic informational pages can be defined using content from Zotero   standalone notes (see   guide).</li> <li>Badges: custom applications can have icons conditionally displayed next to   items.</li> <li>Responsive design: the simple default implementation works on large   monitors as well as on small screens. It is based on Bootstrap.</li> <li>Google Analytics integration: just provide a Google Analytics stream ID to   have Kerko automatically include the tracking code into its pages.</li> <li>Integration: as a Flask blueprint, Kerko can be   integrated into any Flask application. For a standalone application, however,   you may simply install   KerkoApp.</li> <li>Customizable front-end: applications may partly or fully replace the   default templates, scripts and stylesheets with their own.</li> <li>Command line interface (CLI): Kerko provides commands for synchronizing or   deleting its data.</li> </ul> <p>KerkoApp is a standalone application built around Kerko. It inherits all of Kerko's features and it provides a few additions of its own:</p> <ul> <li>Configuration files: allow separation of configuration from code and   enable the Twelve-factor App methodology. Environment   variables and TOML configuration files are supported. Secrets,   server-specific parameters, and general parameters can be configured in   separate files.</li> <li>Page templates for common HTTP errors.</li> <li>Syslog logging handler (for Unix environments).</li> </ul>"},{"location":"#requirements","title":"Requirements","text":"<p>Kerko requires Python 3.8 or later.</p> <p>Required Python packages will be automatically installed when installing Kerko. The main ones are:</p> <ul> <li>Babel: utilities for internationalization and localization.</li> <li>Bootstrap-Flask: helper for integrating Bootstrap.</li> <li>Click: command line interface creation kit.</li> <li>Flask: web application framework.</li> <li>Flask-Babel: integration of Flask and Babel.</li> <li>Flask-WTF: integration of Flask and WTForms.</li> <li>Jinja2: template engine.</li> <li>Pydantic: configuration parsing and validation.</li> <li>Pyzotero: Python client for the Zotero API.</li> <li>w3lib: URL and HTML manipulation utilities.</li> <li>Werkzeug: WSGI web application library (also required by Flask).</li> <li>Whoosh: pure Python full-text indexing and searching library.</li> <li>WTForms: web forms validation and rendering library.</li> </ul> <p>The following front-end resources are loaded from CDNs by Kerko's default templates (but could be completely removed or replaced in custom templates):</p> <ul> <li>Bootstrap: front-end component library for web applications.</li> <li>FontAwesome: beautiful open source icons.</li> <li>jQuery: JavaScript library (required by Bootstrap).</li> <li>Popper.js: JavaScript library for handling tooltips, popovers, etc. (used by   Bootstrap).</li> </ul>"},{"location":"#known-limitations","title":"Known limitations","text":"<p>Before choosing Kerko for your project, you might want to review the following known limitations of Kerko:</p> <ul> <li>The system can handle relatively large bibliographies (it has been tested with   over 15,000 references), but the number of distinct facet values can have more   impact on response times than the number of records. For the best response   times, it is recommended to limit the number of distinct facet values under a   few hundreds.</li> <li>Kerko can only manage a single bibliography per application.</li> <li>Although Kerko can be integrated in a multilingual web application were the   visitor may select a language, Zotero does not provide a way to manage tags or   collections in multiple languages. Thus, there is no easy way for Kerko to   provide those names in the user's selected language.</li> <li>Whoosh does not provide much out-of-the-box support for non-Western languages.   Therefore, search might not work very well with such languages.</li> <li>Zotero is the sole reference management tool supported as a back-end to Kerko.</li> </ul>"},{"location":"about/","title":"About","text":"<p>Kerko was inspired by prior work accomplished by Whisky Echo Bravo on two projects:</p> <ul> <li>Bibliographie sur l\u2019histoire de   Montr\u00e9al, developed in 2014 by David   Lesieur and Patrick Fournier, of Whisky Echo Bravo, for the Laboratoire   d'histoire et de patrimoine de Montr\u00e9al (Universit\u00e9 du   Qu\u00e9bec \u00e0 Montr\u00e9al, Canada). The original custom application got a few minor   updates over time, and was eventually replaced with Kerko in 2024.</li> <li>Bibliography on English-speaking Quebec,   developed in 2017 by David Lesieur, for the Quebec English-Speaking   Communities Research Network   (QUESCREN) (Concordia   University, Canada).</li> </ul> <p>In 2019, Whisky Echo Bravo was asked to work on another similar project. That made it clear that a general solution would benefit many organizations. However, software from the prior projects had to be rewritten in order to be more adaptable to a variety of needs. That led to Kerko, whose initial development was made possible through the following project:</p> <ul> <li>Bibliographie francophone sur   l'archivistique, funded by the   Association internationale des archives francophones   (AIAF)   and hosted by the \u00c9cole de biblioth\u00e9conomie et des sciences de l\u2019information   (EBSI) (Universit\u00e9 de Montr\u00e9al, Canada).</li> </ul> <p>Since then, Kerko has continued to evolve, thanks to work by Whisky Echo Bravo and other contributors, often through funding provided by organizations needing new features or customizations of Kerko.</p>"},{"location":"about/#design-choices","title":"Design choices","text":"<p>Here are some of the design choices that have guided the development of Kerko so far:</p> <ul> <li>Do not build back-end software. Let Zotero manage the data.</li> <li>Allow Kerko to integrate into richer web applications.</li> <li>Only provide features that pertain to the exploration of a bibliography.   Other features, even when they are common to many web sites, do not belong to   Kerko and should be left to the applications to implement.</li> <li>Use a lightweight framework to avoid carrying many features that are not   needed by Kerko (Flask was selected for this reason).</li> <li>Use pure Python dependencies to keep installation and deployment simple (Hence   the use of Whoosh for search, for example, instead of Elasticsearch or Solr).</li> <li>Use a classic server-side rendering architecture. Keep it simple and avoid   asset management when possible.</li> </ul>"},{"location":"about/#etymology","title":"Etymology","text":"<p>The name Zotero reportedly derives from the Albanian word zot\u00ebroj, which means \"to learn something extremely well, that is to master or acquire a skill in learning\" (Source: Mark Dingemanse, 2008, Etymology of Zotero).</p> <p>The name Kerko is a nod to Zotero as it takes a similar etymological route: it derives from the Albanian word k\u00ebrkoj, which means \"to ask, to request, to seek, to look for, to demand, to search\" and seems fit to describe a search tool.</p>"},{"location":"changelog/","title":"Changelog","text":"<p>Before doing an upgrade, please check the \"How to upgrade\" section of the Kerko documentation.</p>"},{"location":"changelog/#120-2024-08-03","title":"1.2.0 (2024-08-03)","text":"<p>New features:</p> <ul> <li>Add the \"Resource language\" facet. It is disabled by default, but can be   enabled by setting the <code>kerko.facets.language.enabled</code> configuration parameter   to <code>true</code>. By default, Kerko will try to normalize the language names to make   the facet more usable; see <code>kerko.facets.language.</code> in the configuration   parameters documentation for details.</li> </ul> <p>Removed features:</p> <ul> <li>Custom translation management commands that depended on Setuptools and   <code>setup.py</code> have been removed. Equivalent <code>pybabel</code> commands can be used   instead (see the updated Localization section of the documentation).</li> </ul> <p>Other changes:</p> <ul> <li>Change the default configuration for some parameters:<ul> <li><code>kerko.facets.item_type.initial_limit</code>, now <code>10</code> instead of <code>0</code>.</li> <li><code>kerko.facets.item_type.initial_limit_leeway</code>, now <code>4</code> instead of <code>2</code>.</li> <li><code>kerko.facets.link.initial_limit_leeway</code>, now <code>0</code> instead of <code>2</code>.</li> <li><code>kerko.facets.tag.initial_limit</code>, now <code>10</code> instead of <code>0</code>.</li> <li><code>kerko.facets.tag.initial_limit_leeway</code>, now <code>4</code> instead of <code>2</code>.</li> <li><code>kerko.facets.year.initial_limit_leeway</code>, now <code>0</code> instead of <code>2</code>.</li> </ul> </li> <li>Update Portuguese translations. Thanks to Gon\u00e7alo Cordeiro.</li> <li>Move project metadata from <code>setup.cfg</code> to <code>pyproject.toml</code>.</li> <li>Build distribution package with Hatch instead of Setuptools.</li> <li>Use dynamic package versioning so that installers such as <code>pip</code> do not mistake   a development version for a previously published version. Version numbers are   now extracted from the tags and revisions of the Git repository.</li> <li>Reduce XML sitemaps size.</li> <li>Improve documentation.</li> </ul> <p>Deprecated APIs:</p> <ul> <li>The Python variable <code>kerko.TRANSLATION_DIRECTORIES</code> is deprecated and will be   removed in Kerko 2.x. The variable <code>kerko.TRANSLATION_DIRECTORY</code> should be   used instead, and its type is a string instead of a list. If you are using a   custom application, please adapt it accordingly (you may check KerkoApp's   <code>__init__.py</code> for an example).</li> </ul>"},{"location":"changelog/#110-2023-12-23","title":"1.1.0 (2023-12-23)","text":"<p>Features:</p> <ul> <li>Add the \"Publication year\" search scope. It is enabled by default, but can be   disabled by setting the <code>kerko.scopes.pubyear.enabled</code> configuration parameter   to <code>false</code>.</li> <li>Add new configuration parameter <code>kerko.pages.*.</code> for defining content pages   whose content come from selected Zotero standalone notes.</li> <li>Add a <code>\"page\"</code> type for the <code>kerko.link_groups.*.</code> configuration table, to   allow the creation of links to content pages.</li> <li>Add configuration parameters <code>kerko.performance.whoosh_index_memory_limit</code> and   <code>kerko.performance.whoosh_index_processors</code> to give some control over the   Whoosh search engine's indexing performance.</li> <li>Allow italic, bold, subscript, superscript and small-caps on Zotero fields   (such as titles and abstracts) where rich text formatting   tags are used.</li> <li>Add Spanish translation. Thanks to Albert   Ormazabal.</li> </ul> <p>Bug fixes:</p> <ul> <li>Fix item title missing from item pages and from Atom feeds when item type is   Case, Email, or Statute.</li> <li>Fix incorrect sorting of search results by title when item type is Case,   Email, or Statute.</li> <li>Fix incorrect escaping of HTML markup in the HTML content elements of Atom   feeds.</li> <li>Fix incorrect scope, analyzer, and boost factor associated with the <code>caseName</code>   search field.</li> <li>Fix crash when a facet specifies no sort order.</li> <li>Fix crash on empty search result pages when configuration parameter   <code>kerko.features.print_results_max_count</code> is greater than zero.</li> <li>Fix badges displayed too close to title on item pages.</li> </ul> <p>Other changes:</p> <ul> <li>Add <code>rel=\"noopener\"</code> to <code>target=\"_blank\"</code> links.</li> <li>Add <code>rel=\"noreferrer\"</code> to links derived from Zotero library data, e.g.,   user-provided URLs, DOIs, link attachments.</li> <li>Reduce the default memory limit for Whoosh's index writer from 256 MB to 128   MB. This can prevent swapping with large libraries on small machines. The   default limit may now be changed with the   <code>kerko.performance.whoosh_index_memory_limit</code> parameter.</li> <li>Improve speed of single-item search pages, i.e., search pages having the   <code>page-len=1</code> URL parameter. This is achieved through removal of the <code>id</code>   parameter from pagination URLs. Obtaining those ids was requiring extra   processing. Instead, the <code>id</code> parameter is now added through the browser   History API when a pagination link is visited.</li> <li>Add support for Python 3.12.</li> <li>Replace pylint, pycodestyle, pydocstyle with Ruff.</li> <li>Replace Yapf with Ruff formatter. Reformat whole code base.</li> <li>Add pre-commit hooks. Run Ruff and other code checks on pre-commit.</li> <li>Add template blocks to facilitate theming.</li> <li>Improve documentation.</li> </ul> <p>Backwards incompatible changes:</p> <ul> <li>Drop support for Python 3.7 (EOL).</li> </ul> <p>Possibly backwards incompatible changes (more or less internal API changes):</p> <ul> <li>Kerko no longer provides a <code>kerko.blueprint</code> global object. Applications must   now instantiate the blueprint by calling <code>kerko.make_blueprint()</code> before   registering it. This prevents attempts to mutate the object after its   registration, especially in tests.</li> <li>Upgrade many dependencies, including new major versions of Flask (3.x),   Flask-Babel (4.x), Werkzeug (3.x).</li> <li><code>kerko.extractors.TransformerExtractor</code> no longer applies transformers on   <code>None</code> values. If you need a transformer to process a <code>None</code> value (Kerko   itself has no such transformer), you now have to set the new <code>skip_none_value</code>   argument to <code>False</code> when instantiating the extractor.</li> </ul>"},{"location":"changelog/#100-2023-07-24","title":"1.0.0 (2023-07-24)","text":"<p>Features:</p> <ul> <li>Add new configuration parameter <code>kerko.features.download_item</code>.</li> </ul> <p>Bug fixes:</p> <ul> <li>Fix Gunicorn not exiting if the default TOML config has errors (use the   <code>errno.EINTR</code> error code). Not an issue anyone should have encountered!</li> </ul> <p>Backwards incompatible changes:</p> <ul> <li>Rename the following configuration parameters:<ul> <li><code>kerko.features.download_results_link</code> \u2192 <code>kerko.features.download_results</code>.</li> <li><code>kerko.features.print_item_link</code> \u2192 <code>kerko.features.print_item</code></li> <li><code>kerko.features.print_results_link</code> \u2192 <code>kerko.features.print_results</code></li> </ul> </li> </ul> <p>Other changes:</p> <ul> <li>Improve documentation.</li> </ul>"},{"location":"changelog/#100alpha2-2023-07-12","title":"1.0.0alpha2 (2023-07-12)","text":"<p>Features:</p> <ul> <li>Add new configuration parameters <code>kerko.link_groups.*.</code> for defining sets of   links that may be used for navigation.</li> <li>Add a breadcrumb trail to all pages. One or more base links can be configured   (see configuration parameters <code>kerko.breadcrumb</code> and   <code>kerko.link_groups.breadcrumb_base</code>).</li> </ul> <p>Bug fixes:</p> <ul> <li>Fix validation pattern too restrictive for the <code>kerko.zotero.csl_style</code>   configuration parameter.</li> </ul> <p>Backwards incompatible changes:</p> <ul> <li>Items from the main navigation bar are now based on the   <code>kerko.link_groups.navbar</code> configuration. There is no default translation for   it. To change the default text or to translate it, you must override the   default <code>kerko.link_groups.navbar</code> in your configuration file. If you have   overridden the <code>_navbar_items.html.jinja2</code> template and wish to use the   configuration, you might want to adapt it, or revert to the default template.</li> </ul> <p>Other changes:</p> <ul> <li>Improve documentation.</li> </ul>"},{"location":"changelog/#100alpha1-2023-06-29","title":"1.0.0alpha1 (2023-06-29)","text":"<p>Features:</p> <ul> <li>Add the <code>--full</code> option to the <code>sync</code> command line interface (CLI) command.</li> </ul> <p>Bug fixes:</p> <ul> <li>Fix validation pattern too restrictive for the <code>kerko.facets.*.collection_key</code>   configuration parameter.</li> <li>Fix incorrect typing for the <code>kerko.features.download_results_max_count</code> and   <code>kerko.features.print_results_max_count</code> configuration parameters.</li> </ul> <p>Other changes:</p> <ul> <li> <p>Rename the default branch of the repository from 'master' to 'main'. If you   have cloned the repository with Git, use the following commands to rename your   local branch:</p> <pre><code>git branch -m master main\ngit fetch origin\ngit branch -u origin/main main\ngit remote set-head origin -a\n</code></pre> </li> <li> <p>Make the <code>config</code> CLI command show the configuration in TOML format.</p> </li> <li>Make the <code>config</code> CLI command hide secrets by default. Add a <code>--show-secrets</code>   option.</li> <li>Improve documentation.</li> </ul> <p>Backwards incompatible changes:</p> <ul> <li>Prevent the <code>clean</code> CLI command from cleaning everything by default. To delete   everything, you now have to run <code>flask kerko clean everything</code>. This may help   prevent accidental deletion of the cache, which in some instances can take   long to rebuild.</li> <li>Rename the following configuration parameters:<ul> <li><code>kerko.citation_formats.*</code> \u2192 <code>kerko.bib_formats.*</code>.</li> <li><code>kerko.features.download_citations_link</code> \u2192 <code>kerko.features.download_results_link</code></li> <li><code>kerko.features.download_citations_max_count</code> \u2192 <code>kerko.features.download_results_max_count</code></li> <li><code>kerko.features.print_citations_link</code> \u2192 <code>kerko.features.print_results_link</code></li> <li><code>kerko.features.print_citations_max_count</code> \u2192 <code>kerko.features.print_results_max_count</code></li> </ul> </li> <li>Rename the following views:<ul> <li><code>item_citation_download</code> \u2192 <code>item_bib_download</code></li> <li><code>search_citation_download</code> \u2192 <code>search_bib_download</code></li> </ul> </li> </ul>"},{"location":"changelog/#100alpha0-2023-06-26","title":"1.0.0alpha0 (2023-06-26)","text":"<p>Warning: Upgrading from version 0.9 or earlier will require that you adapt your installation and configuration files, then rebuild your search index. Use the commands below, then restart the application. If you are using KerkoApp, make sure to check its changelog.</p> <pre><code>flask kerko clean index\nflask kerko sync index\n</code></pre> <p>Features:</p> <ul> <li>Add many new configuration parameters. Please refer to the configuration   parameters documentation for the full list.</li> <li>Add optional \"Open in Zotero\" and \"View on zotero.org\" buttons to item pages.   These are disabled by default (see new parameters   <code>kerko.features.open_in_zotero_app</code> and <code>kerko.features.open_in_zotero_web</code>).   Even when these are enabled, a user who wishes to use such button must first   enable it from the (also new) Preferences dialog.</li> <li>Add a web API endpoint for retrieving information about the last   synchronization from Zotero.</li> <li>Add the <code>kerko config</code> command to the Flask command line interface for   displaying all configuration parameters.</li> </ul> <p>Other changes:</p> <ul> <li>Restructure and expand documentation into a unified documentation site for   both Kerko and KerkoApp.</li> <li>Add Portuguese translation. Thanks to Gon\u00e7alo Cordeiro.</li> </ul> <p>Backwards incompatible changes:</p> <ul> <li>Raise the minimum required versions of Flask, Flask-Babel, Bootstrap-Flask,   and WTForms. If you have a custom application, some of those may introduce   breaking changes.</li> <li>The data directory has a new default location relative to the instance path.   Please check the documentation for the <code>DATA_PATH</code> and <code>INSTANCE_PATH</code>   configuration parameters. You may need to set one or both of those parameters,   and/or move your existing data directory.</li> <li>Almost all configuration parameters have been renamed and/or moved into a   hierarchical structure. Hierarchical parameters are referred to using   path-like, dot-separated parameter names, and may conveniently be set with the   <code>kerko.config_helpers.config_set()</code> function. Here is a mapping of the changed   parameters:<ul> <li><code>KERKO_BOOTSTRAP_VERSION</code> \u2192 <code>kerko.assets.bootstrap_version</code></li> <li><code>KERKO_CSL_STYLE</code> \u2192 <code>kerko.zotero.csl_style</code></li> <li><code>KERKO_COMPOSER</code> \u2192 <code>kerko_composer</code></li> <li><code>KERKO_DATA_DIR</code> \u2192 <code>DATA_PATH</code>. Now optional, relative to the instance   path, and defaulting to <code>kerko</code> instead of <code>data/kerko</code>.</li> <li><code>KERKO_DOWNLOAD_ATTACHMENT_NEW_WINDOW</code> \u2192 <code>kerko.features.download_attachment_new_window</code></li> <li><code>KERKO_DOWNLOAD_CITATIONS_LINK</code> \u2192 <code>kerko.features.download_citations_link</code></li> <li><code>KERKO_DOWNLOAD_CITATIONS_MAX_COUNT</code> \u2192 <code>kerko.features.download_citations_max_count</code></li> <li><code>KERKO_FEEDS</code> \u2192 <code>kerko.feeds.formats</code></li> <li><code>KERKO_FEEDS_FIELDS</code> \u2192 <code>kerko.feeds.fields</code></li> <li><code>KERKO_FEEDS_MAX_DAYS</code> \u2192 <code>kerko.feeds.max_days</code></li> <li><code>KERKO_FEEDS_REJECT_ANY</code> \u2192 <code>kerko.feeds.reject_any</code></li> <li><code>KERKO_FEEDS_REQUIRE_ANY</code> \u2192 <code>kerko.feeds.require_any</code></li> <li><code>KERKO_FULLTEXT_SEARCH</code> \u2192 <code>kerko.search.fulltext</code></li> <li><code>KERKO_HIGHWIREPRESS_TAGS</code> \u2192 <code>kerko.meta.highwirepress_tags</code></li> <li><code>KERKO_JQUERY_VERSION</code> \u2192 <code>kerko.assets.jquery_version</code></li> <li><code>KERKO_PAGE_LEN</code> \u2192 <code>kerko.pagination.page_len</code></li> <li><code>KERKO_PAGER_LINKS</code> \u2192 <code>kerko.pagination.pager_links</code></li> <li><code>KERKO_POPPER_VERSION</code> \u2192 <code>kerko.assets.popper_version</code></li> <li><code>KERKO_PRINT_CITATIONS_LINK</code> \u2192 <code>kerko.features.print_citations_link</code></li> <li><code>KERKO_PRINT_CITATIONS_MAX_COUNT</code> \u2192 <code>kerko.features.print_citations_max_count</code></li> <li><code>KERKO_PRINT_ITEM_LINK</code> \u2192 <code>kerko.features.print_item_link</code></li> <li><code>KERKO_RELATIONS_INITIAL_LIMIT</code> \u2192 <code>kerko.features.relations_initial_limit</code></li> <li><code>KERKO_RELATIONS_LINKS</code> \u2192 <code>kerko.features.relations_links</code></li> <li><code>KERKO_RELATIONS_SORT</code> \u2192 <code>kerko.features.relations_sort</code></li> <li><code>KERKO_RESULTS_ABSTRACTS_MAX_LENGTH</code> \u2192 <code>kerko.features.results_abstracts_max_length</code></li> <li><code>KERKO_RESULTS_ABSTRACTS_MAX_LENGTH_LEEWAY</code> \u2192 <code>kerko.features.results_abstracts_max_length_leeway</code></li> <li><code>KERKO_RESULTS_ABSTRACTS</code> \u2192 <code>kerko.features.results_abstracts</code></li> <li><code>KERKO_RESULTS_ABSTRACTS_TOGGLER</code> \u2192 <code>kerko.features.results_abstracts_toggler</code></li> <li><code>KERKO_RESULTS_ATTACHMENT_LINKS</code> \u2192 <code>kerko.features.results_attachment_links</code></li> <li><code>KERKO_RESULTS_FIELDS</code> \u2192 <code>kerko.search.result_fields</code></li> <li><code>KERKO_RESULTS_URL_LINKS</code> \u2192 <code>kerko.features.results_url_links</code></li> <li><code>KERKO_TEMPLATE_ATOM_FEED</code> \u2192 <code>kerko.templates.atom_feed</code></li> <li><code>KERKO_TEMPLATE_BASE</code> \u2192 <code>kerko.templates.base</code></li> <li><code>KERKO_TEMPLATE_ITEM</code> \u2192 <code>kerko.templates.item</code></li> <li><code>KERKO_TEMPLATE_LAYOUT</code> \u2192 <code>kerko.templates.layout</code></li> <li><code>KERKO_TEMPLATE_SEARCH</code> \u2192 <code>kerko.templates.search</code></li> <li><code>KERKO_TEMPLATE_SEARCH_ITEM</code> \u2192 <code>kerko.templates.search_item</code></li> <li><code>KERKO_TITLE</code> \u2192 <code>kerko.meta.title</code></li> <li><code>KERKO_WHOOSH_LANGUAGE</code> \u2192 <code>kerko.search.whoosh_language</code></li> <li><code>KERKO_WITH_JQUERY</code> \u2192 <code>kerko.assets.with_jquery</code></li> <li><code>KERKO_WITH_POPPER</code> \u2192 <code>kerko.assets.with_popper</code></li> <li><code>KERKO_ZOTERO_API_KEY</code> \u2192 <code>ZOTERO_API_KEY</code></li> <li><code>KERKO_ZOTERO_BATCH_SIZE</code> \u2192 <code>kerko.zotero.batch_size</code></li> <li><code>KERKO_ZOTERO_LIBRARY_ID</code> \u2192 <code>ZOTERO_LIBRARY_ID</code></li> <li><code>KERKO_ZOTERO_LIBRARY_TYPE</code> \u2192 <code>ZOTERO_LIBRARY_TYPE</code></li> <li><code>KERKO_ZOTERO_LOCALE</code> \u2192 <code>kerko.zotero.locale</code></li> <li><code>KERKO_ZOTERO_MAX_ATTEMPTS</code> \u2192 <code>kerko.zotero.max_attempts</code></li> <li><code>KERKO_ZOTERO_WAIT</code> \u2192 <code>kerko.zotero.wait</code></li> </ul> </li> <li>The Kerko configuration should now be initialized by a call like   <code>kerko.config_helpers.config_update(app.config, kerko.DEFAULTS)</code>.</li> <li><code>Composer.__init__()</code> now only takes a configuration object as argument   instead of a bunch of arguments. Thus, the initial values of the <code>Composer</code>   instance now depend solely on the configuration.</li> <li>Remove the <code>KERKO_USE_TRANSLATIONS</code> configuration variable. Kerko now relies   on the application's default Babel domain and translation directories. Custom   applications that wish to load Kerko's translations should now add   <code>kerko.TRANSLATION_DOMAIN</code> and <code>kerko.TRANSLATION_DIRECTORIES</code> to their Babel   configuration.</li> <li>The <code>__init__()</code> method of <code>FacetSpec</code> and its subclasses now only accept   keyword arguments.</li> <li>The <code>sort_key</code> argument to <code>FacetSpec.__init__()</code> is now <code>sort_by</code>.</li> <li><code>Composer</code> built-in fields <code>z_dateAdded</code> and <code>z_dateModified</code> are now named   <code>date_added</code> and <code>date_modified</code> respectively.</li> </ul>"},{"location":"changelog/#09-2022-12-29","title":"0.9 (2022-12-29)","text":"<p>Warning: Upgrading from version 0.8.x or earlier will require that you rebuild your search index. Use the following commands, then restart the application:</p> <pre><code>flask kerko clean index\nflask kerko sync index\n</code></pre> <p>Features:</p> <ul> <li>Add expand/collapse actions on facet values, allowing full exploration of   hierarchical facets without changing the current search.</li> <li>Add an optional initial limit on the number of values to show under each   facet. When the initial limit is reached, a \"show more\" button allows the user   to expand the full list.</li> <li>Add Atom syndication feeds.</li> <li>Allow searching items by their Zotero key.</li> <li>Add XML sitemap.</li> <li>Add the <code>kerko count</code> CLI command (mostly meant for development purposes).</li> </ul> <p>Bug fixes:</p> <ul> <li>Fix last sync time not displayed at the bottom of search results when   <code>KERKO_PRINT_CITATIONS_LINK</code> and <code>KERKO_DOWNLOAD_CITATIONS_LINK</code> are both set   to <code>False</code>.</li> <li>Fix the <code>kerko sync</code> CLI command not returning an error code with some types   of failures.</li> <li>Fix invalid HTML in help modal.</li> </ul> <p>Other changes:</p> <ul> <li>Handle new Zotero fields introduced with the new 'preprint' item type.</li> <li>Apply a boost factor to DOI, ISBN and ISSN fields extracted from the Extra   field (previously, only the dedicated Zotero fields had a boost factor).</li> <li>Under each facet, always show the facet's active filters first.</li> <li>Make facet values with long labels easier to read (by indenting wrapped lines   to the right of the checkbox).</li> <li>Add link to full bibliography from item pages.</li> <li>Add blocks in templates to facilitate theming.</li> <li>Remove <code>page</code> parameter from pagination links when <code>page=1</code>.</li> <li>Improve documentation.</li> <li>Make sync and schema-related error messages more helpful and user-friendly.</li> <li>Move pydocstyle config to <code>pyproject.toml</code>.</li> <li>Tag package as compatible with Python 3.10 and 3.11.</li> <li>Remove leftover code related to Python versions older than 3.7</li> </ul> <p>Backwards incompatible changes:</p> <ul> <li>Remove the <code>KERKO_FACET_COLLAPSING</code> option. The new initial limit on facets   values made this feature largely redundant.</li> <li>Remove the <code>collapsible</code> param from the <code>FacetSpec</code> class.</li> <li>Remove support for configuration variables <code>KERKO_ZOTERO_START</code> and   <code>KERKO_ZOTERO_END</code> (were only used for development and no longer practical).</li> </ul> <p>Changes that might break custom themes:</p> <ul> <li>The HTML markup and CSS styles of expand/collapse buttons have changed.</li> <li>The parameters of the <code>facet</code>, <code>facet_item</code>, <code>facet_items</code>, <code>facet_fields</code>   template macros have changed.</li> <li>The <code>facets-container</code>, <code>facets</code>, and <code>facets-modal-body</code> element ids are now   required in <code>search.html.jinja2</code>.</li> </ul> <p>Possibly backwards incompatible changes (more or less internal API changes):</p> <ul> <li>Rewrote the <code>criteria</code> module. <code>Criteria.keywords</code> and <code>Criteria.filters</code> work   pretty much as before, but everything else has changed.</li> <li>Rewrote the <code>query</code> module, which had organically grown into an tangled mess,   now replaced with the <code>searcher</code> module. This new API is completely different.</li> <li>Adapted view code to the above-mentioned <code>searcher</code> API.</li> <li>Split the monolithic <code>views</code> module into multiple modules under <code>views</code>   (<code>item_creators</code>, <code>item_facets</code>, <code>item_relations</code>, <code>routes</code>, <code>search</code>), and   moved <code>breadbox</code>, <code>meta</code> (as <code>item_meta</code>), <code>pager</code>, and <code>sorter</code> under   <code>views</code>.</li> </ul>"},{"location":"changelog/#081-2021-11-16","title":"0.8.1 (2021-11-16)","text":"<p>Bug fixes:</p> <ul> <li>Fix missing dependency for package building.</li> </ul>"},{"location":"changelog/#08-2021-11-16","title":"0.8 (2021-11-16)","text":"<p>Warning: Upgrading from version 0.7.x or earlier will require that you clean and re-sync your existing search index. Use the following commands, then restart the application:</p> <pre><code>flask kerko clean index\nflask kerko sync\n</code></pre> <p>Features:</p> <ul> <li>Allow full-text search of PDF attachments. This can be disabled by setting   <code>KERKO_FULLTEXT_SEARCH</code> to <code>False</code>. Since this feature relies on Zotero's   full-text indexing, you must make sure that it works in Zotero first; see   Zotero's   documentation.</li> <li>Add new search scopes \"Everywhere\" (to search both metadata fields and the   text content of attached documents) and \"In documents\" (to search the text   content of attached documents). The scope \"In all fields\" allows to search all   metadata fields, but not the text content of attached documents.</li> <li>Display \"View on {hostname}\" links under search result items, for quick access   to the items' URLs. These can be disabled by setting <code>KERKO_RESULTS_URL_LINKS</code>   to <code>False</code>.</li> <li>Move the \"Read\" buttons under search result items, as \"Read document\" links.   These can now be disabled by setting <code>KERKO_RESULTS_ATTACHMENT_LINKS</code> to   <code>False</code>.</li> <li>Display DOI field values as hyperlinks (both in DOI fields, and in the Extra   field when lines are prefixed with 'DOI:').</li> <li>Add support for imported file attachments, e.g., PDF files imported in your   Zotero library through the Zotero Connector. Previously, only \"attached copies   of files\" were supported.</li> <li>Standalone notes and file attachments are now allowed into the search index.   Kerko filters them out of search results, but custom applications could search   them. A new view, <code>standalone_attachment_download</code>, lets one retrieve a   standalone file attachment.</li> <li>Add configuration options for truncating long abstracts in search results   (<code>KERKO_RESULTS_ABSTRACTS_MAX_LENGTH</code> and   <code>KERKO_RESULTS_ABSTRACTS_MAX_LENGTH_LEEWAY</code>).</li> <li>Embed Highwire Press tags in item pages. This is enabled by default but can be   disabled by setting <code>KERKO_HIGHWIREPRESS_TAGS</code> to <code>False</code>.</li> <li>Allow tracking with Google Analytics (optional).</li> <li>Allow relations in child notes to be specified as HTML links, i.e., in the   <code>href</code> attribute of <code>&lt;a&gt;</code> elements.</li> <li>Allow inclusion or exclusion of items based on multiple tags (previously, only   a single pattern could be checked).</li> </ul> <p>Bug fixes:</p> <ul> <li>Fix irrelevant sync warnings, from extractors running on attachment items.</li> <li>Fix empty prev/next links in search pages metadata.</li> </ul> <p>Other changes:</p> <ul> <li>Make synchronization from Zotero much more efficient through incremental   updates. Instead of performing a full synchronization each time, Kerko now   retrieves just the newly added or updated items. This dramatically reduces the   number of Zotero API calls (and time) required to update Kerko's search index.   Note: More work is planned to eliminate some Zotero API calls that Kerko   still makes early in the synchronization process and that could be avoided   when its cache is already up-to-date.</li> <li>Add a <code>sync cache</code> command to the command line interface.</li> <li>On narrow screens, stack search form controls for better usability.</li> <li>Respond with an HTTP 503 (Service Unavailable) when the search index is empty   or unreadable.</li> <li>Make sorts more efficient by setting the <code>sortable</code> Whoosh flag on relevant   fields.</li> <li>Leading and trailing underscore characters (<code>_</code>) are now trimmed from facet   value labels. This happens after sorting the values, which means that the   underscore can still be used as a prefix to alter the alphabetical order.</li> <li>Support more timezone names. Timezone names such as 'US/Eastern' or   'Europe/London' previously did not work, and times could not be converted   to daylight saving times.</li> <li>Change labels:<ul> <li>\"Print this citation\" \u2192 \"Print this record\" (on item pages)</li> <li>\"Download this citation\" \u2192 \"Download this record\" (on item &amp; search pages)</li> </ul> </li> <li>Inject blocks in item Jinja2 template to facilitate theming.</li> <li>Slightly increase some top/bottom margins.</li> <li>Add the <code>type</code> HTML attribute to record download links.</li> <li>Add the <code>rel=\"alternate\"</code> HTML attribute to record download links on item   pages. Also add a corresponding <code>link</code> element to the page <code>head</code>.</li> <li>Added utilities for running automated integration tests. This will allow   testing many areas of Kerko that previously could hardly be tested.</li> </ul> <p>Backwards incompatible changes:</p> <ul> <li>Remove deprecated <code>kerko index</code> CLI command (use <code>kerko sync</code> instead).</li> </ul> <p>Possibly backwards incompatible changes (more or less internal API changes):</p> <ul> <li>Upgrade many dependencies, including new major versions of Flask (2.x), Jinja2   (3.x), Werkzeug (2.x), Click (8.x).</li> <li>The default list for the <code>KERKO_RESULTS_FIELDS</code> setting now includes the   <code>'url'</code> field. If you have overridden that setting in your application and   <code>KERKO_RESULTS_URL_LINKS</code> is enabled, you'll probably have to add <code>'url'</code> too.</li> <li>The schema field <code>item_type</code> has been renamed to <code>item_type_label</code>. If you   have custom templates, please review any use of <code>item.item_type</code>.</li> <li>The structure of the <code>kerko/_search-result.html.jinja2</code> template has changed   somewhat. If you have overridden it, you'll need to review the changes.</li> <li>The <code>ItemContext</code> class has been eliminated. The <code>Extractor.extract()</code> method   now receives an item's dictionary instead of an <code>ItemContext</code> object, and if   an item has children these are now available directly in the item (with the   <code>children</code> key). If you have created custom extractor classes, their   <code>extract()</code> method will need to be adapted accordingly.</li> <li>Some extractor classes have been renamed:<ul> <li><code>BaseAttachmentsExtractor</code> \u2192 <code>BaseChildAttachmentsExtractor</code></li> <li><code>BaseNotesExtractor</code> \u2192 <code>BaseChildNotesExtractor</code></li> <li><code>LinkedURIAttachmentsExtractor</code> \u2192 <code>ChildLinkedURIAttachmentsExtractor</code></li> <li><code>NotesTextExtractor</code> \u2192 <code>ChildNotesTextExtractor</code></li> <li><code>RawNotesExtractor</code> \u2192 <code>RawChildNotesExtractor</code></li> <li><code>RelationsInNotesExtractor</code> \u2192 <code>RelationsInChildNotesExtractor</code></li> <li><code>StoredFileAttachmentsExtractor</code> \u2192 <code>ChildFileAttachmentsExtractor</code></li> </ul> </li> <li>A view has been renamed:<ul> <li><code>item_attachment_download</code> \u2192 <code>child_attachment_download</code></li> </ul> </li> <li>A default field has been renamed:<ul> <li><code>alternateId</code> \u2192 <code>alternate_id</code></li> </ul> </li> </ul>"},{"location":"changelog/#071-2021-02-04","title":"0.7.1 (2021-02-04)","text":"<p>Security fixes:</p> <ul> <li>Fix unescaped date fields, causing a vulnerability to XSS attacks. This   vulnerability was introduced in version 0.7.</li> </ul> <p>Bug fixes:</p> <ul> <li>Fix wrong locale separator in the HTML lang attribute.</li> </ul> <p>Other changes:</p> <ul> <li>Remove unwanted spacing after dropdown labels.</li> </ul> <p>Documentation changes:</p> <ul> <li>Fix missing info about library groupID in configuration docs. Thanks   @drmikeuk for reporting the issue.</li> </ul>"},{"location":"changelog/#07-2021-01-08","title":"0.7 (2021-01-08)","text":"<p>Warning: Upgrading from version 0.6 or earlier will require that you clean and re-sync your existing search index. Use the following commands, then restart the application:</p> <pre><code>flask kerko clean index\nflask kerko sync\n</code></pre> <p>Features:</p> <ul> <li>Allow users to toggle the display of abstracts on search results pages.</li> <li>Allow inclusion or exclusion of items based on their tags   (#4).</li> <li>Show attached links to URIs on item pages.</li> <li>Show relations on item pages. The relation types provided by default are:</li> <li>Related, based on Zotero's Related field.</li> <li>Cites, managed through child notes containing Zotero URIs and tagged with     the <code>_cites</code> tag.</li> <li>Cited by, automatically inferred from Cites relations.</li> <li>The Extra field is now searched when searching \"in any fields\".</li> <li>Items that have a DOI, ISBN or ISSN identifier can be referenced by appending   their identifier to your Kerko site's base URL.</li> <li>Requests for the older URL of an item whose ID has changed are now   automatically redirected to the item's current URL. This relies on the   <code>dc.replaces</code> relation that's managed internally by Zotero on some operations   such as item merges.</li> <li>Help users who might mistakenly bookmark a search result's URL rather than the   item's permanent URL: Add an <code>id</code> parameter to the search result URLs, and   redirect the user to that item's permanent URL if the search result no longer   matches because of database changes.</li> <li>Redirect to the parent item's page when the user tries to request an   attachment that no longer exists.</li> <li>Improve accessibility based on WCAG recommendations and WAI-ARIA standards:</li> <li>Add labels to search form elements.</li> <li>Add landmark role <code>search</code> to the search form.</li> <li>Make the purpose of various links more obvious through improved or added     labels.</li> <li>Add the <code>aria-label</code> attribute to many elements.</li> <li>Add text to indicate the current value of widgets.</li> <li>Add the <code>aria-current</code> attribute to indicate the current value of widgets.</li> <li>Remove useless link to the current page from the pagination widget.</li> </ul> <p>Bug fixes:</p> <ul> <li>Fix crash when trying to sync a link attachment   (#3).</li> <li>Fix unhandled exception during sync when an attachment cannot be downloaded.</li> <li>Fix page numbers greater than the page count in search URLs generating wrong   page numbers for search result item URLs.</li> <li>Fix secondary keys getting sorted in reverse order with some sort options,   e.g., when sorting by newest first, results having the same date were then   sorted by creator name in reverse alphabetical order instead of alphabetical   order.</li> <li>Fix empty HTML element taking up horizontal space when there are no badges.</li> </ul> <p>Other changes:</p> <ul> <li>Display ISO 8601 calendar dates in a more readable format, using the   formatting style of the locale.</li> <li>Show a timezone abbreviation along with time of last update from Zotero.</li> <li>Add German translation. Thanks to @mmoole.</li> <li>Fix broken \"Getting started\" example in README.</li> <li>Migrate most package distribution options and metadata from <code>setup.py</code> to   <code>setup.cfg</code>.</li> <li>Migrate project to a <code>src</code> layout.</li> <li>Use Flask-Babel instead of its fork Flask-BabelEx, now that is has merged the   translation domain features from Flask-BabelEx.</li> </ul> <p>Backwards incompatible changes:</p> <ul> <li>Drop support for Python 3.6. Kerko is no longer being tested under Python 3.6.   Known issue with 3.6 at this point: some ISO 8601 dates cannot be parsed and   reformatted; instead of being displayed in a locale-sensitive manner, these   get displayed as is. More issues might arise in the future with Python 3.6 as   Kerko continues to evolve.</li> <li>All values of the <code>pager</code> dict passed to the <code>_pager.html.jinja2</code> template are   now lists. Previously, only the values at keys <code>'before'</code> and <code>'after'</code> were   lists; now the values at keys <code>'previous'</code>, <code>'first'</code>, <code>'current'</code>, <code>'last'</code>,   and <code>'next'</code> are lists as well.</li> <li>The words <code>'blacklist'</code> and <code>'whitelist'</code> in variable names are replaced with   <code>'exclude'</code> and <code>'include'</code>.</li> <li>The <code>KERKO_RESULTS_ABSTRACT</code> configuration variable is replaced by two   variables, <code>KERKO_RESULTS_ABSTRACTS</code> (note the now plural form) and   <code>KERKO_RESULTS_ABSTRACTS_TOGGLER</code>.</li> <li>Citation download URLs now have the form   <code>{url_prefix}/{itemID}/export/{format}</code> for individual items (<code>'export'</code> has   been inserted), and <code>{url_prefix}/export/{format}/</code> for search result pages   (<code>'download'</code> has been replaced by <code>'export'</code>).</li> <li>The <code>Extractor</code> class' interface has changed, improving consistency and   separation of concerns:</li> <li>All arguments to <code>__init__()</code> must now be specified as keyword arguments.</li> <li>The <code>extract()</code> method no longer have a <code>document</code> argument, and the <code>spec</code>     argument is now the last one. The method now returns a value instead of     assigning it to the document.</li> <li>The new <code>extract_and_store()</code> method handles extraction, encoding, and     assignment to the document, assigning the value only when it is not <code>None</code>.</li> <li>The <code>AttachmentsExtractor</code> class has been renamed to   <code>StoredFileAttachmentsExtractor</code>.</li> <li><code>InCollectionExtractor</code> now extends collection membership to subcollections.   To preserve the previous behavior, set the <code>check_subcollections</code> parameter to   <code>False</code> when initializing the extractor.</li> </ul> <p>Possibly backwards incompatible changes (more or less internal API changes):</p> <ul> <li>The <code>search_results</code> variable passed to the <code>search.html.jinja2</code> template is   now an iterator of tuples, where the first element of each tuple is a result,   and the second element the URL of the result.</li> </ul>"},{"location":"changelog/#06-2020-06-15","title":"0.6 (2020-06-15)","text":"<p>Security fixes:</p> <ul> <li>Fix multiple vulnerabilities to XSS attacks. All previous versions of Kerko   were vulnerable, thus an upgrade is highly recommended.</li> </ul> <p>Backwards incompatible changes:</p> <ul> <li>Remove default value for the <code>KERKO_DATA_DIR</code> configuration variable. KerkoApp   users don't need to worry about this as KerkoApp takes care of it, but custom   apps that did not already set this variable now have to.</li> </ul> <p>Features:</p> <ul> <li>Open PDF documents in the browser's built-in PDF viewer (instead of opening   the browser's file download popup).</li> <li>Add buttons for opening documents directly from search result pages (these   replace the previous paperclip badges).</li> <li>Add button at the top of item pages for opening documents (makes the   availability of such documents much more obvious).</li> <li>Add the <code>KERKO_DOWNLOAD_ATTACHMENT_NEW_WINDOW</code> configuration variable to   control whether to open documents in a new window or in the same window.</li> <li>Display the date and time of the last successful synchronization from Zotero   at the bottom of search results.</li> </ul> <p>Bug fixes:</p> <ul> <li>Preserve newlines when displaying the value of the Extra field.</li> <li>Preserve newlines when displaying abstracts in search result pages.</li> <li>Fix filters missing on search pages that have no results.</li> <li>Avoid empty box in print media when there is no search criteria.</li> <li>Avoid empty box when the search index is missing.</li> <li>Fix pluralization in CLI time elapsed messages.</li> </ul> <p>Other changes:</p> <ul> <li>Refer to attachments as \"documents\" in the interface, and replace the   paperclip icon with a file icon.</li> <li>Remove CSRF token from search form. Token expiration can impede legitimate   users, and the token is unnecessary as the form does not change the   application's state.</li> <li>Add a proper message when none of the filters provided in the URL are   recognized.</li> <li>Improve documentation.</li> <li>Add INFO-level log message to report successful synchronization from Zotero.</li> <li>Add blocks in templates to facilitate theming.</li> </ul> <p>Possibly backwards incompatible changes (more or less internal API changes):</p> <ul> <li>Rename the <code>content_with_badges</code> template macro as <code>badges</code>, and leave it to   the caller to display content.</li> <li>Remove badges that are related to attachments.</li> </ul>"},{"location":"changelog/#05-2019-11-19","title":"0.5 (2019-11-19)","text":"<p>Warning: Upgrading from version 0.4 or earlier will require that you clean and re-sync your existing search index. Use the following commands:</p> <pre><code>flask kerko clean index\nflask kerko sync\n</code></pre> <p>Features:</p> <ul> <li>Add support for Zotero attachments.</li> <li>Allow configuration of badges on items. The 'attachment' badge is provided by   default, displaying an icon on items that have one or more attachments.</li> <li>Add help modal.</li> <li>Improve customizability:</li> <li>Add <code>KERKO_TEMPLATE_*</code> configuration variables for page template names.</li> <li>Use configurable, separate templates to render facets and badges (see the     <code>renderer</code> argument to <code>kerko.specs.FacetSpec</code>, <code>kerko.specs.BadgeSpec</code>).</li> <li>Add the <code>KERKO_RESULTS_FIELDS</code> configuration variable to specify which     fields to retrieve with search queries.</li> <li>Add building blocks for creating boolean facets based on collection membership   (new class <code>kerko.extractors.InCollectionExtractor</code>, new parameters for   <code>kerko.codecs.BooleanFacetCodec</code>).</li> </ul> <p>Bug fixes:</p> <ul> <li>Fix facets not ordered by weight on item page.</li> <li>Preserve newlines in abstract display.</li> <li>Fix incorrect use of bookmark link on item pages, set canonical link instead.</li> <li>Prevent text overflow in some browsers on citations containing long URLs.</li> </ul> <p>Other changes:</p> <ul> <li>Deprecate CLI command <code>kerko index</code> in favor of new command <code>kerko sync</code>.</li> <li>Change title of the \"Refine\" panel to \"Explore\".</li> <li>Change labels of the \"Print\" and \"Download\" buttons to \"Print this citation\"   and \"Download this citation\", to prevent any confusion with attachment   downloading.</li> <li>Show the facets in a more robust and accessible Bootstrap modal, on small   screens, instead of the home-built drawer.</li> <li>Use compact pagination widget on small screens.</li> <li>Tweak sizing, positioning, and spacing of various UI elements.</li> <li>Improve accessibility of various UI elements.</li> <li>Make citation stand out more in item page.</li> <li>Hide some elements and decorations in print media.</li> <li>Make search query more efficient on item page.</li> </ul> <p>Possibly backwards incompatible changes (more or less internal API changes):</p> <ul> <li>Force keyword arguments with <code>kerko.composer.Composer.__init__()</code>.</li> <li>Rename <code>kerko.composer.Composer.__init__()</code> arguments   <code>default_note_whitelist_re</code> as <code>default_child_whitelist_re</code>,   <code>default_note_blacklist_re</code> as <code>default_child_blacklist_re</code>.</li> <li>Rename method <code>kerko.views.item()</code> as <code>kerko.views.item_view()</code>.</li> <li>Rename template file <code>_facet.html.jinja2</code> as <code>_facets.html.jinja2</code>.</li> <li>Replace argument <code>checkboxes</code> in template macro <code>field()</code> with <code>add_link_icon</code>   and <code>remove_link_icon</code>.</li> </ul>"},{"location":"changelog/#04-2019-09-28","title":"0.4 (2019-09-28)","text":"<p>Features:</p> <ul> <li>Allow search term boosting in relevance score calculation, e.g. <code>faceted^2   search browsing^0.5</code>.</li> </ul> <p>Security fixes:</p> <ul> <li>Update minimum Werkzeug version to 0.15.3. See   CVE-2019-14806: \"Pallets   Werkzeug before 0.15.3, when used with Docker, has insufficient debugger PIN   randomness because Docker containers share the same machine id.\"</li> </ul> <p>Other changes:</p> <ul> <li>Update jQuery version to 3.4.1.</li> <li>Update French translations (translate boolean search operators).</li> <li>Improve search form validation and error display.</li> <li>Disable not-so-intuitive boolean search operators (<code>AndNot</code>, <code>AndMaybe</code>,   <code>Require</code> were unwanted but enabled by default by Whoosh's <code>OperatorsPlugin</code>).</li> <li>Improve documentation.</li> <li>Code cleanup.</li> </ul>"},{"location":"changelog/#03-2019-07-29","title":"0.3 (2019-07-29)","text":"<p>Features:</p> <ul> <li>Exporting: users may export individual citations as well as complete   bibliographies corresponding to search results. By default, download links are   provided for the RIS and BibTeX formats, but applications may be configured to   export any format supported by the Zotero API.</li> </ul> <p>Bug fixes:</p> <ul> <li>Fix bad alignment of field names in print mode.</li> <li>Remove warning when indexing an item with no authors   (#1).</li> </ul> <p>Other changes:</p> <ul> <li>Move print button to bottom of search pages (next to the new download   dropdown).</li> <li>Improve documentation.</li> <li>Compile message catalog before building sdist and wheel.</li> </ul> <p>Possibly backwards incompatible changes (more or less internal API changes):</p> <ul> <li>Method <code>kerko.composer.Composer.get_ordered_specs()</code> replaces   <code>get_ordered_scopes()</code>, <code>get_ordered_facets()</code> and <code>get_ordered_sorts()</code>.</li> </ul>"},{"location":"changelog/#03alpha1-2019-07-17","title":"0.3alpha1 (2019-07-17)","text":"<ul> <li>Fix broken links in documentation.</li> </ul>"},{"location":"changelog/#03alpha0-2019-07-16","title":"0.3alpha0 (2019-07-16)","text":"<ul> <li>First PyPI release.</li> </ul>"},{"location":"config-basics/","title":"Configuration basics","text":"<p>In this section, we will assume that you are using Kerko through KerkoApp. Some elements may not apply if you have integrated Kerko into your own custom Flask application (see Configuration in custom applications).</p>"},{"location":"config-basics/#parameter-styles","title":"Parameter styles","text":"<p>When looking at Kerko configuration options, you will quickly notice two styles of parameter names, uppercase names and lowercase names.</p> <p>Uppercase names, such as <code>SECRET_KEY</code>, <code>ZOTERO_LIBRARY_ID</code>, <code>DATA_PATH</code>, <code>BABEL_DEFAULT_LOCALE</code>, follow the usual convention for environment variables. Most Flask and Flask extensions parameter names follow this convention. Some Kerko parameters have uppercase names too, but only those parameters that may usefully be set as environment variables. Internally, those parameters are stored into a flat Python dictionary.</p> <p>Most of Kerko parameters use lowercase names. They are also organized into a hierarchy, and are usually referenced using dot-separated paths. Examples are: <code>kerko.features.results_abstracts</code>, <code>kerko.meta.title</code>, <code>kerko.facets.item_type.enabled</code>. Internally, those parameters are stored into nested Python dictionaries.</p> <p>Documentation convention</p> <p>In this manual, we will generally refer to a hierarchical parameter using its full dot-separated path, for example <code>kerko.meta.title</code>, except when context makes repeating the full path redundant.</p>"},{"location":"config-basics/#configuration-methods","title":"Configuration methods","text":"<p>KerkoApp provides two ways to set configuration parameters:</p> <ol> <li>As parameters in one or more TOML files.</li> <li>As environment variables.</li> </ol> <p>The above list is in ascending order of precedence. This means that a given parameter set in a TOML file can be overridden by an environment variable.</p> <p>We do not recommend configuring the same parameter in multiple places, as that might confuse systems administrators, but a layered approach is useful in implementing the Twelve-factor App methodology.</p> <p>TOML files are the preferred and most convenient way of configuring KerkoApp. Environment variables, however, are still supported, as some parameters cannot be set in TOML files, such as <code>FLASK_APP</code> and <code>KERKOAPP_CONFIG_FILES</code>.</p>"},{"location":"config-basics/#toml-files","title":"TOML files","text":"<p>The TOML syntax allows organizing parameters under headers to avoid repetition and to make the file more readable. Therefore, two following two examples are equivalent ways of setting the <code>kerko.meta.title</code> parameter:</p> TOML example 1<pre><code>kerko.meta.title = \"My Awesome Bibliography\"\n</code></pre> TOML example 2<pre><code>[kerko.meta]\ntitle = \"My Awesome Bibliography\"\n</code></pre> <p>Note that if headers are used in a TOML file, any top-level parameter must be set above the first header:</p> Correct TOML example<pre><code>ZOTERO_LIBRARY_ID = \"123456\"\n\n[kerko.meta]\ntitle = \"My Awesome Bibliography\"\n</code></pre> Incorrect TOML example<pre><code>[kerko.meta]\ntitle = \"My Awesome Bibliography\"\n\nZOTERO_LIBRARY_ID = \"123456\"\n</code></pre> <p>By default, KerkoApp will look for a series of TOML files:</p> <ol> <li><code>config.toml</code></li> <li><code>instance.toml</code></li> <li><code>.secrets.toml</code></li> </ol> <p>For each of those, KerkoApp first looks for the file into the current working directory. If it does not find it there, it searches by traversing directories upwards until it finds the file or reaches the root directory. At this point, if the file is still not found, the same scanning process is reapplied, but this time starting from the instance path. After that, whether the file was found or not, KerkoApp continues with the next filename in the list.</p> <p>The files are loaded in the specified order. The parameters from each file get merged into the previously known configuration. If a given parameter was already set, its value is overwritten by the one from the later file.</p> <p>This approach allows a layered configuration where:</p> <ul> <li><code>config.toml</code> contains general (public) parameters. It is safe (and wise) to   manage this file in a code repository.</li> <li><code>instance.toml</code> contains server-specific parameters such as those that might   refer to paths or systems that only exist on the server. This file is usually   not put into a code repository.</li> <li><code>.secrets.toml</code> contains secrets (private parameters) that ought to be known   only to the server, such as API keys. This file should never be added to a   code repository.</li> </ul> <p>You do not have to use all three files. One might, for example, use just <code>config.toml</code> and <code>.secrets.toml</code>, and not create <code>instance.toml</code>.</p> <p>You may replace the default list of TOML file paths by setting the <code>KERKOAPP_CONFIG_FILES</code> environment variable.</p> <p>In the example below, the default list of TOML files is replaced by a list of two file paths, one relative and the other absolute:</p> POSIXWindows <pre><code>KERKOAPP_CONFIG_FILES=\"first_config.toml;/absolute/path/to/second_config.toml\"\n</code></pre> <pre><code>KERKOAPP_CONFIG_FILES=\"first_config.toml;C:\\absolute\\path\\to\\second_config.toml\"\n</code></pre>"},{"location":"config-basics/#environment-variables","title":"Environment variables","text":"<p>KerkoApp requires environment variable names to be prefixed with <code>KERKOAPP_</code>. The <code>SECRET_KEY</code> parameter, for example, becomes <code>KERKOAPP_SECRET_KEY</code> when specified as an environment variable.</p> <p>For hierarchical parameters, each dot separator (<code>.</code>) must be replaced by two underscore characters (<code>__</code>). The <code>kerko.meta.title</code> parameter, for example, becomes <code>KERKOAPP_kerko__meta__title</code> when specified as an environment variable. Such conversion is not necessary in TOML files.</p> <p>Note that Windows does not allow lowercase environment variable names. Consequently, Windows users have no choice but to set lowercase parameters in TOML files.</p> <p>Environment variables may be set from various locations, in the following order (refer to the Flask documentation for more details):</p> <ol> <li>As entries in a <code>.flaskenv</code> file.</li> <li>As entries in a <code>.env</code> file.</li> <li>As entries in a file specified by the <code>--env-file</code> command line option.</li> <li>As environment variables.</li> </ol> <p>The above list is in ascending order of precedence. This means that a given parameter set earlier can be overridden later as values get loaded. Files are located by scanning directories upwards from the directory you call flask from.</p>"},{"location":"config-basics/#configuration-in-custom-applications","title":"Configuration in custom applications","text":"<p>If you are using a custom Flask application instead of KerkoApp, some of the present documentation may not fully apply to you. For example:</p> <ul> <li>TOML files might not be supported at all.</li> <li>Environment variables might require a prefix other than <code>KERKOAPP_</code>, or no   prefix at all.</li> </ul> <p>In a custom application, hierarchical parameters may be set in Python using the API provided by Kerko, as in the following example:</p> Setting a configuration parameter in Python<pre><code>from kerko.config_helpers import config_set\nconfig_set(app.config, \"kerko.meta.title\", \"My Awesome Bibliography\")\n</code></pre> <p>Such assignments must be done during the initialization process. The application cannot change a setting while responding to a request.</p>"},{"location":"config-basics/#viewing-the-configuration","title":"Viewing the configuration","text":"<p>With configuration parameters potentially taking values from different sources (default values, configuration files, environment variables), you may sometimes want to verify the actual values taken by each parameter.</p> <p>The following command will show the configuration parameters of the application and their values:</p> <pre><code>flask kerko config\n</code></pre>"},{"location":"config-guides/","title":"Configuration guides","text":"<p>This sections provides guidance on configuring specific aspects of Kerko.</p>"},{"location":"config-guides/#defining-custom-facets-based-on-zotero-collections","title":"Defining custom facets based on Zotero collections","text":"<p>Zotero collections can be mapped to custom facets in Kerko. With this scheme, a collection in the Zotero library represents a facet, and its subcollections correspond to values (or user-selectable filters) within the facet. Figure 1 below illustrates such mapping, taken from the demo library and its corresponding demo site.</p> <p></p> Figure 1. Side-by-side comparison between the structure of collections in a Zotero library and the resulting faceted browsing interface in Kerko. <p>For such mapping to work, the following conditions must be met:</p> <ul> <li>The collection that is to be mapped to a facet must be a top-level   collection. In other words, it must be directly under the root of your   Zotero library.</li> <li>At least one subcollection must be present within the chosen top-level   collection, and that subcollection (or one of its own subcollections) must   contain at least one item.</li> </ul> <p>Once your Zotero library it set up to meet those conditions, you may configure the facets. For the example in Figure 1, the configuration looks like this:</p> <pre><code>[kerko.facets.topic]\nenabled = true\ntype = \"collection\"\ncollection_key = \"KY3BNA6T\"\nfilter_key = \"topic\"\ntitle = \"Topic\"\nweight = 110\ninitial_limit = 5\ninitial_limit_leeway = 2\n\n[kerko.facets.field_of_study]\nenabled = true\ntype = \"collection\"\ncollection_key = \"7H2Q7L6I\"\nfilter_key = \"field-of-study\"\ntitle = \"Field of study\"\nweight = 120\ninitial_limit = 5\ninitial_limit_leeway = 2\n\n[kerko.facets.contribution]\nenabled = true\ntype = \"collection\"\ncollection_key = \"JFQRH4X2\"\nfilter_key = \"contribution\"\ntitle = \"Contribution\"\nweight = 130\ninitial_limit = 5\ninitial_limit_leeway = 2\n</code></pre> <p>For details on each parameter, please refer to the parameters documentation. However, we can highlight some elements:</p> <ul> <li><code>collection_key</code> is the key assigned by Zotero to identify the collection. An   easy way to find this key is to visit your library using Zotero's web   interface. Click the collection, and check its URL in your browser's address   bar. In our example, the URL of the \"Topic\" collection is   https://www.zotero.org/groups/2348869/kerko_demo/collections/KY3BNA6T,   hence the use of <code>\"KY3BNA6T\"</code> as the collection key.</li> <li><code>filter_key</code> tells Kerko the key to use in URLs when a user of your Kerko site   selects a filter within the facet. In our example, for the \"Topic\" facet we   chose to set this parameter to <code>\"topic\"</code> and, consequently, the search URL   will look like   https://demo.kerko.whiskyechobravo.com/bibliography/?topic=Z8LT6QZG.2ZGZH2E2.</li> <li><code>title</code> is the heading that Kerko will show for the facet. If desired, you may   choose a title that is different from the collection's name in Zotero.</li> <li><code>weight</code> determines the relative position of the facet. Small numbers (low   weights) rise above large ones (heavier weights). This explains why, in our   example, Kerko displays \"Topic\" (weighting 110) above \"Field of study\" (120)   and \"Contribution\" (130).</li> </ul> <p>Other things to know:</p> <ul> <li> <p>After adding a new facet, you must clean and re-sync the search index. Please   check the documentation on synchronization, but in short   you have to use the following commands:</p> <pre><code>flask kerko clean index\nflask kerko sync index\n</code></pre> </li> <li> <p>Kerko allows a facet to have any number of hierarchical sublevels (nested   subcollections).</p> </li> <li>Any new subcollection will automatically appear under the facet after a sync,   if it (or one of its own subcollections) contains at least one item.   Collection structures that contain no items will not show up in Kerko.</li> <li>An item may belong to multiple collections in Zotero. Take advantage of that   capability when designing your faceted classification. Ideally, facets   complement each other in describing different perspectives on the same   objects. If you are unfamiliar with faceted classification, we highly   recommend this paper by William Denton (2003): How to Make a Faceted   Classification and Put It On the   Web.</li> <li>In Zotero, an item only needs to be assigned to the hierarchical level that is   most relevant for it. You do not need to also add the item to the parent   collections. The reason is that in Kerko a given filter automatically includes   the items from its corresponding subcollection and all of its subcollections.</li> <li>You do not have to expose all of your Zotero library's top-level collections   to Kerko. Kerko will only use those that are given in the configuration, and   ignore the others. Note, however, that unless you use item   inclusion or   exclusion parameters, items will be   visible in your Kerko site regardless of the collections they belong to.</li> </ul> <p>Phew! We think that this is simpler to setup in practice than it looks in writing. Hopefully you will agree.</p>"},{"location":"config-guides/#creating-custom-content-pages-based-on-zotero-standalone-notes","title":"Creating custom content pages based on Zotero standalone notes","text":"<p>If you wish to provide informational pages along with your bibliography, you can add standalone notes to your Zotero library, and configure Kerko to provide pages whose content will come from those notes.</p> <p>Say you want to provide \"About\" and \"Contact Us\" pages with simple text content, you could implement them by following these steps:</p> <ul> <li>Create a standalone note in Zotero. In the Zotero note editor, enter the   desired text for your \"About\" page.</li> <li>Create another standalone note in Zotero. In the Zotero note editor, enter the   desired text for your \"Contact Us\" page.</li> <li>For each note, find its item ID. One way to find it is to visit your library   using Zotero's web interface. Click the note, and check its URL in your   browser's address bar. It should look a bit like   https://www.zotero.org/groups/2348869/kerko_demo/items/Y48RBWDB/item-list.   In this example, <code>\"Y48RBWDB\"</code> is the item ID.</li> <li> <p>Define the \"About\" and \"Contact Us\" pages by adding the following snippet to   your Kerko configuration:</p> <pre><code>[kerko.pages.about]\npath = \"/about\"\nitem_id = \"Y48RBWDB\"\ntitle = \"About\"\n\n[kerko.pages.contact_us]\npath = \"/contact\"\nitem_id = \"REG3CL25\"\ntitle = \"Contact Us\"\n</code></pre> <p>... where:</p> <ul> <li><code>path</code> is the desired URL path for the page;</li> <li><code>item_id</code> is the note's item ID (as found earlier);</li> <li><code>title</code> is the desired title for the page in the Kerko site.</li> </ul> <p>For more details on each parameter, please refer to the parameters documentation.</p> </li> <li> <p>Then, you will probably want the navigation bar to provide links to your   pages. The following configuration code defines a navigation bar with three   links \u2014 a link to the bibliography, and links to the \"About\" and \"Contact Us\"   pages:</p> <pre><code>[[kerko.link_groups.navbar]]\ntype = \"endpoint\"\nendpoint = \"kerko.search\"\ntext = \"Bibliography\"\n\n[[kerko.link_groups.navbar]]\ntype = \"page\"\npage = \"about\"\ntext = \"About\"\n\n[[kerko.link_groups.navbar]]\ntype = \"page\"\npage = \"contact_us\"\ntext = \"Contact Us\"\n</code></pre> <p>... where:</p> <ul> <li>the <code>type</code> parameter indicates the type of link (<code>\"endpoint\"</code> indicates a   core Kerko link, while <code>\"page\"</code> indicates a link to a page defined under   <code>kerko.pages.*</code>);</li> <li>the <code>page</code> parameter specifies the target of the link, e.g., the unique   key of the page (which replaces the <code>*</code> in the <code>kerko.pages.*</code> header);</li> <li>the <code>text</code> parameter provides the link's text to show in the navigation   bar.</li> </ul> <p>Navigation bar links will be displayed in the order they appear in the configuration file.</p> <p>For more details on this configuration section, please refer to the parameters documentation</p> </li> <li> <p>Make sure Kerko's database is up-to-date with your new note by running the   following command:</p> <pre><code>flask kerko sync\n</code></pre> </li> <li> <p>Restart your Kerko application to load the configuration changes. If all goes   well, you will have new \"About\" and \"Contact Us\" pages accessible from the   navigation bar.</p> </li> </ul> <p>Please note that Kerko does not restructure the HTML that Zotero generates for notes. If you use headings in your notes, we recommend that you start with the \"Heading 2\" heading level, because \"Heading 1\" should be reserved to Kerko (for the page title).</p> <p>Kerko is not, and never will be, a web content management system. Its sole purpose is to provide a nice interface for a Zotero library. Thus, Kerko content pages are just a very rudimentary way of providing simple informational content along with the library. For more advanced content needs, you might have to consider integrating Kerko into a custom Flask application backed with proper content editing features.</p>"},{"location":"config-guides/#ensuring-full-text-indexing-of-your-attachments-in-zotero","title":"Ensuring full-text indexing of your attachments in Zotero","text":"<p>Kerko's full-text indexing relies on text content extracted from attachments by Zotero. Consequently, for Kerko's full-text search to work, you must make sure that full-text indexing works in Zotero first; see Zotero's documentation on full-text indexing.</p> <p>Individual attachments in Zotero can be indexed, partially indexed, or unindexed. Various conditions may cause an attachment to be partially indexed or unindexed, e.g., file is large, has not been processed yet, or does not contain text.</p> <p>Zotero shows the indexing status in the attachment's right pane. If it shows \"Indexed: Yes\", all is good. If it shows \"Indexed: No\" or \"Indexed: Partial\", then clicking the \"Reindex Item\" button (next to the indexing status) should ensure that the attachment gets fully indexed, that is if the file actually contains text. If there is no \"Reindex Item\" button, it probably means that Zotero does not support that file type for full-text indexing (at the moment, it only supports PDF and plain text files).</p> <p>It can be tedious to go through hundreds of attachments just to find out whether they are indexed or not. To make things easier, you could create a saved search in your Zotero library to get an always up-to-date list of unindexed PDFs. Use the following search conditions:</p> <ul> <li>Match all of the following:<ul> <li>Attachment File Type \u2014 is \u2014 PDF</li> <li>Attachment Content \u2014 does not contain \u2014 . (that's a period; also   select RegExp in the small dropdown list, as that will make the period   match any character)</li> </ul> </li> </ul> <p>This search might return a long list of unindexed attachments. To reindex them all at once, you may select them, then right-click to get the contextual menu, and select \"Reindex items\". It may require some time to update your library on zotero.org. Note that documents that have no text content, as well as missing documents, will still be considered as unindexed and appear in the results of the saved search.</p> <p>Controlling the indexing status will not only improve full-text search on your Kerko site, but also full-text search from within Zotero!</p>"},{"location":"config-guides/#providing-cites-and-cited-by-relations","title":"Providing Cites and Cited by relations","text":"<p>Zotero allows one to link items together through its Related field. However, such relations are not typed nor directed, making it impossible (1) to indicate the nature of the relation, or (2) to distinguish which of two related items is the citing entity, and which is the one being cited. Consequently, Kerko has its own method for setting up those relations.</p> <p>To establish Cites relations in your Zotero library, you must follow the procedure below:</p> <ul> <li>Install the Zutilo plugin for Zotero. Once it is installed, go to Tools &gt;   Zutilo Preferences... in Zotero. Then, under Zotero item menu, select   Zotero context menu next to the Copy Zotero URIs menu item. This   configuration step only needs to be done once.</li> <li>Select one or more items from your library that you wish to show as cited by   another. Right-click on one of the selected items to open the context menu,   and select Copy Zotero URIs from that menu. This copies the references of   the selected items items to the clipboard.</li> <li>Right-click the item from your library that cites the items. Select Add Note   from that item's context menu to add a child note.</li> <li>In the note editor, paste the content of the clipboard. The note should then   contain a series of URIs looking like   <code>https://www.zotero.org/groups/9999999/items/ABCDEFGH</code> or   <code>https://www.zotero.org/users/9999999/items/ABCDEFGH</code>.</li> <li>At the bottom of the note editor, click into the Tags field and type   <code>_cites</code>. That tag that will tell Kerko that this particular note is special,   that it contains relations.</li> </ul> <p>At the next synchronization, Kerko will retrieve the references found in notes tagged with <code>_cites</code>. Afterwards, proper hyperlinked citations will appear in the Cites and Cited by sections of the related bibliographic records.</p> <p>Remarks:</p> <ul> <li>Enter only the Cites relations. The reverse Cited by relations will be   inferred automatically.</li> <li>You may only relate items that belong to the same Zotero library.</li> <li>You may use Zotero Item Selects (URIs starting with <code>zotero://select/</code>) in the   notes, if you prefer those to Zotero URIs.</li> <li>If entered as plain text, URIs must be separated by one or more whitespace   character(s). Alternatively, URIs may be entered in HTML links, i.e., in the   <code>href</code> attribute of <code>&lt;a&gt;</code> elements.</li> <li>Hopefully, Zotero will provide nicer ways for handling relation   types in the future.   In the meantime, using child notes is how Kerko handles it. If relation types   are important to you, consider describing your use case in the Zotero   forums.</li> <li>Custom Kerko applications can provide more types of relations, if desired, in   addition to Cites and Cited by.</li> </ul>"},{"location":"config-params/","title":"Configuration parameters","text":"<p>This section describes most configuration parameters available to Kerko and KerkoApp.</p> <p>Unless indicated otherwise, all parameters are optional and will take a default value if omitted from your configuration.</p> <p>Note</p> <p>Flask and Flask extensions loaded by the application may provide additional configuration parameters that are not described in this manual. To find those, please refer to the documentation of the relevant package.</p> <p>Changing the Kerko configuration can be disruptive</p> <p>Making any change to a Kerko configuration file requires that you at least restart the application afterwards for the change to become effective.</p> <p>Moreover, some parameters have an effect on the structure of the cache or the search index that Kerko depends on. Changing this kind of parameter may require that you rebuild either. Refer to the documentation of the parameter to check if specific actions need to be taken after a change.</p> <p>Prefix your environment variables</p> <p>KerkoApp users must prefix parameter names with <code>KERKOAPP_</code> when configuring them as environment variables. However, that prefix should be omitted when the same parameter is set in a TOML file. See environment variables for details.</p> <p>Be a minimalist, only set a parameter when necessary</p> <p>If a parameter's default value works for you, just omit that parameter from your configuration file. Your configuration file will be much smaller and easier to read, and you will have less things to check when eventually upgrading Kerko.</p>"},{"location":"config-params/#babel_default_locale","title":"<code>BABEL_DEFAULT_LOCALE</code>","text":"<p>The default language of the user interface.</p> <p>Type: String  Default value: <code>\"en\"</code></p>"},{"location":"config-params/#babel_default_timezone","title":"<code>BABEL_DEFAULT_TIMEZONE</code>","text":"<p>The timezone to use for user facing times. Any timezone name supported by the pytz package should work.</p> <p>Type: String  Default value: <code>\"UTC\"</code></p>"},{"location":"config-params/#config_files","title":"<code>CONFIG_FILES</code>","text":"<p>Specifies where to look for one or more TOML configuration files. The value must be a semicolon-separated list of file paths.</p> <p>The files are loaded in the specified order. The parameters from each file get merged into the previously known configuration. If a given parameter was already set, its value is overwritten by the one from the later file.</p> <p>Paths may be absolute or relative. Relative paths are resolved from the current working directory. If a specified file is not found there, it is searched by traversing the directories upwards. If the root directory is reached and the file is still not found, then the same search method is reapplied, but this time starting from the <code>INSTANCE_PATH</code>.</p> <p>Type: String  Default value: <code>\"config.toml;instance.toml;.secrets.toml\"</code></p> <p>Environment variable only</p> <p>This parameter is specific to KerkoApp and cannot be set in a TOML file. It can only be set as an environment variable, therefore it should actually be referenced as <code>KERKOAPP_CONFIG_FILES</code>. See environment variables for details.</p>"},{"location":"config-params/#data_path","title":"<code>DATA_PATH</code>","text":"<p>The data path specifies a directory where Kerko may store its cache, search index, and file attachments. This may be provided as an absolute path or as a relative path. If a relative path is given, it will be relative to <code>INSTANCE_PATH</code>.</p> <p>Type: String  Default value: <code>\"kerko\"</code></p>"},{"location":"config-params/#instance_path","title":"<code>INSTANCE_PATH</code>","text":"<p>The instance path specifies a directory where the application may store data and configuration files.</p> <p>Type: String  Default value: Determined by Flask. In practice, the default for KerkoApp users is a directory named <code>instance</code> located at the same level as the <code>wsgi.py</code> file. You may set <code>INSTANCE_PATH</code> to a different directory, which you must specify as an absolute path.</p> <p>Environment variable only</p> <p>This parameter is specific to KerkoApp and cannot be set in a TOML file. It can only be set as an environment variable, therefore it should actually be referenced as <code>KERKOAPP_INSTANCE_PATH</code>. See environment variables for details.</p>"},{"location":"config-params/#logging_address","title":"<code>LOGGING_ADDRESS</code>","text":"<p>Address to send log messages to. Used only if <code>LOGGING_HANDLER</code> is set to <code>\"syslog\"</code>.</p> <p>Type: String  Default value: <code>\"/dev/log\"</code></p>"},{"location":"config-params/#logging_format","title":"<code>LOGGING_FORMAT</code>","text":"<p>Log message format string, with %-style placeholders. Refer to the Python logging documentation for allowed attributes.</p> <p>Type: String  Default value: <code>\"[%(asctime)s] %(levelname)s in %(module)s: %(message)s\"</code></p>"},{"location":"config-params/#logging_handler","title":"<code>LOGGING_HANDLER</code>","text":"<p>Logging handler to use. At this time, the sole allowed value is <code>\"syslog\"</code>. If no value is set, the default handler will write to the default stream (usually <code>sys.stderr</code>).</p> <p>Type: String</p>"},{"location":"config-params/#logging_level","title":"<code>LOGGING_LEVEL</code>","text":"<p>Severity of events to log. Allowed values are <code>\"DEBUG\"</code>, <code>\"INFO\"</code>, <code>\"WARNING\"</code>, <code>\"ERROR\"</code>, and <code>\"CRITICAL\"</code>.</p> <p>Type: String  Default value: <code>\"DEBUG\"</code> if the application is running in debug mode, or <code>\"WARNING\"</code> otherwise.</p>"},{"location":"config-params/#secret_key","title":"<code>SECRET_KEY</code>","text":"<p>This parameter is required for generating secure tokens in web forms. It should have a hard to guess value, and should really remain secret.</p> <p>This parameter is required and has no default value.</p> <p>Type: String</p>"},{"location":"config-params/#zotero_api_key","title":"<code>ZOTERO_API_KEY</code>","text":"<p>This parameter specifies your Zotero API key, as created on zotero.org.</p> <p>Kerko does not need to write to your library. Thus, we recommend that your API key be read-only, and that it does not grant any more access to your Zotero data than strictly necessary.</p> <p>On zotero.org, the API key creation options vary on whether you want to connect Kerko to a personal library or to a group library:</p> Personal libraryGroup library <p>Make sure to check Allow library access, as well as Allow notes access, unless you are certain you won't need any Kerko feature that relies on notes. If you are unsure at this point, we recommend that you allow notes access, otherwise some features might not work, and when that happens you might not remember that it is the API key that is blocking notes access. You can always edit the API key later.</p> <p>We recommend that you use Per group permissions so that access is strictly restricted to the chosen group. Make sure that Read Only is selected for that group. This will grant read-only access to all items of that group, including notes.</p> <p>This parameter is required and has no default value.</p> <p>Type: String</p>"},{"location":"config-params/#zotero_library_id","title":"<code>ZOTERO_LIBRARY_ID</code>","text":"<p>The identifier of the Zotero library to get data from.</p> <p>Finding your library ID:</p> Personal libraryGroup library <p>For a personal library, the value is your userID, as found on zotero.org (you must be logged-in).</p> <p>For a group library this value is the groupID of the library, as found in the URL of the library (e.g., the groupID of the library at <code>https://www.zotero.org/groups/2348869/kerko_demo</code> is <code>\"2348869\"</code>).</p> <p>This parameter is required and has no default value.</p> <p>Type: String</p>"},{"location":"config-params/#zotero_library_type","title":"<code>ZOTERO_LIBRARY_TYPE</code>","text":"<p>The type of library to get data from, either <code>\"user\"</code> for a personal library, or <code>\"group\"</code> for a group library.</p> <p>This parameter is required and has no default value.</p> <p>Type: String</p>"},{"location":"config-params/#kerkobib_formats","title":"<code>kerko.bib_formats.*.</code>","text":"<p>Bibliographic record download formats, where <code>*</code> is a format key.</p> <p>The default formats are:</p> <ul> <li><code>bibtex</code></li> <li><code>ris</code></li> </ul> <p>The configuration system does not allow adding new formats.</p>"},{"location":"config-params/#enabled","title":"<code>enabled</code>","text":"<p>Enable the format. If this is set to <code>false</code>, the format will not be available through any download link.</p> <p>Type: Boolean</p> <p>Modifies the cache and the search index</p> <p>Changing this parameter from <code>false</code> to <code>true</code> will require that you run the <code>sync cache --full</code> and <code>sync index</code> commands. See synchronization commands for details.</p>"},{"location":"config-params/#extension","title":"<code>extension</code>","text":"<p>File extension of the downloadable file.</p> <p>Type: String</p>"},{"location":"config-params/#help_text","title":"<code>help_text</code>","text":"<p>Description of the format, to show in the help window.</p> <p>Type: String</p>"},{"location":"config-params/#label","title":"<code>label</code>","text":"<p>Label to use in the format selector.</p> <p>Type: String</p>"},{"location":"config-params/#mime_type","title":"<code>mime_type</code>","text":"<p>MIME type of the downloadable format.</p> <p>Type: String</p>"},{"location":"config-params/#weight","title":"<code>weight</code>","text":"<p>Relative position of the format in lists. Formats with low weights (small numbers) rise above heavier ones (large numbers).</p> <p>Type: Integer</p>"},{"location":"config-params/#kerkobreadcrumb","title":"<code>kerko.breadcrumb.</code>","text":"<p>A breadcrumb is a navigational aid that displays the location of the current page in relation to the structure of a website.</p> <p>If enabled, the breadcrumb works in relation with the <code>kerko.link_groups.breadcrumb_base</code> parameter, which defines the base (starting links) of the breadcrumb trail, which Kerko dynamically completes with one or more links based on the current location within Kerko.</p>"},{"location":"config-params/#enabled_1","title":"<code>enabled</code>","text":"<p>Enable the breadcrumb.</p> <p>Type: Boolean  Default value: <code>true</code></p>"},{"location":"config-params/#include_current","title":"<code>include_current</code>","text":"<p>Include the current page at the end of the breadcrumb trail. If set to <code>false</code>, the breadcrumb trail will end with the parent page instead of the current page.</p> <p>Type: Boolean  Default value: <code>true</code></p>"},{"location":"config-params/#text_max_length","title":"<code>text_max_length</code>","text":"<p>Maximum length for a breadcrumb item's text (in number of characters). If text is to be truncated in the middle of a word, the whole word is discarded instead. Truncated text is appended with an ellipsis sign (\"...\").</p> <p>If set to <code>0</code>, no truncation will be applied.</p> <p>Type: Integer  Default value: <code>50</code></p>"},{"location":"config-params/#text_max_length_leeway","title":"<code>text_max_length_leeway</code>","text":"<p>If the length of a breadcrumb item's text only exceeds <code>kerko.breadcrumb.text_max_length</code> by this tolerance margin or less (in number of characters), the text will not be truncated.</p> <p>This parameter has no effect if <code>text_max_length</code> is set to <code>0</code> (no truncation).</p> <p>Type: Integer  Default value: <code>10</code></p>"},{"location":"config-params/#kerkofacets","title":"<code>kerko.facets.*.</code>","text":"<p>Facets to provide in the search interface, where <code>*</code> is a facet key. The facet key is used internally by Kerko to identify the facet.</p> <p>The default facets are:</p> <ul> <li><code>item_type</code> (item types facet, enabled by default)</li> <li><code>language</code> (item languages facet, disabled by default)</li> <li><code>link</code> (items with links facet, disabled by default)</li> <li><code>tag</code> (item tags facet, enabled by default)</li> <li><code>year</code> (item years facet, enabled by default)</li> </ul> <p>You may define additional facets. See Defining custom facets based on Zotero collections.</p> <p>Modifies the search index</p> <p>Most of the <code>kerko.facets.*</code> parameters require that you run the <code>clean index</code> and <code>sync index</code> commands after you have changed them. See synchronization commands for details.</p>"},{"location":"config-params/#collection_key","title":"<code>collection_key</code>","text":"<p>Key of the Zotero collection to map the facet to. This must refer to a top-level collection containing at least one hierarchical level of subcollections. Each subcollection will be mapped to a filter under the facet, if it contains at least one item that is not excluded through the <code>kerko.zotero.item_include_re</code> or <code>kerko.zotero.item_exclude_re</code> parameters.</p> <p>This parameter has no default value and is required for facets whose <code>type</code> parameter is set to <code>\"collection\"</code>.</p> <p>Type: String </p>"},{"location":"config-params/#enabled_2","title":"<code>enabled</code>","text":"<p>Enable the facet.</p> <p>Type: Boolean  Default value: depends on which facet you are looking at.</p>"},{"location":"config-params/#filter_key","title":"<code>filter_key</code>","text":"<p>Key to use in URLs when filtering with the facet.</p> <p>Type: String  Default value: depends on which facet you are looking at.</p>"},{"location":"config-params/#initial_limit","title":"<code>initial_limit</code>","text":"<p>Maximum number of filters to show by default under the facet. Excess filters will be shown if the user clicks a \"view more\" button. A value of <code>0</code> means no limit.</p> <p>Type: Integer  Default value: depends on which facet you are looking at.</p>"},{"location":"config-params/#initial_limit_leeway","title":"<code>initial_limit_leeway</code>","text":"<p>If the number of filters under the facet exceeds <code>initial_limit</code> by this tolerance margin or less, all filters will be shown. A value of <code>0</code> means no tolerance margin.</p> <p>Type: Integer  Default value: depends on which facet you are looking at.</p>"},{"location":"config-params/#item_view","title":"<code>item_view</code>","text":"<p>Show the facet on item view pages.</p> <p>Type: Boolean  Default value: depends on which facet you are looking at.</p>"},{"location":"config-params/#sort_by","title":"<code>sort_by</code>","text":"<p>List of criteria used for sorting the filters under the facet. Allowed values in this list are <code>\"count\"</code> and <code>\"label\"</code>.</p> <p>Type: Array of strings  Default value: depends on which facet you are looking at.</p>"},{"location":"config-params/#sort_reverse","title":"<code>sort_reverse</code>","text":"<p>Reverse the sort order of the filters under the facet.</p> <p>Type: Boolean  Default value: depends on which facet you are looking at.</p>"},{"location":"config-params/#title","title":"<code>title</code>","text":"<p>Heading of the facet.</p> <p>Type: String  Default value: depends on which facet you are looking at.</p>"},{"location":"config-params/#type","title":"<code>type</code>","text":"<p>Type of facet. Determines the data source of the facet.</p> <p>Allowed values are:</p> <ul> <li><code>\"collection\"</code>: Use a Zotero collection as source.</li> <li><code>\"item_type\"</code>: Use the item type as source.</li> <li><code>\"language\"</code>: Use item Language field as source.</li> <li><code>\"link\"</code>: Use item URL field as source.</li> <li><code>\"tag\"</code>: Use Zotero tags as source.</li> <li><code>\"year\"</code>: Use the item year field as source.</li> </ul> <p>This parameter is required and has no default value.</p> <p>Type: String</p>"},{"location":"config-params/#weight_1","title":"<code>weight</code>","text":"<p>Relative position of the facet in lists. Facets with low weights (small numbers) rise above heavier ones (large numbers).</p> <p>Type: Integer  Default value: depends on which facet you are looking at.</p>"},{"location":"config-params/#kerkofacetslanguage","title":"<code>kerko.facets.language.</code>","text":"<p>The parameters in this section only apply to the <code>language</code> facet.</p> <p>Source values for the language facet are extracted from the Language field of Zotero items.</p>"},{"location":"config-params/#allow_invalid","title":"<code>allow_invalid</code>","text":"<p>Allow values that are not found in the pycountry language database.</p> <p>This parameter has an effect only if <code>normalize</code> is set to <code>true</code>.</p> <p>If this parameter is set to <code>true</code>, non-standard or badly entered language names will be allowed to appear in the language facet. You may find that you have to clean your data in Zotero if you wish to make the facet usable.</p> <p>If this parameter is set to <code>false</code>, non-standard or badly entered language names will be omitted from the language facet. The facet will only show recognized languages but may give an incomplete picture of all the languages present in your library.</p> <p>Type: Boolean  Default value: <code>true</code></p>"},{"location":"config-params/#locale","title":"<code>locale</code>","text":"<p>The locale to use when displaying language names in the language facet. Translations are provided by pycountry.</p> <p>This parameter has an effect only if <code>normalize</code> is set to <code>true</code>.</p> <p>Type: String  Default value: <code>\"en\"</code></p>"},{"location":"config-params/#normalize","title":"<code>normalize</code>","text":"<p>Normalize language names using the pycountry language database.</p> <p>If this parameter is set to <code>true</code>, slight inconsistencies in your data can be attenuated, preventing unwanted duplicates in the facet. For example, values such as <code>fr</code>, <code>FR</code>, <code>fra</code>, <code>Fra</code>, <code>fre</code>, <code>fr-FR</code>, <code>fr-fr</code>, <code>fr-CA</code>, or <code>French</code> will all fall under a single <code>French</code> term in the facet. The normalization process is case insensitive, ignores country or area codes, and recognizes:</p> <ul> <li>3-letter ISO 639-3 language codes;</li> <li>3-letter ISO 639-2 bibliographic (B) codes;</li> <li>2-letter ISO 639-1 codes;</li> <li>English language names.</li> </ul> <p>Terms not falling into any of the above categories will be considered invalid. To choose what to do with invalid terms, see the <code>allow_invalid</code> parameter.</p> <p>For the best results with the <code>normalize</code> option, we recommend that you record languages in Zotero using 2-letter ISO 639-1 codes (because they also happen to be supported by the Citation Style Language), or 3-letter ISO 639-3 codes for languages not covered by ISO 639-1.</p> <p>If <code>normalize</code> is set to <code>false</code>, item language values will be used verbatim. In that case, the facet will work equally well if your language data is well controlled and consistent. This is the way to go if languages are consistently recorded using their non-English names in your Zotero library.</p> <p>Type: Boolean  Default value: <code>true</code></p>"},{"location":"config-params/#values_separator_re","title":"<code>values_separator_re</code>","text":"<p>Regular expression to use for splitting the content of Zotero's Language field into multiple languages, e.g., <code>en; de; it</code>. We do not necessarily recommend recording multiple languages in the Language field, but in practice some people do when describing multilingual resources.</p> <p>Type: String  Default value: <code>\";\"</code></p>"},{"location":"config-params/#kerkofeatures","title":"<code>kerko.features.</code>","text":""},{"location":"config-params/#download_attachment_new_window","title":"<code>download_attachment_new_window</code>","text":"<p>Open attachments in new tabs. In other words: add the HTML <code>target=\"_blank\"</code> attribute to attachment links.</p> <p>Type: Boolean  Default value: <code>false</code></p>"},{"location":"config-params/#download_item","title":"<code>download_item</code>","text":"<p>Provide a record download button on item pages.</p> <p>To configure the bibliographic formats made available for downloading, see <code>kerko.bib_formats</code>.</p> <p>Type: Boolean  Default value: <code>true</code></p>"},{"location":"config-params/#download_results","title":"<code>download_results</code>","text":"<p>Provide a record download button on search results pages.</p> <p>To configure the bibliographic formats made available for downloading, see <code>kerko.bib_formats</code>.</p> <p>Type: Boolean  Default value: <code>true</code></p>"},{"location":"config-params/#download_results_max_count","title":"<code>download_results_max_count</code>","text":"<p>Limit over which the record download button should be hidden from search results pages.</p> <p>Type: Integer  Default value: <code>0</code> (i.e., no limit)</p>"},{"location":"config-params/#open_in_zotero_app","title":"<code>open_in_zotero_app</code>","text":"<p>On item pages, show a button for opening the corresponding item in the Zotero application (through a link using the <code>zotero://</code> protocol). If this parameter is set to <code>true</code>, a user will still need to first enable the button from the Preferences menu (which can be accessed from the footer of item pages and saves the user's choices in browser cookies). For the link to work, the user must also have the Zotero application installed, and have access to the Zotero library. This feature is generally only useful to library editors and might confuse other users, especially if your Zotero library is private. Thus you should probably enable this option only if there is a strong need from the editors.</p> <p>Type: Boolean  Default value: <code>false</code></p>"},{"location":"config-params/#open_in_zotero_web","title":"<code>open_in_zotero_web</code>","text":"<p>On item pages, show a button for viewing the corresponding item on zotero.org (through a regular hyperlink). If this parameter is set to <code>true</code>, a user will still need to first enable the button from the Preferences menu (which can be accessed from the footer of item pages and saves the user's choices in browser cookies). For the link to work, the user must also have access to the Zotero library. This feature is generally only useful to library editors and might confuse other users, especially if your Zotero library is private. Thus you should probably enable this option only if there is a strong need from the editors.</p> <p>Type: Boolean  Default value: <code>false</code></p>"},{"location":"config-params/#print_item","title":"<code>print_item</code>","text":"<p>Provide a print button on item pages.</p> <p>Type: Boolean  Default value: <code>false</code></p>"},{"location":"config-params/#print_results","title":"<code>print_results</code>","text":"<p>Provide a print button on search results pages.</p> <p>Type: Boolean  Default value: <code>false</code></p>"},{"location":"config-params/#print_results_max_count","title":"<code>print_results_max_count</code>","text":"<p>Limit over which the print button should be hidden from search results pages.</p> <p>Type: Integer  Default value: <code>0</code> (i.e., no limit)</p>"},{"location":"config-params/#relations_initial_limit","title":"<code>relations_initial_limit</code>","text":"<p>Number of related items to show above the \"show more\" link.</p> <p>Type: Integer  Default value: <code>5</code></p>"},{"location":"config-params/#relations_links","title":"<code>relations_links</code>","text":"<p>Show item links in lists of related items.</p> <p>Enabling this only has an effect if at least one of the following variables is also set to <code>true</code>: <code>kerko.features.results_attachment_links</code>, <code>kerko.features.results_url_links</code>.</p> <p>Type: Boolean  Default value: <code>false</code></p>"},{"location":"config-params/#results_abstracts","title":"<code>results_abstracts</code>","text":"<p>Show abstracts on search result pages.</p> <p>Type: Boolean  Default value: <code>false</code> (i.e., hide abstracts)</p>"},{"location":"config-params/#results_abstracts_toggler","title":"<code>results_abstracts_toggler</code>","text":"<p>Show a button letting users show or hide abstracts on search results pages.</p> <p>Type: Boolean  Defaults value: <code>true</code> (i.e., toggle is displayed)</p>"},{"location":"config-params/#results_abstracts_max_length","title":"<code>results_abstracts_max_length</code>","text":"<p>Truncate abstracts at the given length (in number of characters). If text is to be truncated in the middle of a word, the whole word is discarded instead. Truncated text is appended with an ellipsis sign (\"...\").</p> <p>Type: Integer  Default value: <code>0</code> (i.e., abstracts get displayed in their full length, without any truncation)</p>"},{"location":"config-params/#results_abstracts_max_length_leeway","title":"<code>results_abstracts_max_length_leeway</code>","text":"<p>If the length of an abstract only exceeds <code>kerko.features.results_abstracts_max_length</code> by this tolerance margin or less (in number of characters), it will not be truncated.</p> <p>This parameter has no effect if <code>results_abstracts_max_length</code> is set to <code>0</code> (no truncation).</p> <p>Type: Integer  Default value: <code>0</code> (i.e., no tolerance margin).</p>"},{"location":"config-params/#results_attachment_links","title":"<code>results_attachment_links</code>","text":"<p>Provide links to attachments in search results.</p> <p>Type: Boolean  Default value: <code>true</code></p>"},{"location":"config-params/#results_url_links","title":"<code>results_url_links</code>","text":"<p>Provide links to online resources in search results (for items whose URL field has a value).</p> <p>Type: Boolean  Default value: <code>true</code></p>"},{"location":"config-params/#kerkofeeds","title":"<code>kerko.feeds.</code>","text":""},{"location":"config-params/#formats","title":"<code>formats</code>","text":"<p>A list of syndication feed formats to publish.</p> <p>If set to an empty array, no web feed will be provided. The only supported format at this time is <code>'atom'</code>.</p> <p>Type: Array of strings  Default value: <code>[\"atom\"]</code></p>"},{"location":"config-params/#fields","title":"<code>fields</code>","text":"<p>List of fields to retrieve for each feed item. Values in this list are keys identifying fields defined in the <code>kerko_composer</code> object, and the list must contain all fields that are used by the <code>kerko.templates.atom_feed</code> template.</p> <p>One probably only needs to change the default list when overriding the template to display additional fields.</p> <p>Note that some fields from the default list may be required by Kerko, and removing those could cause crashes.</p> <p>Type: Dictionary</p>"},{"location":"config-params/#max_days","title":"<code>max_days</code>","text":"<p>The age (in number of days) of the oldest items allowed into web feeds. The date field of the items is used for that purpose, and when no date is available, the date the item was added to Zotero is used instead.</p> <p>Unless your goal is to promote recent literature only, you should probably keep the default value.</p> <p>Items with missing dates will be considered as very recent, to prevent them from being excluded from feeds. For the same reason, items whose date lack the month and/or the day will be considered as from the 12<sup>th</sup> month of the year and/or the last day of the month.</p> <p>Type: Integer  Default value: <code>0</code> (i.e., no age limit)</p>"},{"location":"config-params/#kerkolink_groups","title":"<code>kerko.link_groups.*.</code>","text":"<p>Link groups, where <code>*</code> is an arbitrary key used for identifying the group. Each group is a list which must contain at least one link defined using one or more of the sub-parameters described below.</p> <p>Link groups can be used for navigation or anywhere hyperlinks are needed. Templates can use the key to retrieve a desired link group.</p> <p>Kerko provides default <code>navbar</code> and <code>breadcrumb_base</code> link groups. In TOML format, these are defined as below (the double brackets indicate a list item):</p> <pre><code>[[kerko.link_groups.navbar]]\ntype = \"endpoint\"\nendpoint = \"kerko.search\"\ntext = \"Bibliography\"\n\n[[kerko.link_groups.breadcrumb_base]]\ntype = \"endpoint\"\nendpoint = \"kerko.search\"\ntext = \"Bibliography\"\n</code></pre>"},{"location":"config-params/#anchor","title":"<code>anchor</code>","text":"<p>Anchor to append to the endpoint's URL.</p> <p>This optional parameter is only allowed when the <code>type</code> parameter is set to <code>\"endpoint\"</code>.</p> <p>Type: String</p>"},{"location":"config-params/#endpoint","title":"<code>endpoint</code>","text":"<p>Name of the endpoint within the application to use as target for the link. Use this for internal links. For example, the endpoint for the Kerko search page is <code>\"kerko.search\"</code>.</p> <p>This parameter is required if the <code>type</code> parameter is set to <code>\"endpoint\"</code> and has no default value.</p> <p>Type: String</p>"},{"location":"config-params/#external","title":"<code>external</code>","text":"<p>Generate a full URL (with scheme and domain) for the endpoint instead of an internal URL.</p> <p>This parameter is only allowed when the <code>type</code> parameter is set to <code>\"endpoint\"</code>.</p> <p>Type: Boolean  Default value: <code>false</code></p>"},{"location":"config-params/#new_window","title":"<code>new_window</code>","text":"<p>Open the link in a new tab.</p> <p>Type: Boolean  Default value: <code>false</code></p>"},{"location":"config-params/#page","title":"<code>page</code>","text":"<p>Key of the page to use as target for the link. That page must have been defined in <code>kerko.pages.*</code>.</p> <p>This parameter is required if the <code>type</code> parameter is set to <code>\"page\"</code> (and cannot be used with other <code>type</code> values).</p> <p>Type: String </p>"},{"location":"config-params/#parameters","title":"<code>parameters</code>","text":"<p>Dictionary of parameters to pass to the endpoint. Unknown keys are appended to the URL as query string arguments, like <code>?a=b&amp;c=d</code>.</p> <p>This optional parameter is only allowed when the <code>type</code> parameter is set to <code>\"endpoint\"</code>.</p> <p>Type: Dictionary</p>"},{"location":"config-params/#scheme","title":"<code>scheme</code>","text":"<p>Protocol to use in the endpoint's URL.</p> <p>This parameter is only allowed when the <code>type</code> parameter is set to <code>\"endpoint\"</code> and the <code>external</code> parameter is set to <code>true</code>.</p> <p>Type: String  Default value: Same protocol as the current request</p>"},{"location":"config-params/#text","title":"<code>text</code>","text":"<p>Text to use for the link.</p> <p>This parameter is required and has no default value.</p> <p>Type: String</p>"},{"location":"config-params/#type_1","title":"<code>type</code>","text":"<p>Type of link being configured. Other parameters may or may not be available depending on this value.</p> <p>Allowed values are:</p> <ul> <li><code>\"endpoint\"</code>: Link to an application page (served by a Flask endpoint).</li> <li><code>\"page\"</code>: Link to a page defined in <code>kerko.pages.*</code>.</li> <li><code>\"url\"</code>: Link to an arbitrary URL.</li> </ul> <p>This parameter is required and has no default value.</p> <p>Type: String</p>"},{"location":"config-params/#url","title":"<code>url</code>","text":"<p>URL of the external link.</p> <p>This parameter is required if the <code>type</code> parameter is set to <code>\"url\"</code>.</p> <p>Type: String</p>"},{"location":"config-params/#weight_2","title":"<code>weight</code>","text":"<p>Relative position of the link in lists. Links with low weights (small numbers) rise above heavier ones (large numbers). At equal weights, links are ordered based on their order of appearance in the configuration.</p> <p>Type: Integer  Default value: <code>0</code></p>"},{"location":"config-params/#kerkometa","title":"<code>kerko.meta.</code>","text":""},{"location":"config-params/#google_analytics_id","title":"<code>google_analytics_id</code>","text":"<p>A Google Analytics measurement ID, e.g., <code>'G-??????????'</code>.</p> <p>If the value is not empty and Flask is not running in debug mode, then the Google Analytics tag is inserted into the pages.</p> <p>Type: String  Default value: <code>\"\"</code></p>"},{"location":"config-params/#highwirepress_tags","title":"<code>highwirepress_tags</code>","text":"<p>Embed Highwire Press tags into the HTML of item pages. This should help search engines such as Google Scholar index your items more accurately, but works only with book, conference paper, journal article, report or thesis items.</p> <p>Type: Boolean  Default value: <code>true</code> (i.e., enabled).</p>"},{"location":"config-params/#title_1","title":"<code>title</code>","text":"<p>The title to display in web pages.</p> <p>Type: String</p>"},{"location":"config-params/#kerkopages","title":"<code>kerko.pages.*.</code>","text":"<p>Simple content pages, where <code>*</code> is an arbitrary key you must choose to uniquely identify the page. The content of the page will come from a Zotero standalone note of your choosing.</p> <p>The key can be used in <code>kerko.link_groups.*</code> tables to define hyperlinks to the page.</p>"},{"location":"config-params/#path","title":"<code>path</code>","text":"<p>The path to use in the URL of the page. Must start with a slash (<code>/</code>) character.</p> <p>Type: String </p>"},{"location":"config-params/#item_id","title":"<code>item_id</code>","text":"<p>The Zotero item ID of the note to use as content for the page.</p> <p>Type: String </p>"},{"location":"config-params/#title_2","title":"<code>title</code>","text":"<p>The title of the page.</p> <p>Type: String </p>"},{"location":"config-params/#kerkopagination","title":"<code>kerko.pagination.</code>","text":""},{"location":"config-params/#page_len","title":"<code>page_len</code>","text":"<p>The number of search results per page.</p> <p>Type: Integer  Default value: <code>20</code></p>"},{"location":"config-params/#pager_links","title":"<code>pager_links</code>","text":"<p>Number of pages to show in the pager (not counting the current page).</p> <p>Type: Integer  Default value: <code>4</code></p>"},{"location":"config-params/#kerkoperformance","title":"<code>kerko.performance.</code>","text":""},{"location":"config-params/#whoosh_index_memory_limit","title":"<code>whoosh_index_memory_limit</code>","text":"<p>Maximum memory (in megabytes) the Whoosh index writer will use for the indexing pool. The higher the number, the faster indexing will be.</p> <p>The actual memory used will be higher than this value because of interpreter overhead (up to twice as much!). Other operations performed by Kerko at indexing time use memory too. Thus, although useful as a tuning parameter, this setting does not allow to exactly control the memory usage.</p> <p>Type: Integer  Default value: 128</p>"},{"location":"config-params/#whoosh_index_processors","title":"<code>whoosh_index_processors</code>","text":"<p>Controls the number of processors Whoosh will use for indexing.</p> <p>Note that when you use multiprocessing, the <code>whoosh_index_memory_limit</code> parameter controls the amount of memory used by each process, so the actual memory used will be <code>whoosh_index_memory_limit</code> \u00d7 <code>whoosh_index_processors</code>.</p> <p>Type: Integer  Default value: 1</p>"},{"location":"config-params/#kerkoscopes","title":"<code>kerko.scopes.*.</code>","text":"<p>Keyword search scopes, where <code>*</code> is a scope key. The scope key is used internally by Kerko to identify the scope. Scopes allow users to restrict the search to some fields.</p> <p>The default scopes are:</p> <ul> <li><code>all</code></li> <li><code>creator</code></li> <li><code>fulltext</code></li> <li><code>metadata</code></li> <li><code>pubyear</code></li> <li><code>title</code></li> </ul> <p>You may define additional scopes.</p> <p>To link fields to scopes, see <code>kerko.search_fields.scopes</code>.</p>"},{"location":"config-params/#breadbox_label","title":"<code>breadbox_label</code>","text":"<p>Label to use when the scope appears in the breadbox, i.e. in the list of search criteria.</p>"},{"location":"config-params/#enabled_3","title":"<code>enabled</code>","text":"<p>Enable the scope.</p> <p>Type: Boolean</p>"},{"location":"config-params/#help_text_1","title":"<code>help_text</code>","text":"<p>Description of the scope, to show in the help window.</p> <p>Type: String</p>"},{"location":"config-params/#selector_label","title":"<code>selector_label</code>","text":"<p>Label to use in the scope selector.</p> <p>Type: String</p>"},{"location":"config-params/#weight_3","title":"<code>weight</code>","text":"<p>Relative position of the scope in lists. Scopes with low weights (small numbers) rise above heavier ones (large numbers).</p> <p>Type: Integer</p>"},{"location":"config-params/#kerkosearch","title":"<code>kerko.search.</code>","text":""},{"location":"config-params/#fulltext","title":"<code>fulltext</code>","text":"<p>Allow full-text search of PDF attachments.</p> <p>Type: Boolean  Default value: <code>true</code></p> <p>Tip</p> <p>To get consistent results with full-text search, see Ensuring full-text indexing of your attachments in Zotero.</p> <p>Tip</p> <p>When setting <code>kerko.search.fulltext</code> to <code>false</code>, it is recommended that you set <code>kerko.scopes.fulltext.enabled</code> and <code>kerko.scopes.metadata.enabled</code> to <code>false</code> as well. With full-text data unavailable, the <code>fulltext</code> scope is useless, and the <code>metadata</code> scope gives the same results as the <code>all</code> scope.</p> <p>Modifies the cache and the search index</p> <p>Changing this parameter will require that you run the <code>sync cache --full</code> and <code>sync index</code> commands. See synchronization commands for details.</p>"},{"location":"config-params/#result_fields","title":"<code>result_fields</code>","text":"<p>List of item fields to retrieve for search results (most notably used by the <code>kerko.templates.search_item</code> template).</p> <p>Values in this list are keys identifying fields defined in the <code>kerko.composer.Composer</code> instance. One probably only needs to change the default list when overriding the template to display additional fields.</p> <p>Note that some fields from the default list may be required by Kerko, and removing those could cause crashes.</p> <p>Type: Array of strings  Default value: <code>[\"id\", \"attachments\", \"bib\", \"coins\", \"data\", \"url\"]</code></p>"},{"location":"config-params/#whoosh_language","title":"<code>whoosh_language</code>","text":"<p>The language of search requests.</p> <p>As of this writing, Whoosh supports the following languages: ar, da, nl, en, fi, fr, de, hu, it, no, pt, ro, ru, es, sv, tr. You may refer to Whoosh's source code to get the list of supported languages (see <code>whoosh.lang.languages</code>) and the list of languages that support stemming (see <code>whoosh.lang.has_stemmer()</code>).</p> <p>Type: String  Default value: <code>\"en\"</code></p> <p>Modifies the search index</p> <p>Changing this parameter will require that you run the <code>sync index --full</code> command. See synchronization commands for details.</p>"},{"location":"config-params/#kerkosearch_fields","title":"<code>kerko.search_fields.*.</code>","text":"<p>Searchable fields, where <code>*</code> is a field key. The default fields fall into different tables:</p> <ul> <li><code>core.optional.*</code>: These fields have limited parameters. Their only allowed   parameters are <code>boost</code>, <code>enabled</code>, and <code>scopes</code>.</li> <li><code>core.required.*</code>: These fields cannot be disabled. Their only allowed   parameters are <code>boost</code> and <code>scopes</code>.</li> <li><code>zotero.*</code>: These fields derive directly from Zotero item fields and allow all   field parameters.</li> </ul> <p>The configuration system does not allow adding new fields.</p> <p>Modifies the search index</p> <p>Changing any of the <code>kerko.search_fields.*</code> parameters will require that you run the <code>clean index</code> and <code>sync index</code> commands, except if you are just disabling a field or changing its <code>scopes</code> parameter. See synchronization commands for details.</p>"},{"location":"config-params/#analyzer","title":"<code>analyzer</code>","text":"<p>Type of analysis to apply to the field value when building the search index.</p> <p>Allowed values:</p> <ul> <li><code>\"id\"</code>: Index the entire value of the field as one token.</li> <li><code>\"name\"</code>: Apply standard tokenization and filtering, but without stemming.</li> <li><code>\"text\"</code>: Apply standard tokenization, stemming and filtering.</li> </ul> <p>Type: String</p>"},{"location":"config-params/#boost","title":"<code>boost</code>","text":"<p>Scaling factor to apply to score when matches are found in the field.</p> <p>Type: Float</p>"},{"location":"config-params/#enabled_4","title":"<code>enabled</code>","text":"<p>Enable the field.</p> <p>Type: Boolean</p>"},{"location":"config-params/#scopes","title":"<code>scopes</code>","text":"<p>List of keyword search scopes that will exploit the field.</p> <p>Allowed values are determined by <code>kerko.scopes</code>.</p> <p>Type: Array of strings</p>"},{"location":"config-params/#kerkosorts","title":"<code>kerko.sorts.*.</code>","text":"<p>Search results sorting options, where <code>*</code> is a sort option key.</p> <p>The default sort options are:</p> <ul> <li><code>author_asc</code></li> <li><code>author_desc</code></li> <li><code>date_asc</code></li> <li><code>date_desc</code></li> <li><code>score</code></li> <li><code>title_asc</code></li> <li><code>title_desc</code></li> </ul> <p>The configuration system does not allow adding new sort options.</p>"},{"location":"config-params/#enabled_5","title":"<code>enabled</code>","text":"<p>Enable the sort option.</p> <p>Type: Boolean</p>"},{"location":"config-params/#label_1","title":"<code>label</code>","text":"<p>Label of the sort option.</p> <p>Type: String</p>"},{"location":"config-params/#weight_4","title":"<code>weight</code>","text":"<p>Relative position of the sort option in lists. Sort options with low weights (small numbers) rise above heavier ones (large numbers).</p> <p>The default sort option will be the one with the lowest weight.</p> <p>Type: Integer</p> <p>Tip</p> <p>It is recommended that <code>kerko.sorts.score.weight</code> has the smallest value of all your sort options. Thus, when a keyword search is performed, sorting by relevance score will be the default, and when no keywords are used in the search, then the sort option with the second smallest weight will be the default one.</p>"},{"location":"config-params/#kerkotemplates","title":"<code>kerko.templates.</code>","text":""},{"location":"config-params/#search","title":"<code>search</code>","text":"<p>Name of the Jinja2 template to render for the search page with list of results.</p> <p>Type: String  Default value: <code>\"kerko/search.html.jinja2\"</code></p>"},{"location":"config-params/#search_item","title":"<code>search_item</code>","text":"<p>Name of the Jinja2 template to render for the search page with a single bibliographic record.</p> <p>Type: String  Default value: <code>\"kerko/search-item.html.jinja2\"</code></p>"},{"location":"config-params/#item","title":"<code>item</code>","text":"<p>Name of the Jinja2 template to render for the bibliographic record view.</p> <p>Type: String  Default value: <code>\"kerko/item.html.jinja2\"</code></p>"},{"location":"config-params/#atom_feed","title":"<code>atom_feed</code>","text":"<p>Name of the Jinja2 template used to render an Atom feed.</p> <p>Type: String  Default value: <code>\"kerko/atom.xml.jinja2\"</code></p>"},{"location":"config-params/#layout","title":"<code>layout</code>","text":"<p>Name of the Jinja2 template that is extended by the search, search-item, and item templates.</p> <p>Type: String  Default value: <code>\"kerko/layout.html.jinja2\"</code></p>"},{"location":"config-params/#base","title":"<code>base</code>","text":"<p>Name of the Jinja2 template that is extended by the layout template.</p> <p>Type: String  Default value: <code>\"kerko/base.html.jinja2\"</code></p>"},{"location":"config-params/#kerkozotero","title":"<code>kerko.zotero.</code>","text":""},{"location":"config-params/#attachment_mime_types","title":"<code>attachment_mime_types</code>","text":"<p>List of allowed MIME types for attachments.</p> <p>Type: Array of strings  Default value: <code>[\"application/pdf\"]</code></p> <p>Modifies the attachments</p> <p>Changing this parameter will require that you run the <code>sync attachments</code> command. See synchronization commands for details.</p>"},{"location":"config-params/#csl_style","title":"<code>csl_style</code>","text":"<p>The citation style to use for formatted references.</p> <p>Allowed values are either a file name (without the <code>.csl</code> extension) found in the Zotero Styles Repository (e.g., <code>\"apa\"</code>) or the publicly accessible URL of a remote CSL file.</p> <p>Type: String  Default value: <code>\"apa\"</code>.</p> <p>Modifies the cache and the search index</p> <p>Changing this parameter will require that you run the <code>sync cache --full</code> and <code>sync index</code> commands. See synchronization commands for details.</p>"},{"location":"config-params/#batch_size","title":"<code>batch_size</code>","text":"<p>Number of items to request on each call to the Zotero API.</p> <p>Type: Integer  Default value: <code>100</code> (this is the maximum currently allowed by the Zotero API)</p>"},{"location":"config-params/#child_include_re","title":"<code>child_include_re</code>","text":"<p>Regular expression to use to include children (e.g. notes, attachments) based on their tags. Any child which does not have a tag that matches this regular expression will be ignored. If this value is empty (which is the default), all children will be accepted unless <code>kerko.zotero.child_exclude_re</code> is set and causes some to be rejected.</p> <p>Type: String  Default value: <code>\"\"</code></p> <p>Modifies the search index and attachments</p> <p>Changing this parameter will require that you run the <code>sync index --full</code> and <code>sync attachments</code> commands. See synchronization commands for details.</p>"},{"location":"config-params/#child_exclude_re","title":"<code>child_exclude_re</code>","text":"<p>Regular expression to use to exclude children (e.g. notes, attachments) based on their tags. Any child that have a tag that matches this regular expression will be ignored. If empty, no children will be rejected unless <code>kerko.zotero.child_include_re</code> is set and the tags of those children do not match it. By default, any child having at least one tag that begins with an underscore character (<code>_</code>) is rejected.</p> <p>Type: String  Default value: <code>\"^_\"</code></p> <p>Modifies the search index and attachments</p> <p>Changing this parameter will require that you run the <code>sync index --full</code> and <code>sync attachments</code> commands. See synchronization commands for details.</p>"},{"location":"config-params/#item_include_re","title":"<code>item_include_re</code>","text":"<p>Regular expression to use to include items based on their tags. Any item which does not have a tag that matches this regular expression will be ignored. If this value is empty (which is the default), all items will be accepted unless <code>kerko.zotero.item_exclude_re</code> is set which can cause some items to be rejected.</p> <p>Type: String  Default value: <code>\"\"</code></p> <p>Modifies the search index and attachments</p> <p>Changing this parameter will require that you run the <code>sync index --full</code> and <code>sync attachments</code> commands. See synchronization commands for details.</p>"},{"location":"config-params/#item_exclude_re","title":"<code>item_exclude_re</code>","text":"<p>Regular expression to use to exclude items based on their tags. Any item that have a tag that matches this regular expression will be excluded. If empty (which is the default), no items will be excluded unless <code>kerko.zotero.item_include_re</code> is set, in which case items that do not have any tag that matches it will be excluded.</p> <p>Type: String  Default value: <code>\"\"</code></p> <p>Modifies the search index and attachments</p> <p>Changing this parameter will require that you run the <code>sync index --full</code> and <code>sync attachments</code> commands. See synchronization commands for details.</p>"},{"location":"config-params/#locale_1","title":"<code>locale</code>","text":"<p>The locale to use with Zotero API calls. This dictates the locale of Zotero item types, field names, creator types and citations. Supported locales are listed at https://api.zotero.org/schema, under \"locales\".</p> <p>Type: String  Default value: <code>\"en-US\"</code></p> <p>Modifies the cache and the search index</p> <p>Changing this parameter will require that you run the <code>sync cache --full</code> and <code>sync index</code> commands. See synchronization commands for details.</p>"},{"location":"config-params/#max_attempts","title":"<code>max_attempts</code>","text":"<p>Maximum number of tries after the Zotero API has returned an error or has not responded during indexing.</p> <p>Type: Integer  Default value: <code>10</code></p>"},{"location":"config-params/#tag_include_re","title":"<code>tag_include_re</code>","text":"<p>Regular expression to use to include tags. By default, all tags are accepted.</p> <p>Note that record exports (downloads) always include all tags regardless of this parameter, which only applies to information displayed by Kerko (exports are generated by the Zotero API, not by Kerko).</p> <p>Type: String  Default value: <code>\"\"</code></p> <p>Modifies the search index</p> <p>Changing this parameter will require that you run the <code>sync index --full</code> command. See synchronization commands for details.</p>"},{"location":"config-params/#tag_exclude_re","title":"<code>tag_exclude_re</code>","text":"<p>Regular expression to use to exclude tags. The default value causes any tag that begins with an underscore character (<code>_</code>) to be ignored by Kerko.</p> <p>Note that record exports (downloads) always include all tags regardless of this parameter, which only applies to information displayed by Kerko (exports are generated by the Zotero API, not by Kerko).</p> <p>Type: String  Default value: <code>\"^_\"</code></p> <p>Modifies the search index</p> <p>Changing this parameter will require that you run the <code>sync index --full</code> command. See synchronization commands for details.</p>"},{"location":"config-params/#wait","title":"<code>wait</code>","text":"<p>Time to wait (in seconds) between failed attempts to call the Zotero API.</p> <p>Type: Integer  Default value: <code>120</code></p>"},{"location":"config-params/#kerkoappproxy_fix","title":"<code>kerkoapp.proxy_fix.</code>","text":"<p>When an application is running behind a proxy server, WSGI may see the request as coming from that server rather than the real client. Proxies set various headers to track where the request actually came from.</p> <p>In that case you must tell the application how many proxies set each header so it knows what values to trust. However, enable this ONLY if the application is actually running behind a proxy; it would be a security issue to trust values that came directly from the client rather than a proxy.</p> <p>Refer to Tell Flask it is behind a proxy for details.</p> <p>Warning</p> <p>This parameter is specific to KerkoApp.</p>"},{"location":"config-params/#enabled_6","title":"<code>enabled</code>","text":"<p>Enable the proxy parameters.</p> <p>All other <code>kerkoapp.proxy_fix</code> parameters are ignored unless this is set to <code>true</code>.</p> <p>Type: Boolean  Default value: <code>false</code></p>"},{"location":"config-params/#x_for","title":"<code>x_for</code>","text":"<p>Number of values to trust for <code>X-Forwarded-For</code>.</p> <p>Type: Integer  Default value: <code>1</code></p>"},{"location":"config-params/#x_proto","title":"<code>x_proto</code>","text":"<p>Number of values to trust for <code>X-Forwarded-Proto</code>.</p> <p>Type: Integer  Default value: <code>1</code></p>"},{"location":"config-params/#x_host","title":"<code>x_host</code>","text":"<p>Number of values to trust for <code>X-Forwarded-Host</code>.</p> <p>Type: Integer  Default value: <code>0</code></p>"},{"location":"config-params/#x_port","title":"<code>x_port</code>","text":"<p>Number of values to trust for <code>X-Forwarded-Port</code>.</p> <p>Type: Integer  Default value: <code>0</code></p>"},{"location":"config-params/#x_prefix","title":"<code>x_prefix</code>","text":"<p>Number of values to trust for <code>X-Forwarded-Prefix</code>.</p> <p>Type: Integer  Default value: <code>0</code></p>"},{"location":"contributing/","title":"Contributing","text":"<p>This section provides guidance on how to contribute to the Kerko project.</p>"},{"location":"contributing/#reporting-issues","title":"Reporting issues","text":"<p>Before reporting an issue, please consider the following guidelines:</p> <ul> <li>Try to identify whether the issue belongs to Kerko or to KerkoApp. Then   submit the issue to the proper issue tracker, either Kerko's,   or KerkoApp's.</li> <li>Search existing issues, in case the same issue has already been reported or   even fixed in the repository.</li> <li>Describe what happened when you experienced the issue. Include the full   traceback if an exception was raised.</li> <li>Describe what you expected to happen.</li> <li>If possible, include a minimal reproducible example to help others identify   the issue.</li> </ul>"},{"location":"contributing/#making-code-changes","title":"Making code changes","text":"<p>Clone the Kerko repository into a local directory. Set up a virtual environment, then install that local version of Kerko in the virtual environment, including development and testing dependencies by running the following command from Kerko's root directory, i.e., where <code>setup.cfg</code> resides:</p> <pre><code>pip install -e .[dev,docs,tests]\n</code></pre>"},{"location":"contributing/#running-the-tests","title":"Running the tests","text":"<p>To run the test suite:</p> <pre><code>python -m unittest\n</code></pre> <p>To check code coverage as well, use these commands instead:</p> <pre><code>coverage run -m unittest\ncoverage report\n</code></pre> <p>To run the full test suite under different environments (using the various Python interpreters available on your machine):</p> <pre><code>tox\n</code></pre> <p>Note</p> <p>Test coverage is still low at the moment. You are welcome to contribute new tests!</p>"},{"location":"contributing/#running-the-pre-commit-hooks","title":"Running the pre-commit hooks","text":"<p>Pre-commit checks should be performed automatically whenever you perform a <code>git commit</code>. If you wish to run the checks manually, use this command:</p> <pre><code>pre-commit run --all-files\n</code></pre>"},{"location":"contributing/#working-on-the-documentation","title":"Working on the documentation","text":"<p>To start a local live-reloading documentation server:</p> <pre><code>mkdocs serve\n</code></pre> <p>Then view the documentation in your browser at http://localhost:8000/.</p>"},{"location":"contributing/#building-the-distribution-package","title":"Building the distribution package","text":"<p>When building the distribution package, a version number is dynamically extracted from the Git repository. For an official release, the Git head revision must be tagged prior to building the distribution package. When the revision is not tagged, a dev version number gets derived from the branch's most recent tag, with a suffix appended.</p> <p>To check the version number that will be generated:</p> <pre><code>hatch version\n</code></pre> <p>To build the distribution package in sdist and wheel formats:</p> <pre><code>hatch build\n</code></pre>"},{"location":"contributing/#submitting-code-changes","title":"Submitting code changes","text":"<p>Pull requests may be submitted against Kerko's repository. Please consider the following guidelines:</p> <ul> <li>Before submitting, run the tests and make sure they pass. Add tests relevant   to your change (those should fail if ran without your patch).</li> <li>Use Ruff to format Python code.</li> <li>If a Jinja2 template represents a page fragment or a collection of macros,   prefix its file name with the underscore character.</li> <li>Update the relevant sections of the documentation.</li> <li>Include a string like \"Fixes #123\" in your commit message (where 123 is the   issue you fixed). See Closing issues using   keywords.</li> </ul>"},{"location":"contributing/#submitting-a-translation","title":"Submitting a translation","text":"<p>Some guidelines:</p> <ul> <li>The PO file encoding must be UTF-8.</li> <li>The header of the PO file must be filled out appropriately.</li> <li>All messages of the PO file must be translated.</li> </ul> <p>Please submit your translation as a pull request against the proper repository, either Kerko's, or KerkoApp's, or by e-mail, with the PO file included as an attachment (do not copy the PO file's content into an e-mail's body, since that could introduce formatting or encoding issues).</p>"},{"location":"contributing/#supporting-the-project","title":"Supporting the project","text":"<p>Nurturing an open source project, following up on issues and helping others in working with the system is a lot of work. Hiring the original developers of Kerko can help make the project sustainable. It is the best way to ensure continued support and development of the project.</p> <p>If you need professional support related to Kerko, have requirements not currently implemented in Kerko, want to make sure that some Kerko issue important to you gets resolved, or if you just like our work and would like to hire us for an unrelated project, please e-mail us.</p>"},{"location":"deploying/","title":"How to deploy","text":"<p>As there is a great diversity of operating systems, hosting environments, and WSGI servers, it is hard to provide universal and useful instructions for setting up KerkoApp for use in production.</p> <p>You can expect a procedure similar to that of any Flask application, and there are many guides on the web covering this topic for various environments.</p> <p>That said, you may refer to the guide below for step-by-step instructions. Even if your environment is different from the one this guide was designed for, it might provide you with some useful hints.</p>"},{"location":"deploying/#deploying-on-ubuntu-with-nginx-and-gunicorn","title":"Deploying on Ubuntu with nginx and gunicorn","text":"<p>These instructions will detail the steps and configurations required to get KerkoApp running on an Ubuntu 22.04 or 24.04 web server, using Gunicorn as the WSGI container and nginx as a HTTP proxy.</p> <p>The procedure is similar that of any Flask application, but KerkoApp-specific steps are also covered here.</p> <p>Install some required packages, including Python 3:</p> <pre><code>sudo apt install git nginx python3 python3-pip python3-venv\n</code></pre> <p>Create the user who will run the app:</p> <pre><code>sudo groupadd --system kerkoapp\nsudo useradd --gid kerkoapp --shell /bin/bash --create-home --home-dir /home/kerkoapp --groups www-data kerkoapp\n</code></pre> <p>Switch to that user and clone the desired version of KerkoApp. If you want to use version 1.0.0, for example, replace <code>VERSION</code> in the command below with <code>1.0.0</code>:</p> <pre><code>sudo su kerkoapp\ngit clone --branch VERSION https://github.com/whiskyechobravo/kerkoapp.git ~/kerkoapp\n</code></pre> <p>Still as user <code>kerkoapp</code>, create a Python virtual environment and install the Python packages required by KerkoApp:</p> <pre><code>python3 -m venv ~/venv\nsource ~/venv/bin/activate\npip3 install -r ~/kerkoapp/requirements/run.txt\npip3 install gunicorn\n</code></pre> <p>Always as user <code>kerkoapp</code>, create the <code>~/.secrets.toml</code> file. This is where you will put secret keys that should only be known to your server. Its content should look like the following:</p> .secrets.toml<pre><code>SECRET_KEY = \"MY_SECRET_KEY\"\nZOTERO_API_KEY = \"MY_ZOTERO_API_KEY\"\n</code></pre> <p>You must set <code>SECRET_KEY</code> with a random string, and <code>ZOTERO_API_KEY</code> with an appropriate value (see configuration parameters).</p> <p>Then create the <code>~/instance.toml</code> file. This file will contain settings that are specific to your server, but are not secret. Its content should look like the following:</p> instance.toml<pre><code>LOGGING_HANDLER = \"syslog\"\n\n[kerkoapp.proxy_fix]\nenabled = true\nx_for = 1\nx_proto = 1\nx_host = 1\nx_port = 0\nx_prefix = 0\n</code></pre> <p>We are enabling the <code>kerkoapp.proxy_fix</code> parameters because we will configure nginx as a reverse proxy.</p> <p>Then create the <code>~/config.toml</code> file. This file will contain general settings for Kerko. You might have already tested KerkoApp on your desktop computer and created such file. If so, you could just copy that file to your server. At the very least it should contain the following settings:</p> config.toml<pre><code>ZOTERO_LIBRARY_ID = \"MY_ZOTERO_LIBRARY_ID\"\nZOTERO_LIBRARY_TYPE = \"MY_ZOTERO_LIBRARY_TYPE\"\n\n[kerko.meta]\ntitle = \"My Bibliography\"\n</code></pre> <p>You must set <code>ZOTERO_LIBRARY_ID</code> and <code>ZOTERO_LIBRARY_TYPE</code> with appropriate values (see configuration parameters) so that Kerko can connect to your Zotero library.</p> <p>It is not absolutely necessary to use three separate configuration files for KerkoApp as we just did. You could, for example, have just <code>~/instance.toml</code> and put all of the settings there. However, it is a good practice to split the configuration, and that allows you to copy <code>config.toml</code> from or to other machines, or even share it with other people, without worrying about leaking secret keys or messing up your server-specific settings.</p> <p>Once the configuration files are ready, Kerko should be able to talk to Zotero. Have Kerko retrieve your Zotero library's data by running the following command:</p> <pre><code>flask --debug kerko sync\n</code></pre> <p>The <code>--debug</code> switch is optional. If you use it, some messages will give you an better idea of the progress of the sync process. If you omit it, the command will run silently unless there are warnings or errors.</p> <p>Depending on the size of your library, this process can complete within less than a minute or take an hour or more. Zotero throttles API requests to prevent its servers from getting overloaded, so sometimes the process might seem to freeze, but be patient and Kerko will resume synchronization a few minutes later.</p> <p>Now that synchronization works, configure the cron task that will synchronize data from your Zotero library on a regular basis. Run the following command (always from the <code>kerkoapp</code> user):</p> <pre><code>crontab -e\n</code></pre> <p>That will launch the default <code>nano</code> editor. Add the following line at the very bottom, then save the file and exit the editor:</p> crontab<pre><code>10 4 * * * cd /home/kerkoapp/kerkoapp &amp;&amp; /home/kerkoapp/venv/bin/flask kerko sync\n</code></pre> <p>That will synchronize the data once a day, at 4:10am. You may specify a different time, of course.</p> <p>Now exit from the <code>kerkoapp</code> user's shell, and go back to your usual sudoer account to finish the installation.</p> <p>Configure a socket that will let Gunicorn to speak with nginx. As the superuser, create the <code>/etc/systemd/system/kerkoapp.socket</code> file, with the following content:</p> kerkoapp.socket<pre><code>[Unit]\nDescription=KerkoApp socket\n\n[Socket]\nListenStream=/run/kerkoapp.socket\n\n[Install]\nWantedBy=kerkoapp.target\n</code></pre> <p>Configure a service that will run Gunicorn. As the superuser, create the <code>/etc/systemd/system/kerkoapp.service</code> file, with the following content:</p> kerkoapp.service<pre><code>[Unit]\nDescription=KerkoApp daemon\nRequires=kerkoapp.socket\nAfter=network.target\n\n[Service]\nWorkingDirectory=/home/kerkoapp/kerkoapp\nExecStart=/home/kerkoapp/venv/bin/gunicorn wsgi:app --name kerkoapp --user kerkoapp --group www-data --workers 4 --log-level warning --error-logfile - --access-logfile - --bind unix:/run/kerkoapp.socket\nExecReload=/bin/kill -s HUP $MAINPID\nExecStop=/bin/kill -s TERM $MAINPID\nPrivateTmp=true\n\n[Install]\nWantedBy=multi-user.target\n</code></pre> <p>Reload the systemd configurations, then enable and start the new service by running the following commands:</p> <pre><code>sudo systemctl daemon-reload\nsudo systemctl enable kerkoapp.socket\nsudo systemctl enable kerkoapp.service\nsudo systemctl start kerkoapp.socket\n</code></pre> <p>You can check whether the socket is active with this command:</p> <pre><code>sudo systemctl status kerkoapp.socket\n</code></pre> <p>If it shows up as 'active (listening)', you may now verify that it triggers the service:</p> <pre><code>curl --unix-socket /run/kerkoapp.socket localhost\nsudo systemctl status kerkoapp.service\n</code></pre> <p>The <code>curl</code> command should output some HTML, and the <code>systemctl</code> command should now show the KerkoApp daemon as 'active (running)'.</p> <p>If either the socket or the service doesn't work, you might want to check for errors in the log:</p> <pre><code>sudo journalctl --unit=kerkoapp\n</code></pre> <p>Once all of the above works, configure nginx to pass requests to Gunicorn. As the superuser, create the <code>/etc/nginx/sites-available/kerkoapp.conf</code> file with the following content, replacing <code>example.com</code> with your actual domain name:</p> kerkoapp.conf<pre><code>server {\n    listen 80;\n    server_name example.com;\n\n    location / {\n        proxy_redirect off;\n        proxy_set_header Host $http_host;\n        proxy_set_header X-Real-IP $remote_addr;\n        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n        proxy_set_header X-Forwarded-Host $server_name;\n        proxy_set_header X-Forwarded-Proto $scheme;\n\n        if (!-f $request_filename) {\n            proxy_pass http://unix:/run/kerkoapp.socket;\n            break;\n        }\n    }\n}\n</code></pre> <p>Enable the site by running the following command:</p> <pre><code>sudo ln -s /etc/nginx/sites-available/kerkoapp.conf /etc/nginx/sites-enabled/\n</code></pre> <p>Have nginx test the configuration:</p> <pre><code>sudo nginx -t\n</code></pre> <p>If the command reports the configuration test as successful, reload nginx to make the configuration changes effective:</p> <pre><code>sudo service nginx reload\n</code></pre> <p>You should now be able to view your KerkoApp site at http://example.com!</p> <p>The nginx configuration above will serve the application using the HTTP protocol. As for any website, HTTPS is strongly recommended. That will require that you install a SSL certificate and configure nginx to use it; that exercise is left to the reader.</p> <p>Changing the configuration can be disruptive</p> <p>Making any change to a configuration file requires that you at least restart the application afterwards for the change to become effective.</p> <p>Moreover, some parameters have an effect on the structure of the cache or the search index that Kerko depends on. Changing this kind of parameter may require that you rebuild either. Refer to the documentation of the parameter to check if specific actions need to be taken after a change.</p> <p>The commands below, for example, will allow you to clean and rebuild the search index, and to restart KerkoApp:</p> <pre><code>sudo -iu kerkoapp bash -c 'cd /home/kerkoapp/kerkoapp &amp;&amp; /home/kerkoapp/venv/bin/flask kerko clean index'\nsudo -iu kerkoapp bash -c 'cd /home/kerkoapp/kerkoapp &amp;&amp; /home/kerkoapp/venv/bin/flask kerko sync'\nsudo systemctl stop kerkoapp.socket\nsudo systemctl start kerkoapp.socket\n</code></pre>"},{"location":"deploying/#submitting-your-sitemap-to-search-engines","title":"Submitting your sitemap to search engines","text":"<p>Kerko generates an XML Sitemap that can help search engines discover your bibliographic records.</p> <p>The path of the sitemap is <code>BASE_URL/sitemap.xml</code>, where <code>BASE_URL</code> should be replaced with the protocol, domain, port, and Kerko URL path prefix that are relevant to your installation, e.g., <code>https://example.com/bibliography/sitemap.xml</code>.</p> <p>Different search engines may have different procedures for submitting sitemaps (Google, Bing, Yandex).</p> <p>However, a standard method consists in adding a <code>Sitemap</code> directive to a <code>robots.txt</code> file served at the root of your site, to tell web crawlers where to find your sitemap. For example, one might add the following line to <code>robots.txt</code>:</p> <pre><code>Sitemap: https://example.com/bibliography/sitemap.xml\n</code></pre> <p>A <code>robots.txt</code> file can have multiple <code>Sitemap</code> directives, thus the Kerko sitemap can be specified alongside any other sitemaps you might already have.</p>"},{"location":"getting-started/","title":"Getting started","text":"<p>For getting started with Kerko, we recommend that you use KerkoApp. However, if KerkoApp is not suited to your use case, we also have instructions for creating a custom application.</p>"},{"location":"getting-started/#getting-started-with-kerkoapp","title":"Getting started with KerkoApp","text":"<p>To install KerkoApp, you may choose between a \"standard\" installation and a Docker installation. Just go with the option you feel most comfortable with. If you don't know Docker, you should be fine with the standard installation. But if you prefer to keep your distance from Python-related stuff, perhaps the Docker installation will suit you best.</p>"},{"location":"getting-started/#standard-installation","title":"Standard installation","text":"<p>This procedure requires that you have Python, pip, and Git installed on your computer.</p> <ol> <li> <p>The first step is to install the desired version of KerkoApp. You may check    the list of available versions, but make sure to choose    one that matches the documentation version you are currently reading! For    version 1.0.0, for example, replace <code>VERSION</code> with <code>1.0.0</code> in the commands    below:</p> POSIXWindows <pre><code>git clone --branch VERSION https://github.com/whiskyechobravo/kerkoapp.git\ncd kerkoapp\npython -m venv venv\nsource venv/bin/activate\npip install -r requirements/run.txt\n</code></pre> <pre><code>git clone --branch VERSION https://github.com/whiskyechobravo/kerkoapp.git\ncd kerkoapp\npython -m venv venv\nvenv\\Scripts\\activate.bat\npip install -r requirements\\run.txt\n</code></pre> <p>This will install all packages required by Kerko and KerkoApp within a virtual environment.</p> </li> <li> <p>Copy the <code>sample.secrets.toml</code> file to <code>.secrets.toml</code> in the same directory.    Open <code>.secrets.toml</code> in a text editor to assign proper values to the    parameters outlined below:</p> <ul> <li><code>SECRET_KEY</code>: This parameter is required for generating secure tokens in   web forms. It should have a hard to guess value, and should really remain   secret. For this reason, never add your <code>.secrets.toml</code> file to a code   repository.</li> <li><code>ZOTERO_API_KEY</code>: Your Zotero API key. See API key creation   instructions.</li> </ul> </li> <li> <p>Copy the <code>sample.config.toml</code> file to <code>config.toml</code> in the same directory.    Open <code>config.toml</code> in a text editor to assign proper values to the parameters    outlined below:</p> <ul> <li><code>ZOTERO_LIBRARY_ID</code>: The identifier of the Zotero library to get   data from. For a personal library the value is your userID, as found on   https://www.zotero.org/settings/keys (you must be logged-in). For a group   library this value is the groupID of the library, as found in the URL of   the library (e.g., the groupID of the library at   https://www.zotero.org/groups/2348869/kerko_demo is <code>\"2348869\"</code>).</li> <li><code>ZOTERO_LIBRARY_TYPE</code>: The type of library to get data from,   either <code>\"user\"</code> for a personal library, or <code>\"group\"</code> for a group library.</li> </ul> <p>You do not need to edit other parameters at this point, but later on <code>config.toml</code> is where your configuration changes will take place.</p> </li> <li> <p>Have KerkoApp synchronize your data from zotero.org:</p> <pre><code>flask --debug kerko sync\n</code></pre> <p>If you have a large Zotero library and/or large file attachments, that command may take a while to complete. Wait until the command finishes. In production use, this command is usually added to the crontab file for regular execution.</p> <p>The <code>--debug</code> switch is optional. If you use it, some messages will give you an idea of the sync process' progress. If you omit it, the command will run silently unless there are warnings or errors.</p> <p>To list all commands provided by Kerko:</p> <pre><code>flask kerko --help\n</code></pre> </li> <li> <p>Run KerkoApp:</p> <pre><code>flask --debug run\n</code></pre> </li> <li> <p>Open http://localhost:5000/ in your browser and explore the bibliography!</p> </li> </ol> <p>Running your installed application</p> <p>To launch the application again in a future session, make sure to reactivate the virtual environment first. The command sequence should look like:</p> POSIXWindows <pre><code>cd kerkoapp\nsource venv/bin/activate\nflask --debug run\n</code></pre> <pre><code>cd kerkoapp\nvenv\\Scripts\\activate.bat\nflask --debug run\n</code></pre> <p>Not suitable for production</p> <p>The above procedure relies on Flask's built-in server, which is not suitable for production. For production use, you should consider better options such as the WSGI servers suggested in the Flask documentation.</p>"},{"location":"getting-started/#docker-installation","title":"Docker installation","text":"<p>This procedure requires that Docker is installed on your computer.</p> <ol> <li> <p>Copy the <code>Makefile</code>, <code>sample.secrets.toml</code>, and <code>sample.config.toml</code> files    from the most recent stable branch of the KerkoApp repository (e.g.    https://github.com/whiskyechobravo/kerkoapp/tree/stable/1.0.x) to an empty    directory on your computer.</p> </li> <li> <p>Under the same directory, create a subdirectory named <code>instance</code>. This is    where you will put your configuration files, and where Kerko will save its    data.</p> </li> <li> <p>Copy <code>sample.secrets.toml</code> as <code>.secrets.toml</code> into the <code>instance</code>    subdirectory. Open <code>instance/.secrets.toml</code> in a text editor to assign proper    values to the configuration parameters outlined below:</p> <ul> <li><code>SECRET_KEY</code>: This parameter is required for generating secure tokens in   web forms. It should have a hard to guess value, and should really remain   secret. For this reason, never add your <code>.secrets.toml</code> file to a code   repository.</li> <li><code>ZOTERO_API_KEY</code>: Your Zotero API key. See API key creation   instructions.</li> </ul> </li> <li> <p>Copy <code>sample.config.toml</code> as <code>config.toml</code> into the <code>instance</code> subdirectory.    Open <code>instance/config.toml</code> in a text editor to assign proper values to the    configuration parameters outlined below:</p> <ul> <li><code>ZOTERO_LIBRARY_ID</code>: The identifier of the Zotero library to get   data from. For a personal library the value is your userID, as found on   https://www.zotero.org/settings/keys (you must be logged-in). For a group   library this value is the groupID of the library, as found in the URL of   the library (e.g., the groupID of the library at   https://www.zotero.org/groups/2348869/kerko_demo is <code>\"2348869\"</code>).</li> <li><code>ZOTERO_LIBRARY_TYPE</code>: The type of library to get data from,   either <code>\"user\"</code> for a personal library, or <code>\"group\"</code> for a group library.</li> </ul> <p>It should not be necessary to change other settings at this point. You can always come back later to this file in order to configure KerkoApp to your liking. For now, we suggest that you proceed to the next step and get it running.</p> </li> <li> <p>From the same directory as <code>Makefile</code>, run KerkoApp:</p> <pre><code>make run\n</code></pre> <p>This command should do many things:</p> <ul> <li>Download and install the latest KerkoApp Docker image from DockerHub.</li> <li>Run the Docker container to have KerkoApp retrieve your data from   zotero.org.</li> <li>Run the Docker container to launch the KerkoApp server.</li> </ul> <p>If your configuration files have errors, the process may be interrupted; if that happens, retry <code>make run</code> after correcting the problem. Otherwise, if all goes well, you will only have to wait a bit for the data synchronization process to complete. This may take a long time if you have a large Zotero library.</p> <p>Kerko's data will be stored in the <code>instance</code> subdirectory.</p> <p>KerkoApp should launch once the synchronization process has completed. When you see the following message in the terminal, proceed to the next step:</p> <pre><code>[INFO] Listening at: http://0.0.0.0:80\n</code></pre> </li> <li> <p>Open http://localhost:8080/ in your browser and explore the bibliography!</p> </li> </ol> <p>To stop the KerkoApp server, press Ctrl+C in the terminal where the container is running.</p> <p>The next time you execute <code>make run</code>, it will find that the image has been already been downloaded and the data synchronized, and thus it will just launch the server.</p> <p>Using the Kerko command line interface (CLI) with Docker</p> <p>To use Kerko's command line interface, enter this command from the same directory as <code>Makefile</code>:</p> <pre><code>make shell\n</code></pre> <p>This will start an interactive shell within the Docker container. From there, you may run Kerko commands to clean Kerko's data, to synchronize from zotero.org, or to check Kerko's configuration. The command below lists all the commands provided by Kerko:</p> <pre><code>flask kerko --help\n</code></pre> <p>To exit the interactive shell, enter <code>exit</code> or press Ctrl+D at the command prompt.</p> <p>Building a Docker image for production</p> <p>The <code>Makefile</code> is just an example that shows how to build and interact with a dockerized KerkoApp. For production use, you might want to clone the full KerkoApp repository, make some changes to its <code>Dockerfile</code>, and build your own image.</p> <p>For full documentation on how to run Docker containers, including port mapping and volume binding, see the Docker documentation.</p>"},{"location":"getting-started/#creating-a-custom-application","title":"Creating a custom application","text":"<p>This section should help you understand the minimal steps required for setting up Kerko within a custom Flask application.</p> <p>Tip</p> <p>For a ready-to-use standalone application, you will be better off using KerkoApp instead.</p> <p>Some familiarity with Flask should help you make more sense of the instructions, but should not be absolutely necessary for getting them to work. Let's now build a minimal app:</p> <ol> <li> <p>Create an empty directory <code>myapp</code> where your application reside.</p> </li> <li> <p>Install Kerko in a new virtual environment:</p> POSIXWindows <pre><code>cd myapp\npython -m venv venv\nsource venv/bin/activate\npip install kerko\n</code></pre> <pre><code>cd myapp\npython -m venv venv\nvenv\\Scripts\\activate.bat\npip install kerko\n</code></pre> </li> <li> <p>In the <code>myapp</code> directory, create a file named <code>.env</code>, where parameters    required by Kerko will be configured, with content such as the example below:</p> <pre><code>MYAPP_SECRET_KEY=\"your-random-secret-key\"\nMYAPP_ZOTERO_API_KEY=\"xxxxxxxxxxxxxxxxxxxxxxxx\"\nMYAPP_ZOTERO_LIBRARY_ID=\"9999999\"\nMYAPP_ZOTERO_LIBRARY_TYPE=\"group\"\n</code></pre> <p>Replace each value with a proper one. The meaning of each parameter is outlined below:</p> <ul> <li><code>MYAPP_SECRET_KEY</code>: This parameter is required for generating secure   tokens in web forms. It should have a hard to guess value, and should   really remain secret. For this reason, never add your <code>.env</code> file to a   code repository.</li> <li><code>MYAPP_ZOTERO_API_KEY</code>: Your Zotero API key. See API key creation   instructions.</li> <li><code>MYAPP_ZOTERO_LIBRARY_ID</code>: The identifier of the Zotero library to get   data from. For a personal library the value is your userID, as found on   https://www.zotero.org/settings/keys (you must be logged-in). For a group   library this value is the groupID of the library, as found in the URL of   the library (e.g., the groupID of the library at   https://www.zotero.org/groups/2348869/kerko_demo is <code>\"2348869\"</code>).</li> <li><code>MYAPP_ZOTERO_LIBRARY_TYPE</code>: The type of library to get data from,   either <code>\"user\"</code> for a personal library, or <code>\"group\"</code> for a group library.</li> </ul> <p>A <code>.env</code> file is a good place to store an application's secrets. It is good practice to keep this file only on the machine where the application is hosted, and to never push it to a code repository.</p> </li> <li> <p>Create a file named <code>wsgi.py</code> with the following content:</p> wsgi.py<pre><code>import kerko\nfrom flask import Flask\nfrom flask_babel import Babel\nfrom flask_bootstrap import Bootstrap4\nfrom kerko.composer import Composer\nfrom kerko.config_helpers import config_set, config_update, validate_config\n\napp = Flask(__name__)\n</code></pre> <p>The above imports required modules and creates the Flask application object (<code>app</code>). Then, load the default Kerko configuration, and update it from values set in <code>.env</code>:</p> wsgi.py<pre><code># Initialize app configuration with Kerko's defaults.\nconfig_update(app.config, kerko.DEFAULTS)\n\n# Update app configuration from environment variables.\napp.config.from_prefixed_env(prefix=\"MYAPP\")\n</code></pre> <p>Next, adjust general application parameters to your liking. For example, we can use the <code>config_set</code> function to set the main title of the web application to <code>\"My App\"</code>. This function can be called each time you wish to set a configuration option.</p> wsgi.py<pre><code># Make changes to the Kerko configuration here, if desired.\nconfig_set(app.config, \"kerko.meta.title\", \"My App\")\n</code></pre> <p>Next, have Kerko parse and validate the configuration. Then create the <code>kerko_composer</code> object, which provides key elements needed by Kerko such as the fields to display and search, and the facets made available for filtering:</p> wsgi.py<pre><code># Validate configuration and save its parsed version.\nparse_config(app.config)\n\n# Initialize the Composer object.\napp.config[\"kerko_composer\"] = Composer(app.config)\n\n# Make changes to the Kerko composer object here, if desired.\n</code></pre> <p>Using methods of the <code>Composer</code> class, your application could alter the <code>kerko_composer</code> object if needed, to add, remove or alter fields, facets, sort options, search scopes, record download formats, or badges.</p> <p>Finally, initialize extensions required by Kerko (see the respective documentations of Flask-Babel and Bootstrap-Flask for more details), and register the Kerko blueprint with the application object:</p> wsgi.py<pre><code>babel = Babel(app)\nbootstrap = Bootstrap4(app)\n\napp.register_blueprint(kerko.make_blueprint(), url_prefix=\"/bibliography\")\n</code></pre> <p>The <code>url_prefix</code> argument given above defines the base path for every URL provided by Kerko.</p> <p>Note</p> <p>The full code example is available on GitHub.</p> </li> <li> <p>In the same directory as <code>wsgi.py</code> with your virtual environment active, run    the following shell commands:</p> <pre><code>flask --debug kerko sync\n</code></pre> <p>If you have a large Zotero library and/or large file attachments, that command may take a while to complete. Wait until the command finishes. In production use, this command is usually added to the crontab file for regular execution.</p> <p>The <code>--debug</code> switch is optional. If you use it, some messages will give you an idea of the sync process' progress. If you omit it, the command will run silently unless there are warnings or errors.</p> <p>To list all commands provided by Kerko:</p> <pre><code>flask kerko --help\n</code></pre> </li> <li> <p>Run your application:</p> <pre><code>flask --debug run\n</code></pre> </li> <li> <p>Open http://127.0.0.1:5000/bibliography/ in your browser and explore the    bibliography!</p> </li> </ol> <p>You have just built a really minimal application for Kerko. However, if you are looking at developing a custom Kerko application, we recommend that you still look at KerkoApp for a more advanced starting point. While still small, KerkoApp adds some structure as well as features such as TOML configuration files, translations loading, a syslog logging handler, and error pages.</p>"},{"location":"localization/","title":"Localization","text":"<p>This section is about adapting Kerko for specific regions or languages. For this purpose, the main issues to consider are:</p> <ul> <li>The language of the user interface. Kerko defaults to English but translations   for languages are available. To configure a language other than English, see   <code>BABEL_DEFAULT_LOCALE</code>. If no   translation is available for the desired language, or if the existing   translation needs to be updated, see Translating Kerko   and Translating KerkoApp below.</li> <li>The timezone to apply when displaying times. To configure the timezone, see   <code>BABEL_DEFAULT_TIMEZONE</code>.</li> <li>The language and locale used by Zotero, which determines the display names of   fields, item types, and author types, and can impact citation formatting as   well. To configure this, see <code>kerko.zotero.locale</code>.</li> <li>The language analysis applied by the Whoosh search engine. To configure this,   see <code>kerko.search.whoosh_language</code>.</li> </ul>"},{"location":"localization/#translating-kerko","title":"Translating Kerko","text":"<p>Kerko translations are managed with Babel.</p> <p>The following commands should be executed from the root Kerko directory (the one that contains <code>babel.cfg</code>), and the virtual environment must have been activated beforehand.</p> <p>Create or update the PO template (POT) file. Replace <code>CURRENT_VERSION</code> with the current Kerko version:</p> <pre><code>pybabel extract -F babel.cfg -o src/kerko/translations/kerko.pot --project=Kerko --version=CURRENT_VERSION --copyright-holder=\"Kerko Contributors\" src/kerko\n</code></pre> <p>Create a new PO file (for a new locale) based on the POT file. Replace <code>YOUR_LOCALE</code> with the appropriate language code, e.g., <code>de</code>, <code>es</code>, <code>fr</code>:</p> <pre><code>pybabel init -l YOUR_LOCALE -D kerko -i src/kerko/translations/kerko.pot -d src/kerko/translations\n</code></pre> <p>Update an existing PO file based on the POT file:</p> <pre><code>pybabel update -l YOUR_LOCALE -D kerko -i src/kerko/translations/kerko.pot -d src/kerko/translations\n</code></pre> <p>Compile MO files:</p> <pre><code>pybabel compile -l YOUR_LOCALE -D kerko -d src/kerko/translations --statistics\n</code></pre> <p>Contributing your translation</p> <p>You are welcome to contribute your translation. See Submitting a translation. It is only thanks to user contributions that Kerko is available in multiple languages.</p>"},{"location":"localization/#translating-kerkoapp","title":"Translating KerkoApp","text":"<p>Although most user interface messages come from Kerko, KerkoApp also has messages of its own, and thus its own separate translation file.</p> <p>KerkoApp translations are managed with Babel.</p> <p>The following commands should be executed from the root KerkoApp directory (the one that contains <code>babel.cfg</code>), and the virtual environment must have been activated beforehand.</p> <p>Create or update the PO file template (POT). Replace <code>CURRENT_VERSION</code> with your current KerkoApp version:</p> <pre><code>pybabel extract -F babel.cfg -o kerkoapp/translations/messages.pot --project=KerkoApp --version=CURRENT_VERSION --copyright-holder=\"Kerko Contributors\" kerkoapp\n</code></pre> <p>Create a new PO file (for a new locale) based on the POT file. Replace <code>YOUR_LOCALE</code> with the appropriate language code, e.g., <code>de</code>, <code>es</code>, <code>it</code>:</p> <pre><code>pybabel init -l YOUR_LOCALE -i kerkoapp/translations/messages.pot -d kerkoapp/translations\n</code></pre> <p>Update an existing PO file based on the POT file:</p> <pre><code>pybabel update -l YOUR_LOCALE -i kerkoapp/translations/messages.pot -d kerkoapp/translations\n</code></pre> <p>Compile MO files:</p> <pre><code>pybabel compile -l YOUR_LOCALE -d kerkoapp/translations\n</code></pre>"},{"location":"synchronization/","title":"Synchronization","text":"<p>Kerko synchronizes its data from Zotero through a 3-step process:</p> <ol> <li>Update a cache of the Zotero library.</li> <li>Update the search index from the cache.</li> <li>Download file attachments from Zotero.</li> </ol> <p>The first step is an incremental update of the cache, which is a local copy of the library. To this end, Kerko uses the Zotero API to request items and collections from the library on zotero.org. Unless the library is getting synchronized for the first time by Kerko, this will only request new and changed items from Zotero in order to reduce the number of API requests.</p> <p>The second step reads data from the cache to update the search index. If the cache has changed since the last update, a full update of the search index is performed. No Zotero API calls are made during this step. Any changes to the search index are only committed at the end of this step, thus while the update is taking place users still see the data as it was prior to the synchronization run.</p> <p>The third and last step reads the list of file attachments from the search index, with their MD5 hashes. It compares the hashes with those of the available local copies of the files, and downloads new or changed files from Zotero. It also deletes any local files that may no longer be used.</p> <p>Usually, all synchronization steps should be executed. But under certain circumstances it can be useful to run a specific step alone. For example, after changing certain configuration settings, instead of cleaning all data and performing a lengthy full synchronization from Zotero, one may clean just the search index and rebuild it from the cache.</p> <p>Note</p> <p>The synchronization process is unidirectional, where Kerko pulls data from Zotero. Kerko will never try to write anything to your Zotero library.</p>"},{"location":"synchronization/#command-line-interface-cli","title":"Command line interface (CLI)","text":"<p>Kerko provides an integration with the Flask command line interface. The <code>flask</code> command will work with your virtual environment active.</p> <p>Before running a command, go to the application's directory (where the <code>wsgi.py</code> file is found). That is the easiest way to help Flask discover the application.</p> <p>Some frequently used commands are:</p> <code>flask kerko --help</code> <p>Lists all commands provided by Kerko.</p> <code>flask kerko sync</code> <p>Synchronizes everything: the cache (from Zotero), the search index (from the   cache), the attachments (from files in Zotero, based on list in search index).</p> <p>Tip: Making commands more verbose</p> <p>The <code>--debug</code> option may be used with any Flask command and will cause Kerko to output more information. It will tell quite a bit more about what is happening during the synchronization process. For example:</p> <pre><code>flask --debug kerko sync\n</code></pre> <code>flask kerko sync --help</code> <p>Shows help specifically about the <code>sync</code> command:</p> <code>flask kerko sync index</code> <p>Synchronizes just the search index (from the cache).</p> <code>flask kerko sync cache --full</code> <p>When possible, the synchronization process performs an incremental update of   just the new or changed items. Here, the <code>--full</code> option forces a full   synchronization of the cache, even if no or just some items have been updated   since the last synchronization of the cache.</p> <p>This can be useful after changing certain configuration parameters.</p> <code>flask kerko clean everything</code> <p>Deletes all of Kerko's data: cache, search index, attachments.</p> <code>flask kerko clean --help</code> <p>Shows help about the clean command.</p> <code>flask kerko clean cache</code> <p>Deletes just the cache. A subsequent execution of <code>flask kerko sync</code> will   perform a full update from Zotero, but it will not re-download all file   attachments.</p> <p>This does not affect the search index. Thus, if the index was built before a <code>clean cache</code>, users will still be able to access the bibliography using the Kerko web interface.</p> <code>flask kerko clean index</code> <p>Deletes just the search index. The bibliography will become unavailable to the   Kerko web interface until the index gets synchronized again.</p> <p>It can be necessary to use this command after changing certain configuration parameters, and you will usually want to run <code>flask kerko sync index</code> immediately after.</p> <code>flask kerko config</code> <p>Output a consolidated view of all configuration parameters, from all of your   configuration files, and including the defaults provided by Kerko that you may   not have explicitly configured.</p>"},{"location":"synchronization/#monitoring-data-synchronization","title":"Monitoring data synchronization","text":"<p>Kerko provides a web API endpoint that you could use to monitor data synchronization.</p> <p>In the description below, <code>BASE_URL</code> should be replaced with the protocol, domain, port, and Kerko URL path prefix that are relevant to your installation, e.g., <code>https://example.com/bibliography</code>.</p> <p>The web API endpoint is:</p> <code>BASE_URL/api/last-sync</code> <p>Returns a JSON object with information about the last synchronization from   Zotero. If no sync has been performed yet, it returns an empty JSON object,   otherwise the returned object contains the following values:</p> <code>hours_ago</code> <p>Number of hours since the last sync.</p> <code>when</code> <p>ISO 8601 date string with the date and time of the last sync.</p> Sample JSON output<pre><code>{\n  \"hours_ago\": 17.029,\n  \"when\": \"2023-05-24T11:10:29.093335-04:00\"\n}\n</code></pre>"},{"location":"troubleshooting/","title":"Troubleshooting","text":""},{"location":"troubleshooting/#no-such-command-kerko-error-when-running-flask","title":"No such command \"kerko\" error when running Flask","text":"<p>Make sure to run the <code>flask</code> command from the application's directory (where the <code>wsgi.py</code> file is found).</p> <p>To run it from other directories, you could use the <code>--app</code> option, or to set the <code>FLASK_APP</code> environment variable. See application discovery for details.</p> <p>For example:</p> <pre><code>flask --app=/path/to/kerkoapp/wsgi:app kerko sync\n</code></pre>"},{"location":"troubleshooting/#configuration-parameter-change-has-no-effect","title":"Configuration parameter change has no effect","text":"<p>Restart the application. This is required for any configuration change to take effect.</p> <p>If the change still appears to have no effect after a restart, use the following command to verify that the desired parameter value is actually being used:</p> <pre><code>flask --debug kerko config\n</code></pre> <p>If the parameter's value is not the expected one, check your configuration files. If you are uncertain about which configuration files are being loaded by the application, check the first few lines printed by the above command; these list the TOML files in their loading order. Remember that a later file can override values set in a previous one. If you are still unable to trace the source of an incorrect parameter value, check your environment variables. Environment variables can override parameter values set in TOML configuration files.</p> <p>If, on the other hand, the parameter's value is the desired one, then review the documentation for that parameter. Make sure you understand the effect of the parameter value, and check for any notes or warnings. Some parameters require a rebuild of the cache or the search index to become effective.</p>"},{"location":"troubleshooting/#custom-application-conflicting-package-versions-with-standard-installation","title":"Custom application: Conflicting package versions with standard installation","text":"<p>The <code>requirements/run.txt</code> file specifies a precise version for each required package, ensuring consistent results with the last environment KerkoApp was tested with. If some of these packages are already present in your Python environment, their versions are likely to be different and some Python code outside KerkoApp might require those versions. In that case, try replacing <code>run.txt</code> with <code>run.in</code> in the install command:</p> <pre><code>pip install -r requirements/run.in\n</code></pre> <p>Requirements in <code>run.in</code> are more flexible regarding the versions. If you still have version conflicts with those requirements, you'll have to find out which version to use, checking that it is compatible with both KerkoApp and your other Python code.</p>"},{"location":"upgrading/","title":"How to upgrade","text":"<p>Before attempting any upgrade, it is highly recommended that you do a backup of all of your code, configuration files, data files, and Python virtual environment.</p>"},{"location":"upgrading/#from-10x-to-11x-or-12x","title":"From 1.0.x to 1.1.x or 1.2.x","text":""},{"location":"upgrading/#kerkoapp","title":"KerkoApp","text":"<p>The instructions below make the assumption that you have cloned KerkoApp from its Git repository.</p> <ul> <li>Go to the KerkoApp directory.</li> <li> <p>Get the desired version of KerkoApp. You may check the list of available   versions. For version 1.1.0, for example, replace   <code>VERSION</code> with <code>1.1.0</code> in the command below:</p> <pre><code>git fetch &amp;&amp; git checkout VERSION\n</code></pre> </li> <li> <p>Activate your Python virtual environment.</p> </li> <li> <p>Install Python dependencies:</p> <pre><code>pip install --force-reinstall -r requirements/run.txt\n</code></pre> </li> <li> <p>Adapt your configuration file:</p> <ul> <li>Make sure the <code>kerko.feeds.fields</code> parameter is either omitted or has at   least the following values: <code>[\"id\", \"data\", \"item_fields\"]</code>.</li> </ul> </li> <li> <p>Rebuild your search index using the following commands:</p> <pre><code>flask kerko clean index\nflask kerko sync index\n</code></pre> </li> <li> <p>Restart the application.</p> </li> </ul>"},{"location":"upgrading/#custom-applications","title":"Custom applications","text":"<p>If you have a custom application, the following changes will need to be applied:</p> <ul> <li> <p>The application is now responsible for instantiating the blueprint by calling   <code>kerko.make_blueprint()</code>. Any previous uses of the global <code>kerko.blueprint</code>   object must be replaced, as Kerko no longer provides it. If registration was   your application's only use of that object, the change could look like:</p> Before<pre><code>app.register_blueprint(kerko.blueprint, url_prefix='/bibliography')\n</code></pre> After<pre><code>app.register_blueprint(kerko.make_blueprint(), url_prefix='/bibliography')\n</code></pre> <p>... where <code>app</code> is the <code>Flask</code> object.</p> </li> </ul>"},{"location":"upgrading/#from-09-to-10x","title":"From 0.9 to 1.0.x","text":"<p>Version 1.0.x brings significant changes on how Kerko can be configured. Before you attempt an upgrade, reading Configuration basics is a must.</p>"},{"location":"upgrading/#kerkoapp_1","title":"KerkoApp","text":"<p>The instructions below make the assumption that you have cloned KerkoApp from its Git repository.</p> <ul> <li>Go to the KerkoApp directory.</li> <li> <p>Rename the default branch of your local KerkoApp repository:</p> <pre><code>git branch -m master main\ngit fetch origin\ngit branch -u origin/main main\ngit remote set-head origin -a\n</code></pre> </li> <li> <p>Get the desired version of KerkoApp. You may check the list of available   versions. For version 1.0.0, for example, replace   <code>VERSION</code> with <code>1.0.0</code> in the command below:</p> <pre><code>git checkout VERSION\n</code></pre> </li> <li> <p>Activate your Python virtual environment.</p> </li> <li> <p>Install Python dependencies:</p> <pre><code>pip install --force-reinstall -r requirements/run.txt\n</code></pre> </li> <li> <p>Rename the <code>.env</code> file to <code>dotenv.old</code>. We no longer want KerkoApp to use that   file, but it might be useful to keep it as reference while we migrate the   configuration.</p> </li> <li>Create two files, <code>.secrets.toml</code> and <code>config.toml</code>, in the KerkoApp   directory, i.e., the directory where <code>wsgi.py</code> is found.</li> <li>Copy the <code>SECRET_KEY</code> and <code>KERKO_ZOTERO_API_KEY</code> lines from <code>dotenv.old</code> into   <code>.secrets.toml</code>. In <code>.secrets.toml</code>, rename the <code>KERKO_ZOTERO_API_KEY</code>   parameter to <code>ZOTERO_API_KEY</code>. For each of the two parameters, make sure the   value following the equal sign (<code>=</code>) is surrounded by double quotes (<code>\"</code>). To   ascertain the syntax, you may have a look at the <code>sample.secrets.toml</code> file   provided by KerkoApp.</li> <li>Copy the remaining lines from <code>dotenv.old</code> to <code>config.toml</code>. For each   parameter, use the list below to determine if something special needs to be   done to migrate it. Almost all configuration parameters have been renamed   and/or moved into a hierarchical structure (indicated by an arrow (\u2192)). Check   the parameter values too as the syntax of a TOML file is slightly different   from that of a <code>.env</code> file, e.g., in TOML string values must be surrounded by   double quotes (<code>\"</code>), and booleans values must be either <code>true</code> or <code>false</code>   (lowercase, no quotes). Refer to the parameters   documentation for additional information, and have a look   at the <code>sample.config.toml</code> file provided by KerkoApp.<ul> <li><code>DEBUG</code>: Remove. Debug mode is now activated with the <code>--debug</code> command   line option.</li> <li><code>FLASK_APP</code>: Probably not needed anymore. In doubt, please refer to the   Flask documentation on application   discovery.   If you do need this variable, then a <code>.env</code> file could be the right place.   It will not work from a TOML file. Note also that the application is now   referenced as <code>wsgi.app</code> instead of <code>kerkoapp.app</code>.</li> <li><code>FLASK_ENV</code>: Remove. Flask 2.3 stopped supporting it. Debug mode is now   activated with the <code>--debug</code> command line option.</li> <li><code>KERKO_BOOTSTRAP_VERSION</code> \u2192 <code>kerko.assets.bootstrap_version</code></li> <li><code>KERKO_CSL_STYLE</code> \u2192 <code>kerko.zotero.csl_style</code></li> <li><code>KERKO_COMPOSER</code> \u2192 <code>kerko_composer</code></li> <li><code>KERKO_DATA_DIR</code> \u2192 <code>DATA_PATH</code>. Now optional, relative to the instance   path, and defaulting to <code>kerko</code> instead of <code>data/kerko</code>.</li> <li><code>KERKO_DOWNLOAD_ATTACHMENT_NEW_WINDOW</code> \u2192 <code>kerko.features.download_attachment_new_window</code></li> <li><code>KERKO_DOWNLOAD_CITATIONS_LINK</code> \u2192 <code>kerko.features.download_results</code></li> <li><code>KERKO_DOWNLOAD_CITATIONS_MAX_COUNT</code> \u2192 <code>kerko.features.download_results_max_count</code></li> <li><code>KERKO_FEEDS</code> \u2192 <code>kerko.feeds.formats</code></li> <li><code>KERKO_FEEDS_FIELDS</code> \u2192 <code>kerko.feeds.fields</code></li> <li><code>KERKO_FEEDS_MAX_DAYS</code> \u2192 <code>kerko.feeds.max_days</code></li> <li><code>KERKO_FEEDS_REJECT_ANY</code> \u2192 <code>kerko.feeds.reject_any</code></li> <li><code>KERKO_FEEDS_REQUIRE_ANY</code> \u2192 <code>kerko.feeds.require_any</code></li> <li><code>KERKO_FULLTEXT_SEARCH</code> \u2192 <code>kerko.search.fulltext</code></li> <li><code>KERKO_HIGHWIREPRESS_TAGS</code> \u2192 <code>kerko.meta.highwirepress_tags</code></li> <li><code>KERKO_JQUERY_VERSION</code> \u2192 <code>kerko.assets.jquery_version</code></li> <li><code>KERKO_PAGE_LEN</code> \u2192 <code>kerko.pagination.page_len</code></li> <li><code>KERKO_PAGER_LINKS</code> \u2192 <code>kerko.pagination.pager_links</code></li> <li><code>KERKO_POPPER_VERSION</code> \u2192 <code>kerko.assets.popper_version</code></li> <li><code>KERKO_PRINT_CITATIONS_LINK</code> \u2192 <code>kerko.features.print_results</code></li> <li><code>KERKO_PRINT_CITATIONS_MAX_COUNT</code> \u2192 <code>kerko.features.print_results_max_count</code></li> <li><code>KERKO_PRINT_ITEM_LINK</code> \u2192 <code>kerko.features.print_item</code></li> <li><code>KERKO_RELATIONS_INITIAL_LIMIT</code> \u2192 <code>kerko.features.relations_initial_limit</code></li> <li><code>KERKO_RELATIONS_LINKS</code> \u2192 <code>kerko.features.relations_links</code></li> <li><code>KERKO_RELATIONS_SORT</code> \u2192 <code>kerko.features.relations_sort</code></li> <li><code>KERKO_RESULTS_ABSTRACTS</code> \u2192 <code>kerko.features.results_abstracts</code></li> <li><code>KERKO_RESULTS_ABSTRACTS_MAX_LENGTH</code> \u2192 <code>kerko.features.results_abstracts_max_length</code></li> <li><code>KERKO_RESULTS_ABSTRACTS_MAX_LENGTH_LEEWAY</code> \u2192 <code>kerko.features.results_abstracts_max_length_leeway</code></li> <li><code>KERKO_RESULTS_ABSTRACTS_TOGGLER</code> \u2192 <code>kerko.features.results_abstracts_toggler</code></li> <li><code>KERKO_RESULTS_ATTACHMENT_LINKS</code> \u2192 <code>kerko.features.results_attachment_links</code></li> <li><code>KERKO_RESULTS_FIELDS</code> \u2192 <code>kerko.search.result_fields</code></li> <li><code>KERKO_RESULTS_URL_LINKS</code> \u2192 <code>kerko.features.results_url_links</code></li> <li><code>KERKO_TEMPLATE_ATOM_FEED</code> \u2192 <code>kerko.templates.atom_feed</code></li> <li><code>KERKO_TEMPLATE_BASE</code> \u2192 <code>kerko.templates.base</code></li> <li><code>KERKO_TEMPLATE_ITEM</code> \u2192 <code>kerko.templates.item</code></li> <li><code>KERKO_TEMPLATE_LAYOUT</code> \u2192 <code>kerko.templates.layout</code></li> <li><code>KERKO_TEMPLATE_SEARCH</code> \u2192 <code>kerko.templates.search</code></li> <li><code>KERKO_TEMPLATE_SEARCH_ITEM</code> \u2192 <code>kerko.templates.search_item</code></li> <li><code>KERKO_TITLE</code> \u2192 <code>kerko.meta.title</code></li> <li><code>KERKO_USE_TRANSLATIONS</code>: Remove.</li> <li><code>KERKO_WHOOSH_LANGUAGE</code> \u2192 <code>kerko.search.whoosh_language</code></li> <li><code>KERKO_WITH_JQUERY</code> \u2192 <code>kerko.assets.with_jquery</code></li> <li><code>KERKO_WITH_POPPER</code> \u2192 <code>kerko.assets.with_popper</code></li> <li><code>KERKO_ZOTERO_API_KEY</code> \u2192 <code>ZOTERO_API_KEY</code></li> <li><code>KERKO_ZOTERO_BATCH_SIZE</code> \u2192 <code>kerko.zotero.batch_size</code></li> <li><code>KERKO_ZOTERO_LIBRARY_ID</code> \u2192 <code>ZOTERO_LIBRARY_ID</code></li> <li><code>KERKO_ZOTERO_LIBRARY_TYPE</code> \u2192 <code>ZOTERO_LIBRARY_TYPE</code></li> <li><code>KERKO_ZOTERO_LOCALE</code> \u2192 <code>kerko.zotero.locale</code></li> <li><code>KERKO_ZOTERO_MAX_ATTEMPTS</code> \u2192 <code>kerko.zotero.max_attempts</code></li> <li><code>KERKO_ZOTERO_WAIT</code> \u2192 <code>kerko.zotero.wait</code></li> <li><code>KERKOAPP_CHILD_EXCLUDE_RE</code> \u2192 <code>kerko.zotero.child_exclude_re</code></li> <li><code>KERKOAPP_CHILD_INCLUDE_RE</code> \u2192 <code>kerko.zotero.child_include_re</code></li> <li><code>KERKOAPP_COLLECTION_FACETS</code> \u2192 <code>kerko.facets.*</code>. See sub-parameters <code>type</code>   (set it to <code>\"collection\"</code>), <code>collection_key</code>, <code>weight</code>, and <code>title</code>.</li> <li><code>KERKOAPP_EXCLUDE_DEFAULT_BADGES</code>: Remove. There is no replacement since   Kerko does not provide any default badges at this point.</li> <li><code>KERKOAPP_EXCLUDE_DEFAULT_CITATION_FORMATS</code> \u2192 <code>kerko.citation_formats.*</code>.   See sub-parameter <code>enable</code>.</li> <li><code>KERKOAPP_EXCLUDE_DEFAULT_FACETS</code> \u2192 <code>kerko.facets.*</code>. See sub-parameter   <code>enable</code>.</li> <li><code>KERKOAPP_EXCLUDE_DEFAULT_FIELDS</code> \u2192 <code>kerko.search_fields.*</code>. See   sub-parameter <code>enable</code>.</li> <li><code>KERKOAPP_EXCLUDE_DEFAULT_SCOPES</code> \u2192 <code>kerko.scopes.*</code>. See sub-parameter   <code>enable</code>.</li> <li><code>KERKOAPP_EXCLUDE_DEFAULT_SORTS</code> \u2192 <code>kerko.sorts.*</code>. See sub-parameter   <code>enable</code>.</li> <li><code>KERKOAPP_FACET_INITIAL_LIMIT_LEEWAY</code> \u2192   <code>kerko.facets.*.initial_limit_leeway</code>. This is now set individually for   each facet, and there is no longer a global parameter.</li> <li><code>KERKOAPP_FACET_INITIAL_LIMIT</code> \u2192 <code>kerko.facets.*.initial_limit</code>. This is   now set individually for each facet, and there is no longer a global   parameter.</li> <li><code>KERKOAPP_ITEM_EXCLUDE_RE</code> \u2192 <code>kerko.zotero.item_exclude_re</code></li> <li><code>KERKOAPP_ITEM_INCLUDE_RE</code> \u2192 <code>kerko.zotero.item_include_re</code></li> <li><code>KERKOAPP_MIME_TYPES</code> \u2192 <code>kerko.zotero.attachment_mime_types</code></li> <li><code>KERKOAPP_TAG_EXCLUDE_RE</code> \u2192 <code>kerko.zotero.tag_exclude_re</code></li> <li><code>KERKOAPP_TAG_INCLUDE_RE</code> \u2192 <code>kerko.zotero.tag_include_re</code></li> <li><code>PROXY_FIX</code> \u2192 <code>kerkoapp.proxy_fix.*</code></li> </ul> </li> <li>If you are using a translated version of Kerko, the default \"Bibliography\"   link of the navigation bar no longer gets translated because it is now defined   by a configuration parameter. To replace it, set the   <code>kerko.link_groups.navbar</code> parameter (see the parameters   documentation for details).</li> <li>If your configuration changes neither the <code>DATA_PATH</code> nor the <code>INSTANCE_PATH</code>   parameters, then rename KerkoApp's <code>data</code> directory to <code>instance</code>.</li> <li>Make sure your WSGI server now references the application as <code>wsgi.app</code> (or   <code>wsgi:app</code>) instead of <code>kerkoapp.app</code> (or <code>kerkoapp:app</code>).</li> <li> <p>Rebuild your search index using the following commands:</p> <pre><code>flask kerko clean index\nflask kerko sync index\n</code></pre> </li> <li> <p>Restart the application.</p> </li> </ul>"},{"location":"upgrading/#custom-templates","title":"Custom templates","text":"<p>Occurrences of parameter names in custom templates will need to be edited. For example:</p> <ul> <li><code>config.KERKO_COMPOSER</code> \u2192 <code>config.kerko_composer</code></li> <li><code>config.KERKO_TITLE</code> \u2192 <code>config.kerko.meta.title</code></li> <li>... for the full list, please refer to the above section.</li> </ul> <p>The following item fields have been renamed. Occurrences of these in your templates will need to be edited:</p> <ul> <li><code>z_dateAdded</code> \u2192 <code>date_added</code></li> <li><code>z_dateModified</code> \u2192 <code>date_modified</code></li> </ul> <p>The following views have been renamed. Occurrences of these in your templates (perhaps in calls to <code>url_for</code>) will need to be edited:</p> <ul> <li><code>item_citation_download</code> \u2192 <code>item_bib_download</code></li> <li><code>search_citation_download</code> \u2192 <code>search_bib_download</code></li> </ul>"},{"location":"upgrading/#custom-applications_1","title":"Custom applications","text":"<p>Configuration initialization and loading has greatly changed. If you have a custom application, it will need to be adapted even if you do not plan to use TOML files. See Creating a custom application for a working example, and refer to the changelog for other breaking changes.</p>"}]}
\ No newline at end of file
diff --git a/development/sitemap.xml.gz b/development/sitemap.xml.gz
index d7a42a5b02b27ba675c8ec645ac2617d99ac869f..0ebf654eb77e9e69ebb75357426c8571b01f728c 100644
GIT binary patch
delta 13
Ucmb=gXP58h;9%IfX(D?C02}ZGI{*Lx

delta 13
Ucmb=gXP58h;9w|TJCVHt02+P+@Bjb+