Kerko

Name	Kerko JSON
Version	1.1.0 JSON
	download
home_page	https://whiskyechobravo.github.io/kerko/
Summary	A Flask blueprint that provides a faceted search interface for bibliographies based on Zotero.
upload_time	2023-12-23 18:56:15
maintainer
docs_url	None
author	David Lesieur
requires_python	>=3.8
license
keywords	academia bibliography bibliographies flask search zotero
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            [![License](https://img.shields.io/pypi/l/kerko)][Kerko]
[![Version](https://img.shields.io/pypi/v/kerko?color=informational)][Kerko_pypi]
[![Tests status](https://github.com/whiskyechobravo/kerko/workflows/tests/badge.svg)][Kerko_actions]


# Kerko

[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.

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.


## Demo site

A [KerkoApp]-based [demo site][KerkoApp_demo] is available for you to try. You
may also view the [Zotero library][Zotero_demo] that contains the source data
for the demo site.


## Powered by Kerko

The following sites are powered by Kerko:

- [Bibliographie francophone sur l'archivistique](https://bibliopiaf.ebsi.umontreal.ca/)
- [Community Knowledge Open Library on English-Speaking Quebec](https://ckol.quescren.ca/)
- [Lipedema Foundation LEGATO Lipedema Library](https://library.lipedema.org/)
- [Open Development & Education Evidence Library](https://docs.opendeved.net/)
- [The EdTech Hub Evidence Library](http://docs.edtechhub.org/)
- [University of Saint Joseph Research Output](https://research.usj.edu.mo/)


## Features

The main features provided by Kerko are:

- **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.
- **Keyword search** features:
    - Boolean operators:
        - `AND`: matches items that contain all specified terms. This is the default
        relation between terms when no operator is specified, e.g., `a b` is the
        same as `a AND b`.
        - `OR`: matches items that contain any of the specified terms, e.g., `a OR
        b`.
        - `NOT`: excludes items that match the term, e.g., `NOT a`.
        - Boolean operators must be specified in uppercase and may be translated in
        other languages.
    - Logical grouping (with parentheses), e.g., `(a OR b) AND c`.
    - Sequence of words (with double quotes), e.g., `"a b c"`. 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. `"web search"~2` allows up
        to 1 word between `web` and `search`, meaning it could match `web site
        search` as well as `web search`.
    - Term boosting (with the caret), e.g., `faceted^2 search browsing^0.5`
        specifies that `faceted` is twice as important as `search` when computing
        the relevance score of results, while `browsing` is half as important.
        Boosting may be applied to a logical grouping, e.g., `(a b)^3 c`.
    - 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 `search`, `searches`,
        and `searching` all return the same results. The [Snowball] algorithm is
        used for that purpose.
    - Full-text search: the text content of PDF attachments can be searched.
    - Scope of search: users may choose to search everywhere, in
        author/contributor names, in titles, 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.
- **Faceted browsing**: allows filtering by topic (Zotero tag), by resource type
  (Zotero item type), by publication year. 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.
- **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.
- **Sort options**: by relevance score (only applicable to keyword search), by
  publication date, by author, by title.
- **Citation styles**: any from the [Zotero Style Repository][Zotero_styles], or
  custom stylesheet defined in the [Citation Style Language][CSL] (stylesheet
  must be accessible by URL).
- **Language support**: the default language of the user interface is English,
  but [some translations][Kerko_translations] are provided. Additional
  translations may be created using gettext-compatible tools. Also to consider:
  locales supported by the [Zotero Data Schema][Zotero_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.
- **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:
    - [OpenURL COinS][COinS], in search results pages and individual
      bibliographic record pages. COinS is recognized by [many reference
      management tools][COinS_clients], including the [Zotero
      Connector][Zotero_Connector] browser extension.
    - 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][HighwirePress_Google], and
      are recognized by many other databases and reference management tools,
      including the [Zotero Connector][Zotero_Connector] browser extension.
- **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.
    - The main feed lists the most recently added bibliographic records.
    - 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.
    - Feeds are provided in the [Atom syndication format][Atom].
    - Basic metadata is provided directly in the feeds, using both Atom and
      unqualified [Dublin Core][Dublin_Core] elements.
    - 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).
- **Sitemap**: an [XML Sitemap][XML_Sitemap] is automatically generated, and you
  may use it to help search engines discover your bibliographic records.
- **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][Zotero_export].
- **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).
- **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.
- **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.
- **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. Custom applications can add more types of relations if desired.
- **Pages**: simple informational pages can be defined using content from Zotero
  standalone notes.
- **Badges**: custom applications can have icons conditionally displayed next to
  items.
- **Responsive design**: the simple default implementation works on large
  monitors as well as on small screens. It is based on [Bootstrap].
- **Google Analytics integration**: just provide a Google Analytics stream ID to
  have Kerko automatically include the tracking code into its pages.
- **Integration**: as a Flask [blueprint][Flask_blueprint], Kerko can be
  integrated into any Flask application. For a standalone application, however,
  you may simply install [KerkoApp].
- **Customizable front-end**: applications may partly or fully replace the
  default templates, scripts and stylesheets with their own.
- **Command line interface (CLI)**: Kerko provides commands for synchronizing or
  deleting its data.

[KerkoApp] is a standalone application built around Kerko. It inherits all of
Kerko's features and it provides a few additions of its own:

- **Configuration files**: allow separation of configuration from code and
  enable the [Twelve-factor App][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.
- Page templates for common HTTP errors.
- Syslog logging handler (for Unix environments).


## Learn more

Please refer to the [documentation][Kerko_documentation] for more details.


[Atom]: https://en.wikipedia.org/wiki/Atom_(web_standard)
[BM25F]: https://en.wikipedia.org/wiki/Okapi_BM25
[Bootstrap]: https://getbootstrap.com/
[CSL]: https://citationstyles.org/
[COinS]: https://en.wikipedia.org/wiki/COinS
[COinS_clients]: https://en.wikipedia.org/wiki/COinS#Client_tools
[Dublin_Core]: https://en.wikipedia.org/wiki/Dublin_Core
[Flask]: https://pypi.org/project/Flask/
[Flask_blueprint]: https://flask.palletsprojects.com/en/latest/blueprints/
[Kerko]: https://github.com/whiskyechobravo/kerko
[Kerko_actions]: https://github.com/whiskyechobravo/kerko/actions
[Kerko_documentation]: https://whiskyechobravo.github.io/kerko/
[Kerko_pypi]: https://pypi.org/project/Kerko/
[Kerko_translations]: https://github.com/whiskyechobravo/kerko/tree/main/src/kerko/translations
[KerkoApp]: https://github.com/whiskyechobravo/kerkoapp
[KerkoApp_demo]: https://demo.kerko.whiskyechobravo.com
[Snowball]: https://snowballstem.org/
[TOML]: https://toml.io/
[Twelve-factor_App]: https://12factor.net/config
[Whoosh]: https://pypi.org/project/Whoosh/
[XML_Sitemap]: https://www.sitemaps.org/
[Zotero]: https://www.zotero.org/
[Zotero_Connector]: https://www.zotero.org/download/connectors
[Zotero_demo]: https://www.zotero.org/groups/2348869/kerko_demo/items
[Zotero_export]: https://www.zotero.org/support/dev/web_api/v3/basics#export_formats
[Zotero_schema]: https://api.zotero.org/schema
[Zotero_styles]: https://www.zotero.org/styles/

# Changelog

Before doing an upgrade, please check the "How to upgrade" section of the Kerko
documentation.

## 1.1.0 (2023-12-23)

Features:

- Add the "Publication year" search scope. It is enabled by default, but can be
  disabled by setting the `kerko.scopes.pubyear.enabled` configuration parameter
  to `false`.
- Add new configuration parameter `kerko.pages.*.` for defining content pages
  whose content come from selected Zotero standalone notes.
- Add a `"page"` type for the `kerko.link_groups.*.` configuration table, to
  allow the creation of links to content pages.
- Add configuration parameters `kerko.performance.whoosh_index_memory_limit` and
  `kerko.performance.whoosh_index_processors` to give some control over the
  Whoosh search engine's indexing performance.
- Allow italic, bold, subscript, superscript and small-caps on Zotero fields
  (such as titles and abstracts) where [rich text formatting
  tags](https://www.zotero.org/support/kb/rich_text_bibliography) are used.
- Add Spanish translation. Thanks to [Albert
  Ormazabal](https://github.com/aormazabal).

Bug fixes:

- Fix item title missing from item pages and from Atom feeds when item type is
  Case, Email, or Statute.
- Fix incorrect sorting of search results by title when item type is Case,
  Email, or Statute.
- Fix incorrect escaping of HTML markup in the HTML content elements of Atom
  feeds.
- Fix incorrect scope, analyzer, and boost factor associated with the `caseName`
  search field.
- Fix crash when a facet specifies no sort order.
- Fix crash on empty search result pages when configuration parameter
  `kerko.features.print_results_max_count` is greater than zero.
- Fix badges displayed too close to title on item pages.

Other changes:

- Add `rel="noopener"` to `target="_blank"` links.
- Add `rel="noreferrer"` to links derived from Zotero library data, e.g.,
  user-provided URLs, DOIs, link attachments.
- 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
  `kerko.performance.whoosh_index_memory_limit` parameter.
- Improve speed of single-item search pages, i.e., search pages having the
  `page-len=1` URL parameter. This is achieved through removal of the `id`
  parameter from pagination URLs. Obtaining those ids was requiring extra
  processing. Instead, the `id` parameter is now added through the browser
  History API when a pagination link is visited.
- Add support for Python 3.12.
- Replace pylint, pycodestyle, pydocstyle with Ruff.
- Replace Yapf with Ruff formatter. Reformat whole code base.
- Add pre-commit hooks. Run Ruff and other code checks on pre-commit.
- Add template blocks to facilitate theming.
- Improve documentation.

Backwards incompatible changes:

- Drop support for Python 3.7 (EOL).

Possibly backwards incompatible changes (more or less internal API changes):

- Kerko no longer provides a `kerko.blueprint` global object. Applications must
  now instantiate the blueprint by calling `kerko.make_blueprint()` before
  registering it. This prevents attempts to mutate the object after its
  registration, especially in tests.
- Upgrade many dependencies, including new major versions of Flask (3.x),
  Flask-Babel (4.x), Werkzeug (3.x).
- `kerko.extractors.TransformerExtractor` no longer applies transformers on
  `None` values. If you need a transformer to process a `None` value (Kerko
  itself has no such transformer), you now have to set the new `skip_none_value`
  argument to `False` when instantiating the extractor.


## 1.0.0 (2023-07-24)

Features:

- Add new configuration parameter `kerko.features.download_item`.

Bug fixes:

- Fix Gunicorn not exiting if the default TOML config has errors (use the
  `errno.EINTR` error code). Not an issue anyone should have encountered!

Backwards incompatible changes:

- Rename the following configuration parameters:
    - `kerko.features.download_results_link` → `kerko.features.download_results`.
    - `kerko.features.print_item_link` → `kerko.features.print_item`
    - `kerko.features.print_results_link` → `kerko.features.print_results`

Other changes:

- Improve documentation.


## 1.0.0alpha2 (2023-07-12)

Features:

- Add new configuration parameters `kerko.link_groups.*.` for defining sets of
  links that may be used for navigation.
- Add a breadcrumb trail to all pages. One or more base links can be configured
  (see configuration parameters `kerko.breadcrumb` and
  `kerko.link_groups.breadcrumb_base`).

Bug fixes:

- Fix validation pattern too restrictive for the `kerko.zotero.csl_style`
  configuration parameter.

Backwards incompatible changes:

- Items from the main navigation bar are now based on the
  `kerko.link_groups.navbar` configuration. There is no default translation for
  it. To change the default text or to translate it, you must override the
  default `kerko.link_groups.navbar` in your configuration file. If you have
  overridden the `_navbar_items.html.jinja2` template and wish to use the
  configuration, you might want to adapt it, or revert to the default template.

Other changes:

- Improve documentation.


## 1.0.0alpha1 (2023-06-29)

Features:

- Add the `--full` option to the `sync` command line interface (CLI) command.

Bug fixes:

- Fix validation pattern too restrictive for the `kerko.facets.*.collection_key`
  configuration parameter.
- Fix incorrect typing for the `kerko.features.download_results_max_count` and
  `kerko.features.print_results_max_count` configuration parameters.

Other changes:

- 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:

    ```bash
    git branch -m master main
    git fetch origin
    git branch -u origin/main main
    git remote set-head origin -a
    ```

- Make the `config` CLI command show the configuration in TOML format.
- Make the `config` CLI command hide secrets by default. Add a `--show-secrets`
  option.
- Improve documentation.

Backwards incompatible changes:

- Prevent the `clean` CLI command from cleaning everything by default. To delete
  everything, you now have to run `flask kerko clean everything`. This may help
  prevent accidental deletion of the cache, which in some instances can take
  long to rebuild.
- Rename the following configuration parameters:
    - `kerko.citation_formats.*` → `kerko.bib_formats.*`.
    - `kerko.features.download_citations_link` → `kerko.features.download_results_link`
    - `kerko.features.download_citations_max_count` → `kerko.features.download_results_max_count`
    - `kerko.features.print_citations_link` → `kerko.features.print_results_link`
    - `kerko.features.print_citations_max_count` → `kerko.features.print_results_max_count`
- Rename the following views:
    - `item_citation_download` → `item_bib_download`
    - `search_citation_download` → `search_bib_download`


## 1.0.0alpha0 (2023-06-26)

*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][KerkoApp_changelog].

```bash
flask kerko clean index
flask kerko sync index
```

Features:

- Add many new configuration parameters. Please refer to the configuration
  parameters documentation for the full list.
- Add optional "Open in Zotero" and "View on zotero.org" buttons to item pages.
  These are disabled by default (see new parameters
  `kerko.features.open_in_zotero_app` and `kerko.features.open_in_zotero_web`).
  Even when these are enabled, a user who wishes to use such button must first
  enable it from the (also new) Preferences dialog.
- Add a web API endpoint for retrieving information about the last
  synchronization from Zotero.
- Add the `kerko config` command to the Flask command line interface for
  displaying all configuration parameters.

Other changes:

- Restructure and expand documentation into a unified documentation site for
  both Kerko and KerkoApp.
- Add Portuguese translation. Thanks to Gonçalo Cordeiro.

Backwards incompatible changes:

- 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.
- The data directory has a new default location relative to the instance path.
  Please check the documentation for the `DATA_PATH` and `INSTANCE_PATH`
  configuration parameters. You may need to set one or both of those parameters,
  and/or move your existing data directory.
- 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
  `kerko.config_helpers.config_set()` function. Here is a mapping of the changed
  parameters:
    - `KERKO_BOOTSTRAP_VERSION` → `kerko.assets.bootstrap_version`
    - `KERKO_CSL_STYLE` → `kerko.zotero.csl_style`
    - `KERKO_COMPOSER` → `kerko_composer`
    - `KERKO_DATA_DIR` → `DATA_PATH`. Now optional, relative to the instance
      path, and defaulting to `kerko` instead of `data/kerko`.
    - `KERKO_DOWNLOAD_ATTACHMENT_NEW_WINDOW` → `kerko.features.download_attachment_new_window`
    - `KERKO_DOWNLOAD_CITATIONS_LINK` → `kerko.features.download_citations_link`
    - `KERKO_DOWNLOAD_CITATIONS_MAX_COUNT` → `kerko.features.download_citations_max_count`
    - `KERKO_FEEDS` → `kerko.feeds.formats`
    - `KERKO_FEEDS_FIELDS` → `kerko.feeds.fields`
    - `KERKO_FEEDS_MAX_DAYS` → `kerko.feeds.max_days`
    - `KERKO_FEEDS_REJECT_ANY` → `kerko.feeds.reject_any`
    - `KERKO_FEEDS_REQUIRE_ANY` → `kerko.feeds.require_any`
    - `KERKO_FULLTEXT_SEARCH` → `kerko.search.fulltext`
    - `KERKO_HIGHWIREPRESS_TAGS` → `kerko.meta.highwirepress_tags`
    - `KERKO_JQUERY_VERSION` → `kerko.assets.jquery_version`
    - `KERKO_PAGE_LEN` → `kerko.pagination.page_len`
    - `KERKO_PAGER_LINKS` → `kerko.pagination.pager_links`
    - `KERKO_POPPER_VERSION` → `kerko.assets.popper_version`
    - `KERKO_PRINT_CITATIONS_LINK` → `kerko.features.print_citations_link`
    - `KERKO_PRINT_CITATIONS_MAX_COUNT` → `kerko.features.print_citations_max_count`
    - `KERKO_PRINT_ITEM_LINK` → `kerko.features.print_item_link`
    - `KERKO_RELATIONS_INITIAL_LIMIT` → `kerko.features.relations_initial_limit`
    - `KERKO_RELATIONS_LINKS` → `kerko.features.relations_links`
    - `KERKO_RELATIONS_SORT` → `kerko.features.relations_sort`
    - `KERKO_RESULTS_ABSTRACTS_MAX_LENGTH` → `kerko.features.results_abstracts_max_length`
    - `KERKO_RESULTS_ABSTRACTS_MAX_LENGTH_LEEWAY` → `kerko.features.results_abstracts_max_length_leeway`
    - `KERKO_RESULTS_ABSTRACTS` → `kerko.features.results_abstracts`
    - `KERKO_RESULTS_ABSTRACTS_TOGGLER` → `kerko.features.results_abstracts_toggler`
    - `KERKO_RESULTS_ATTACHMENT_LINKS` → `kerko.features.results_attachment_links`
    - `KERKO_RESULTS_FIELDS` → `kerko.search.result_fields`
    - `KERKO_RESULTS_URL_LINKS` → `kerko.features.results_url_links`
    - `KERKO_TEMPLATE_ATOM_FEED` → `kerko.templates.atom_feed`
    - `KERKO_TEMPLATE_BASE` → `kerko.templates.base`
    - `KERKO_TEMPLATE_ITEM` → `kerko.templates.item`
    - `KERKO_TEMPLATE_LAYOUT` → `kerko.templates.layout`
    - `KERKO_TEMPLATE_SEARCH` → `kerko.templates.search`
    - `KERKO_TEMPLATE_SEARCH_ITEM` → `kerko.templates.search_item`
    - `KERKO_TITLE` → `kerko.meta.title`
    - `KERKO_WHOOSH_LANGUAGE` → `kerko.search.whoosh_language`
    - `KERKO_WITH_JQUERY` → `kerko.assets.with_jquery`
    - `KERKO_WITH_POPPER` → `kerko.assets.with_popper`
    - `KERKO_ZOTERO_API_KEY` → `ZOTERO_API_KEY`
    - `KERKO_ZOTERO_BATCH_SIZE` → `kerko.zotero.batch_size`
    - `KERKO_ZOTERO_LIBRARY_ID` → `ZOTERO_LIBRARY_ID`
    - `KERKO_ZOTERO_LIBRARY_TYPE` → `ZOTERO_LIBRARY_TYPE`
    - `KERKO_ZOTERO_LOCALE` → `kerko.zotero.locale`
    - `KERKO_ZOTERO_MAX_ATTEMPTS` → `kerko.zotero.max_attempts`
    - `KERKO_ZOTERO_WAIT` → `kerko.zotero.wait`
- The Kerko configuration should now be initialized by a call like
  `kerko.config_helpers.config_update(app.config, kerko.DEFAULTS)`.
- `Composer.__init__()` now only takes a configuration object as argument
  instead of a bunch of arguments. Thus, the initial values of the `Composer`
  instance now depend solely on the configuration.
- Remove the `KERKO_USE_TRANSLATIONS` 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
  `kerko.TRANSLATION_DOMAIN` and `kerko.TRANSLATION_DIRECTORIES` to their Babel
  configuration.
- The `__init__()` method of `FacetSpec` and its subclasses now only accept
  keyword arguments.
- The `sort_key` argument to `FacetSpec.__init__()` is now `sort_by`.
- `Composer` built-in fields `z_dateAdded` and `z_dateModified` are now named
  `date_added` and `date_modified` respectively.


## 0.9 (2022-12-29)

*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:

```bash
flask kerko clean index
flask kerko sync index
```

Features:

- Add expand/collapse actions on facet values, allowing full exploration of
  hierarchical facets without changing the current search.
- 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.
- Add Atom syndication feeds.
- Allow searching items by their Zotero key.
- Add XML sitemap.
- Add the `kerko count` CLI command (mostly meant for development purposes).

Bug fixes:

- Fix last sync time not displayed at the bottom of search results when
  `KERKO_PRINT_CITATIONS_LINK` and `KERKO_DOWNLOAD_CITATIONS_LINK` are both set
  to `False`.
- Fix the `kerko sync` CLI command not returning an error code with some types
  of failures.
- Fix invalid HTML in help modal.

Other changes:

- Handle new Zotero fields introduced with the new 'preprint' item type.
- 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).
- Under each facet, always show the facet's active filters first.
- Make facet values with long labels easier to read (by indenting wrapped lines
  to the right of the checkbox).
- Add link to full bibliography from item pages.
- Add blocks in templates to facilitate theming.
- Remove `page` parameter from pagination links when `page=1`.
- Improve documentation.
- Make sync and schema-related error messages more helpful and user-friendly.
- Move pydocstyle config to `pyproject.toml`.
- Tag package as compatible with Python 3.10 and 3.11.
- Remove leftover code related to Python versions older than 3.7

Backwards incompatible changes:

- Remove the `KERKO_FACET_COLLAPSING` option. The new initial limit on facets
  values made this feature largely redundant.
- Remove the `collapsible` param from the `FacetSpec` class.
- Remove support for configuration variables `KERKO_ZOTERO_START` and
  `KERKO_ZOTERO_END` (were only used for development and no longer practical).

Changes that might break custom themes:

- The HTML markup and CSS styles of expand/collapse buttons have changed.
- The parameters of the `facet`, `facet_item`, `facet_items`, `facet_fields`
  template macros have changed.
- The `facets-container`, `facets`, and `facets-modal-body` element ids are now
  required in `search.html.jinja2`.

Possibly backwards incompatible changes (more or less internal API changes):

- Rewrote the `criteria` module. `Criteria.keywords` and `Criteria.filters` work
  pretty much as before, but everything else has changed.
- Rewrote the `query` module, which had organically grown into an tangled mess,
  now replaced with the `searcher` module. This new API is completely different.
- Adapted view code to the above-mentioned `searcher` API.
- Split the monolithic `views` module into multiple modules under `views`
  (`item_creators`, `item_facets`, `item_relations`, `routes`, `search`), and
  moved `breadbox`, `meta` (as `item_meta`), `pager`, and `sorter` under
  `views`.


## 0.8.1 (2021-11-16)

Bug fixes:

- Fix missing dependency for package building.


## 0.8 (2021-11-16)

*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:

```bash
flask kerko clean index
flask kerko sync
```

Features:

- Allow full-text search of PDF attachments. This can be disabled by setting
  `KERKO_FULLTEXT_SEARCH` to `False`. Since this feature relies on Zotero's
  full-text indexing, you must make sure that it works in Zotero first; see
  [Zotero's
  documentation](https://www.zotero.org/support/searching#pdf_full-text_indexing).
- 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.
- Display "View on {hostname}" links under search result items, for quick access
  to the items' URLs. These can be disabled by setting `KERKO_RESULTS_URL_LINKS`
  to `False`.
- Move the "Read" buttons under search result items, as "Read document" links.
  These can now be disabled by setting `KERKO_RESULTS_ATTACHMENT_LINKS` to
  `False`.
- Display DOI field values as hyperlinks (both in DOI fields, and in the Extra
  field when lines are prefixed with 'DOI:').
- 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.
- 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, `standalone_attachment_download`, lets one retrieve a
  standalone file attachment.
- Add configuration options for truncating long abstracts in search results
  (`KERKO_RESULTS_ABSTRACTS_MAX_LENGTH` and
  `KERKO_RESULTS_ABSTRACTS_MAX_LENGTH_LEEWAY`).
- Embed Highwire Press tags in item pages. This is enabled by default but can be
  disabled by setting `KERKO_HIGHWIREPRESS_TAGS` to `False`.
- Allow tracking with Google Analytics (optional).
- Allow relations in child notes to be specified as HTML links, i.e., in the
  `href` attribute of `<a>` elements.
- Allow inclusion or exclusion of items based on multiple tags (previously, only
  a single pattern could be checked).

Bug fixes:

- Fix irrelevant sync warnings, from extractors running on attachment items.
- Fix empty prev/next links in search pages metadata.

Other changes:

- 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.
- Add a `sync cache` command to the command line interface.
- On narrow screens, stack search form controls for better usability.
- Respond with an HTTP 503 (Service Unavailable) when the search index is empty
  or unreadable.
- Make sorts more efficient by setting the `sortable` Whoosh flag on relevant
  fields.
- Leading and trailing underscore characters (`_`) 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.
- 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.
- Change labels:
    - "Print this citation" → "Print this record" (on item pages)
    - "Download this citation" → "Download this record" (on item & search pages)
- Inject blocks in item Jinja2 template to facilitate theming.
- Slightly increase some top/bottom margins.
- Add the `type` HTML attribute to record download links.
- Add the `rel="alternate"` HTML attribute to record download links on item
  pages. Also add a corresponding `link` element to the page `head`.
- Added utilities for running automated integration tests. This will allow
  testing many areas of Kerko that previously could hardly be tested.

Backwards incompatible changes:

- Remove deprecated `kerko index` CLI command (use `kerko sync` instead).

Possibly backwards incompatible changes (more or less internal API changes):

- Upgrade many dependencies, including new major versions of Flask (2.x), Jinja2
  (3.x), Werkzeug (2.x), Click (8.x).
- The default list for the `KERKO_RESULTS_FIELDS` setting now includes the
  `'url'` field. If you have overridden that setting in your application and
  `KERKO_RESULTS_URL_LINKS` is enabled, you'll probably have to add `'url'` too.
- The schema field `item_type` has been renamed to `item_type_label`. If you
  have custom templates, please review any use of `item.item_type`.
- The structure of the `kerko/_search-result.html.jinja2` template has changed
  somewhat. If you have overridden it, you'll need to review the changes.
- The `ItemContext` class has been eliminated. The `Extractor.extract()` method
  now receives an item's dictionary instead of an `ItemContext` object, and if
  an item has children these are now available directly in the item (with the
  `children` key). If you have created custom extractor classes, their
  `extract()` method will need to be adapted accordingly.
- Some extractor classes have been renamed:
    - `BaseAttachmentsExtractor` → `BaseChildAttachmentsExtractor`
    - `BaseNotesExtractor` → `BaseChildNotesExtractor`
    - `LinkedURIAttachmentsExtractor` → `ChildLinkedURIAttachmentsExtractor`
    - `NotesTextExtractor` → `ChildNotesTextExtractor`
    - `RawNotesExtractor` → `RawChildNotesExtractor`
    - `RelationsInNotesExtractor` → `RelationsInChildNotesExtractor`
    - `StoredFileAttachmentsExtractor` → `ChildFileAttachmentsExtractor`
- A view has been renamed:
    - `item_attachment_download` → `child_attachment_download`
- A default field has been renamed:
    - `alternateId` → `alternate_id`

## 0.7.1 (2021-02-04)

Security fixes:

- Fix unescaped date fields, causing a vulnerability to XSS attacks. This
  vulnerability was introduced in version 0.7.

Bug fixes:

- Fix wrong locale separator in the HTML lang attribute.

Other changes:

- Remove unwanted spacing after dropdown labels.

Documentation changes:

- Fix missing info about library groupID in configuration docs. Thanks
  [@drmikeuk](https://github.com/drmikeuk) for reporting the issue.

## 0.7 (2021-01-08)

*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:

```bash
flask kerko clean index
flask kerko sync
```

Features:

- Allow users to toggle the display of abstracts on search results pages.
- Allow inclusion or exclusion of items based on their tags
  ([#4](https://github.com/whiskyechobravo/kerko/issues/4)).
- Show attached links to URIs on item pages.
- Show relations on item pages. The relation types provided by default are:
  - _Related_, based on Zotero's _Related_ field.
  - _Cites_, managed through child notes containing Zotero URIs and tagged with
    the `_cites` tag.
  - _Cited by_, automatically inferred from _Cites_ relations.
- The Extra field is now searched when searching "in any fields".
- Items that have a DOI, ISBN or ISSN identifier can be referenced by appending
  their identifier to your Kerko site's base URL.
- 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
  `dc.replaces` relation that's managed internally by Zotero on some operations
  such as item merges.
- Help users who might mistakenly bookmark a search result's URL rather than the
  item's permanent URL: Add an `id` 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.
- Redirect to the parent item's page when the user tries to request an
  attachment that no longer exists.
- Improve accessibility based on WCAG recommendations and WAI-ARIA standards:
  - Add labels to search form elements.
  - Add landmark role `search` to the search form.
  - Make the purpose of various links more obvious through improved or added
    labels.
  - Add the `aria-label` attribute to many elements.
  - Add text to indicate the current value of widgets.
  - Add the `aria-current` attribute to indicate the current value of widgets.
  - Remove useless link to the current page from the pagination widget.

Bug fixes:

- Fix crash when trying to sync a link attachment
  ([#3](https://github.com/whiskyechobravo/kerko/issues/3)).
- Fix unhandled exception during sync when an attachment cannot be downloaded.
- Fix page numbers greater than the page count in search URLs generating wrong
  page numbers for search result item URLs.
- 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.
- Fix empty HTML element taking up horizontal space when there are no badges.

Other changes:

- Display ISO 8601 calendar dates in a more readable format, using the
  formatting style of the locale.
- Show a timezone abbreviation along with time of last update from Zotero.
- Add German translation. Thanks to [@mmoole](https://github.com/mmoole).
- Fix broken "Getting started" example in README.
- Migrate most package distribution options and metadata from `setup.py` to
  `setup.cfg`.
- Migrate project to a `src` layout.
- Use Flask-Babel instead of its fork Flask-BabelEx, now that is has merged the
  translation domain features from Flask-BabelEx.

Backwards incompatible changes:

- 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.
- All values of the `pager` dict passed to the `_pager.html.jinja2` template are
  now lists. Previously, only the values at keys `'before'` and `'after'` were
  lists; now the values at keys `'previous'`, `'first'`, `'current'`, `'last'`,
  and `'next'` are lists as well.
- The words `'blacklist'` and `'whitelist'` in variable names are replaced with
  `'exclude'` and `'include'`.
- The `KERKO_RESULTS_ABSTRACT` configuration variable is replaced by two
  variables, `KERKO_RESULTS_ABSTRACTS` (note the now plural form) and
  `KERKO_RESULTS_ABSTRACTS_TOGGLER`.
- Citation download URLs now have the form
  `{url_prefix}/{itemID}/export/{format}` for individual items (`'export'` has
  been inserted), and `{url_prefix}/export/{format}/` for search result pages
  (`'download'` has been replaced by `'export'`).
- The `Extractor` class' interface has changed, improving consistency and
  separation of concerns:
  - All arguments to `__init__()` must now be specified as keyword arguments.
  - The `extract()` method no longer have a `document` argument, and the `spec`
    argument is now the last one. The method now returns a value instead of
    assigning it to the document.
  - The new `extract_and_store()` method handles extraction, encoding, and
    assignment to the document, assigning the value only when it is not `None`.
- The `AttachmentsExtractor` class has been renamed to
  `StoredFileAttachmentsExtractor`.
- `InCollectionExtractor` now extends collection membership to subcollections.
  To preserve the previous behavior, set the `check_subcollections` parameter to
  `False` when initializing the extractor.

Possibly backwards incompatible changes (more or less internal API changes):

- The `search_results` variable passed to the `search.html.jinja2` 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.

## 0.6 (2020-06-15)

Security fixes:

- Fix multiple vulnerabilities to XSS attacks. **All previous versions of Kerko
  were vulnerable, thus an upgrade is highly recommended.**

Backwards incompatible changes:

- Remove default value for the `KERKO_DATA_DIR` 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.

Features:

- Open PDF documents in the browser's built-in PDF viewer (instead of opening
  the browser's file download popup).
- Add buttons for opening documents directly from search result pages (these
  replace the previous paperclip badges).
- Add button at the top of item pages for opening documents (makes the
  availability of such documents much more obvious).
- Add the `KERKO_DOWNLOAD_ATTACHMENT_NEW_WINDOW` configuration variable to
  control whether to open documents in a new window or in the same window.
- Display the date and time of the last successful synchronization from Zotero
  at the bottom of search results.

Bug fixes:

- Preserve newlines when displaying the value of the Extra field.
- Preserve newlines when displaying abstracts in search result pages.
- Fix filters missing on search pages that have no results.
- Avoid empty box in print media when there is no search criteria.
- Avoid empty box when the search index is missing.
- Fix pluralization in CLI time elapsed messages.

Other changes:

- Refer to attachments as "documents" in the interface, and replace the
  paperclip icon with a file icon.
- 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.
- Add a proper message when none of the filters provided in the URL are
  recognized.
- Improve documentation.
- Add INFO-level log message to report successful synchronization from Zotero.
- Add blocks in templates to facilitate theming.

Possibly backwards incompatible changes (more or less internal API changes):

- Rename the `content_with_badges` template macro as `badges`, and leave it to
  the caller to display content.
- Remove badges that are related to attachments.

## 0.5 (2019-11-19)

*Warning:* Upgrading from version 0.4 or earlier will require that you clean and
re-sync your existing search index. Use the following commands:

```bash
flask kerko clean index
flask kerko sync
```

Features:

- Add support for Zotero attachments.
- Allow configuration of badges on items. The 'attachment' badge is provided by
  default, displaying an icon on items that have one or more attachments.
- Add help modal.
- Improve customizability:
  - Add `KERKO_TEMPLATE_*` configuration variables for page template names.
  - Use configurable, separate templates to render facets and badges (see the
    `renderer` argument to `kerko.specs.FacetSpec`, `kerko.specs.BadgeSpec`).
  - Add the `KERKO_RESULTS_FIELDS` configuration variable to specify which
    fields to retrieve with search queries.
- Add building blocks for creating boolean facets based on collection membership
  (new class `kerko.extractors.InCollectionExtractor`, new parameters for
  `kerko.codecs.BooleanFacetCodec`).

Bug fixes:

- Fix facets not ordered by weight on item page.
- Preserve newlines in abstract display.
- Fix incorrect use of bookmark link on item pages, set canonical link instead.
- Prevent text overflow in some browsers on citations containing long URLs.

Other changes:

- Deprecate CLI command `kerko index` in favor of new command `kerko sync`.
- Change title of the "Refine" panel to "Explore".
- Change labels of the "Print" and "Download" buttons to "Print this citation"
  and "Download this citation", to prevent any confusion with attachment
  downloading.
- Show the facets in a more robust and accessible Bootstrap modal, on small
  screens, instead of the home-built drawer.
- Use compact pagination widget on small screens.
- Tweak sizing, positioning, and spacing of various UI elements.
- Improve accessibility of various UI elements.
- Make citation stand out more in item page.
- Hide some elements and decorations in print media.
- Make search query more efficient on item page.

Possibly backwards incompatible changes (more or less internal API changes):

- Force keyword arguments with `kerko.composer.Composer.__init__()`.
- Rename `kerko.composer.Composer.__init__()` arguments
  `default_note_whitelist_re` as `default_child_whitelist_re`,
  `default_note_blacklist_re` as `default_child_blacklist_re`.
- Rename method `kerko.views.item()` as `kerko.views.item_view()`.
- Rename template file `_facet.html.jinja2` as `_facets.html.jinja2`.
- Replace argument `checkboxes` in template macro `field()` with `add_link_icon`
  and `remove_link_icon`.

## 0.4 (2019-09-28)

Features:

- Allow search term boosting in relevance score calculation, e.g. `faceted^2
  search browsing^0.5`.

Security fixes:

- Update minimum Werkzeug version to 0.15.3. See
  [CVE-2019-14806](https://nvd.nist.gov/vuln/detail/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."

Other changes:

- Update jQuery version to 3.4.1.
- Update French translations (translate boolean search operators).
- Improve search form validation and error display.
- Disable not-so-intuitive boolean search operators (`AndNot`, `AndMaybe`,
  `Require` were unwanted but enabled by default by Whoosh's `OperatorsPlugin`).
- Improve documentation.
- Code cleanup.

## 0.3 (2019-07-29)

Features:

- 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.

Bug fixes:

- Fix bad alignment of field names in print mode.
- Remove warning when indexing an item with no authors
  ([#1](https://github.com/whiskyechobravo/kerko/issues/1)).

Other changes:

- Move print button to bottom of search pages (next to the new download
  dropdown).
- Improve documentation.
- Compile message catalog before building sdist and wheel.

Possibly backwards incompatible changes (more or less internal API changes):

- Method `kerko.composer.Composer.get_ordered_specs()` replaces
  `get_ordered_scopes()`, `get_ordered_facets()` and `get_ordered_sorts()`.

## 0.3alpha1 (2019-07-17)

- Fix broken links in documentation.

## 0.3alpha0 (2019-07-16)

- First PyPI release.


[KerkoApp_changelog]: https://github.com/whiskyechobravo/kerkoapp/blob/main/CHANGELOG.md

            

Raw data

            {
    "_id": null,
    "home_page": "https://whiskyechobravo.github.io/kerko/",
    "name": "Kerko",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.8",
    "maintainer_email": "",
    "keywords": "academia,bibliography,bibliographies,flask,search,zotero",
    "author": "David Lesieur",
    "author_email": "kerko@whiskyechobravo.com",
    "download_url": "https://files.pythonhosted.org/packages/c9/a0/a8b7591430f6af1cdc4da4d570a0b20163b828a9e7e063c0e58217ccc5cf/Kerko-1.1.0.tar.gz",
    "platform": null,
    "description": "[![License](https://img.shields.io/pypi/l/kerko)][Kerko]\n[![Version](https://img.shields.io/pypi/v/kerko?color=informational)][Kerko_pypi]\n[![Tests status](https://github.com/whiskyechobravo/kerko/workflows/tests/badge.svg)][Kerko_actions]\n\n\n# Kerko\n\n[Kerko] is a web application component that provides a user-friendly search and\nbrowsing interface for sharing a bibliography managed with the [Zotero]\nreference manager.\n\nThe combination of Kerko and Zotero gives you the best of both worlds: a rich\nbut easy to use web interface for end-users of the bibliography, and a\nwell-established and powerful bibliographic reference management tool for\nindividuals or teams working on the bibliography's content.\n\n\n## Demo site\n\nA [KerkoApp]-based [demo site][KerkoApp_demo] is available for you to try. You\nmay also view the [Zotero library][Zotero_demo] that contains the source data\nfor the demo site.\n\n\n## Powered by Kerko\n\nThe following sites are powered by Kerko:\n\n- [Bibliographie francophone sur l'archivistique](https://bibliopiaf.ebsi.umontreal.ca/)\n- [Community Knowledge Open Library on English-Speaking Quebec](https://ckol.quescren.ca/)\n- [Lipedema Foundation LEGATO Lipedema Library](https://library.lipedema.org/)\n- [Open Development & Education Evidence Library](https://docs.opendeved.net/)\n- [The EdTech Hub Evidence Library](http://docs.edtechhub.org/)\n- [University of Saint Joseph Research Output](https://research.usj.edu.mo/)\n\n\n## Features\n\nThe main features provided by Kerko are:\n\n- **Faceted search interface**: allows exploration of the bibliography both in\n  search mode and in browsing mode, potentially suiting different user needs,\n  behaviors, and abilities. For example, users with a prior idea of the topic or\n  expected results may enter keywords or a more complex query in a search field,\n  while those who wish to become familiar with the content of the bibliography\n  or discover new topics may choose to navigate along the proposed facets, to\n  narrow or broaden their search. Since both modes are integrated into a single\n  interface, it is possible to combine them.\n- **Keyword search** features:\n    - Boolean operators:\n        - `AND`: matches items that contain all specified terms. This is the default\n        relation between terms when no operator is specified, e.g., `a b` is the\n        same as `a AND b`.\n        - `OR`: matches items that contain any of the specified terms, e.g., `a OR\n        b`.\n        - `NOT`: excludes items that match the term, e.g., `NOT a`.\n        - Boolean operators must be specified in uppercase and may be translated in\n        other languages.\n    - Logical grouping (with parentheses), e.g., `(a OR b) AND c`.\n    - Sequence of words (with double quotes), e.g., `\"a b c\"`. The default\n        difference between word positions is 1, meaning that an item will match if\n        it contains the words next to each other, but a different maximum distance\n        may be selected (with the tilde character), e.g. `\"web search\"~2` allows up\n        to 1 word between `web` and `search`, meaning it could match `web site\n        search` as well as `web search`.\n    - Term boosting (with the caret), e.g., `faceted^2 search browsing^0.5`\n        specifies that `faceted` is twice as important as `search` when computing\n        the relevance score of results, while `browsing` is half as important.\n        Boosting may be applied to a logical grouping, e.g., `(a b)^3 c`.\n    - Keyword search is case-insensitive, accents are folded, and punctuation is\n        ignored. To further improve recall (albeit at the cost of precision),\n        stemming is also performed on terms from most text fields, e.g., title,\n        abstract, notes. Stemming relieves the user from having to specify all\n        variants of a word when searching, e.g., terms such as `search`, `searches`,\n        and `searching` all return the same results. The [Snowball] algorithm is\n        used for that purpose.\n    - Full-text search: the text content of PDF attachments can be searched.\n    - Scope of search: users may choose to search everywhere, in\n        author/contributor names, in titles, in all fields (i.e., in metadata and\n        notes), or in documents (i.e., in the text content of attachments).\n        Applications may provide additional choices.\n- **Faceted browsing**: allows filtering by topic (Zotero tag), by resource type\n  (Zotero item type), by publication year. Moreover, you may define additional\n  facets modeled on collections and subcollections; in such case, any collection\n  can be represented as a facet, and each subcollection as a value within that\n  facet. By taking advantage of Zotero's ability to assign any given item to\n  multiple collections, a faceted classification scheme can be designed,\n  including hierarchical subdivisions within facets.\n- **Relevance scoring**: provided by the [Whoosh] library and based on the\n  [BM25F] algorithm, which determines how important a term is to a document in\n  the context of the whole collection of documents, while taking into account\n  its relation to document structure (in this regard most fields are neutral,\n  but the score is boosted when a term appears in specific fields, e.g., DOI,\n  ISBN, ISSN, title, author/contributor). Any keyword search asks the question\n  \"how well does this document match this query clause?\", which requires\n  calculating a relevance score for each document. Filtering with facets, on the\n  other hand, has no effect on the score because it asks \"does this document\n  match this query clause?\", which leads to a yes or no answer.\n- **Sort options**: by relevance score (only applicable to keyword search), by\n  publication date, by author, by title.\n- **Citation styles**: any from the [Zotero Style Repository][Zotero_styles], or\n  custom stylesheet defined in the [Citation Style Language][CSL] (stylesheet\n  must be accessible by URL).\n- **Language support**: the default language of the user interface is English,\n  but [some translations][Kerko_translations] are provided. Additional\n  translations may be created using gettext-compatible tools. Also to consider:\n  locales supported by the [Zotero Data Schema][Zotero_schema] (which provides\n  the names of fields, item types and author types displayed by Kerko);\n  languages supported by Whoosh (which provides the search capabilities), i.e.,\n  ar, da, nl, en, fi, fr, de, hu, it, no, pt, ro, ru, es, sv, tr.\n- **Semantic markup**: pages generated by Kerko embed HTML markup that can be\n  detected by web crawlers (helping the indexing of your records by search\n  engines) or by web browsers (allowing users of reference management tools to\n  easily import metadata in their library). Supported schemes are:\n    - [OpenURL COinS][COinS], in search results pages and individual\n      bibliographic record pages. COinS is recognized by [many reference\n      management tools][COinS_clients], including the [Zotero\n      Connector][Zotero_Connector] browser extension.\n    - Highwire Press tags, in the individual bibliographic record pages of book,\n      conference paper, journal article, report or thesis items. These tags are\n      recommended for indexing by [Google Scholar][HighwirePress_Google], and\n      are recognized by many other databases and reference management tools,\n      including the [Zotero Connector][Zotero_Connector] browser extension.\n- **Web feeds**: users of news aggregators or feed readers may get updates when\n  new bibliographic records are added. They may subscribe to the main feed, or\n  to one or more custom feeds.\n    - The main feed lists the most recently added bibliographic records.\n    - Any search page has a related custom feed that lists the most recently\n      added bibliographic records that match the search criteria. Thus, a user\n      can obtain a custom feed for a particular area of interest simply by\n      entering keywords to search and/or selecting filters.\n    - Feeds are provided in the [Atom syndication format][Atom].\n    - Basic metadata is provided directly in the feeds, using both Atom and\n      unqualified [Dublin Core][Dublin_Core] elements.\n    - An age limit may be configured to exclude older items from the feeds. This\n      may be useful to bibliographies that are frequently updated and mostly\n      meant to promote recent literature (all resources still remain visible to\n      the search interface regardless of their age).\n- **Sitemap**: an [XML Sitemap][XML_Sitemap] is automatically generated, and you\n  may use it to help search engines discover your bibliographic records.\n- **Exporting**: users may export individual records as well as complete\n  bibliographies corresponding to search results. By default, download links are\n  provided for the RIS and BibTeX formats, but applications may be configured to\n  export [any format supported by the Zotero API][Zotero_export].\n- **Printing**: stylesheets are provided for printing individual bibliographic\n  records as well as lists of search results. When printing search results, all\n  results get printed (not just the current page of results).\n- **Notes and attachments**: notes, attached files, and attached links to URIs\n  are synchronized from zotero.org and made available to users of the\n  bibliography. Regular expressions may be used to include or exclude such child\n  items from the bibliography, based on their tags.\n- **DOI, ISBN and ISSN resolver**: items that have such identifier in your\n  library can be referenced by appending their identifier to your Kerko site's\n  base URL.\n- **Relations**: bibliographic record pages show links to related items, if any.\n  You may define such relations using Zotero's _Related_ field. Moreover, Kerko\n  adds the _Cites_ and _Cited by_ relation types, which can be managed in Zotero\n  through notes. Custom applications can add more types of relations if desired.\n- **Pages**: simple informational pages can be defined using content from Zotero\n  standalone notes.\n- **Badges**: custom applications can have icons conditionally displayed next to\n  items.\n- **Responsive design**: the simple default implementation works on large\n  monitors as well as on small screens. It is based on [Bootstrap].\n- **Google Analytics integration**: just provide a Google Analytics stream ID to\n  have Kerko automatically include the tracking code into its pages.\n- **Integration**: as a Flask [blueprint][Flask_blueprint], Kerko can be\n  integrated into any Flask application. For a standalone application, however,\n  you may simply install [KerkoApp].\n- **Customizable front-end**: applications may partly or fully replace the\n  default templates, scripts and stylesheets with their own.\n- **Command line interface (CLI)**: Kerko provides commands for synchronizing or\n  deleting its data.\n\n[KerkoApp] is a standalone application built around Kerko. It inherits all of\nKerko's features and it provides a few additions of its own:\n\n- **Configuration files**: allow separation of configuration from code and\n  enable the [Twelve-factor App][Twelve-factor_App] methodology. Environment\n  variables and [TOML] configuration files are supported. Secrets,\n  server-specific parameters, and general parameters can be configured in\n  separate files.\n- Page templates for common HTTP errors.\n- Syslog logging handler (for Unix environments).\n\n\n## Learn more\n\nPlease refer to the [documentation][Kerko_documentation] for more details.\n\n\n[Atom]: https://en.wikipedia.org/wiki/Atom_(web_standard)\n[BM25F]: https://en.wikipedia.org/wiki/Okapi_BM25\n[Bootstrap]: https://getbootstrap.com/\n[CSL]: https://citationstyles.org/\n[COinS]: https://en.wikipedia.org/wiki/COinS\n[COinS_clients]: https://en.wikipedia.org/wiki/COinS#Client_tools\n[Dublin_Core]: https://en.wikipedia.org/wiki/Dublin_Core\n[Flask]: https://pypi.org/project/Flask/\n[Flask_blueprint]: https://flask.palletsprojects.com/en/latest/blueprints/\n[Kerko]: https://github.com/whiskyechobravo/kerko\n[Kerko_actions]: https://github.com/whiskyechobravo/kerko/actions\n[Kerko_documentation]: https://whiskyechobravo.github.io/kerko/\n[Kerko_pypi]: https://pypi.org/project/Kerko/\n[Kerko_translations]: https://github.com/whiskyechobravo/kerko/tree/main/src/kerko/translations\n[KerkoApp]: https://github.com/whiskyechobravo/kerkoapp\n[KerkoApp_demo]: https://demo.kerko.whiskyechobravo.com\n[Snowball]: https://snowballstem.org/\n[TOML]: https://toml.io/\n[Twelve-factor_App]: https://12factor.net/config\n[Whoosh]: https://pypi.org/project/Whoosh/\n[XML_Sitemap]: https://www.sitemaps.org/\n[Zotero]: https://www.zotero.org/\n[Zotero_Connector]: https://www.zotero.org/download/connectors\n[Zotero_demo]: https://www.zotero.org/groups/2348869/kerko_demo/items\n[Zotero_export]: https://www.zotero.org/support/dev/web_api/v3/basics#export_formats\n[Zotero_schema]: https://api.zotero.org/schema\n[Zotero_styles]: https://www.zotero.org/styles/\n\n# Changelog\n\nBefore doing an upgrade, please check the \"How to upgrade\" section of the Kerko\ndocumentation.\n\n## 1.1.0 (2023-12-23)\n\nFeatures:\n\n- Add the \"Publication year\" search scope. It is enabled by default, but can be\n  disabled by setting the `kerko.scopes.pubyear.enabled` configuration parameter\n  to `false`.\n- Add new configuration parameter `kerko.pages.*.` for defining content pages\n  whose content come from selected Zotero standalone notes.\n- Add a `\"page\"` type for the `kerko.link_groups.*.` configuration table, to\n  allow the creation of links to content pages.\n- Add configuration parameters `kerko.performance.whoosh_index_memory_limit` and\n  `kerko.performance.whoosh_index_processors` to give some control over the\n  Whoosh search engine's indexing performance.\n- Allow italic, bold, subscript, superscript and small-caps on Zotero fields\n  (such as titles and abstracts) where [rich text formatting\n  tags](https://www.zotero.org/support/kb/rich_text_bibliography) are used.\n- Add Spanish translation. Thanks to [Albert\n  Ormazabal](https://github.com/aormazabal).\n\nBug fixes:\n\n- Fix item title missing from item pages and from Atom feeds when item type is\n  Case, Email, or Statute.\n- Fix incorrect sorting of search results by title when item type is Case,\n  Email, or Statute.\n- Fix incorrect escaping of HTML markup in the HTML content elements of Atom\n  feeds.\n- Fix incorrect scope, analyzer, and boost factor associated with the `caseName`\n  search field.\n- Fix crash when a facet specifies no sort order.\n- Fix crash on empty search result pages when configuration parameter\n  `kerko.features.print_results_max_count` is greater than zero.\n- Fix badges displayed too close to title on item pages.\n\nOther changes:\n\n- Add `rel=\"noopener\"` to `target=\"_blank\"` links.\n- Add `rel=\"noreferrer\"` to links derived from Zotero library data, e.g.,\n  user-provided URLs, DOIs, link attachments.\n- Reduce the default memory limit for Whoosh's index writer from 256 MB to 128\n  MB. This can prevent swapping with large libraries on small machines. The\n  default limit may now be changed with the\n  `kerko.performance.whoosh_index_memory_limit` parameter.\n- Improve speed of single-item search pages, i.e., search pages having the\n  `page-len=1` URL parameter. This is achieved through removal of the `id`\n  parameter from pagination URLs. Obtaining those ids was requiring extra\n  processing. Instead, the `id` parameter is now added through the browser\n  History API when a pagination link is visited.\n- Add support for Python 3.12.\n- Replace pylint, pycodestyle, pydocstyle with Ruff.\n- Replace Yapf with Ruff formatter. Reformat whole code base.\n- Add pre-commit hooks. Run Ruff and other code checks on pre-commit.\n- Add template blocks to facilitate theming.\n- Improve documentation.\n\nBackwards incompatible changes:\n\n- Drop support for Python 3.7 (EOL).\n\nPossibly backwards incompatible changes (more or less internal API changes):\n\n- Kerko no longer provides a `kerko.blueprint` global object. Applications must\n  now instantiate the blueprint by calling `kerko.make_blueprint()` before\n  registering it. This prevents attempts to mutate the object after its\n  registration, especially in tests.\n- Upgrade many dependencies, including new major versions of Flask (3.x),\n  Flask-Babel (4.x), Werkzeug (3.x).\n- `kerko.extractors.TransformerExtractor` no longer applies transformers on\n  `None` values. If you need a transformer to process a `None` value (Kerko\n  itself has no such transformer), you now have to set the new `skip_none_value`\n  argument to `False` when instantiating the extractor.\n\n\n## 1.0.0 (2023-07-24)\n\nFeatures:\n\n- Add new configuration parameter `kerko.features.download_item`.\n\nBug fixes:\n\n- Fix Gunicorn not exiting if the default TOML config has errors (use the\n  `errno.EINTR` error code). Not an issue anyone should have encountered!\n\nBackwards incompatible changes:\n\n- Rename the following configuration parameters:\n    - `kerko.features.download_results_link` \u2192 `kerko.features.download_results`.\n    - `kerko.features.print_item_link` \u2192 `kerko.features.print_item`\n    - `kerko.features.print_results_link` \u2192 `kerko.features.print_results`\n\nOther changes:\n\n- Improve documentation.\n\n\n## 1.0.0alpha2 (2023-07-12)\n\nFeatures:\n\n- Add new configuration parameters `kerko.link_groups.*.` for defining sets of\n  links that may be used for navigation.\n- Add a breadcrumb trail to all pages. One or more base links can be configured\n  (see configuration parameters `kerko.breadcrumb` and\n  `kerko.link_groups.breadcrumb_base`).\n\nBug fixes:\n\n- Fix validation pattern too restrictive for the `kerko.zotero.csl_style`\n  configuration parameter.\n\nBackwards incompatible changes:\n\n- Items from the main navigation bar are now based on the\n  `kerko.link_groups.navbar` configuration. There is no default translation for\n  it. To change the default text or to translate it, you must override the\n  default `kerko.link_groups.navbar` in your configuration file. If you have\n  overridden the `_navbar_items.html.jinja2` template and wish to use the\n  configuration, you might want to adapt it, or revert to the default template.\n\nOther changes:\n\n- Improve documentation.\n\n\n## 1.0.0alpha1 (2023-06-29)\n\nFeatures:\n\n- Add the `--full` option to the `sync` command line interface (CLI) command.\n\nBug fixes:\n\n- Fix validation pattern too restrictive for the `kerko.facets.*.collection_key`\n  configuration parameter.\n- Fix incorrect typing for the `kerko.features.download_results_max_count` and\n  `kerko.features.print_results_max_count` configuration parameters.\n\nOther changes:\n\n- Rename the default branch of the repository from 'master' to 'main'. If you\n  have cloned the repository with Git, use the following commands to rename your\n  local branch:\n\n    ```bash\n    git branch -m master main\n    git fetch origin\n    git branch -u origin/main main\n    git remote set-head origin -a\n    ```\n\n- Make the `config` CLI command show the configuration in TOML format.\n- Make the `config` CLI command hide secrets by default. Add a `--show-secrets`\n  option.\n- Improve documentation.\n\nBackwards incompatible changes:\n\n- Prevent the `clean` CLI command from cleaning everything by default. To delete\n  everything, you now have to run `flask kerko clean everything`. This may help\n  prevent accidental deletion of the cache, which in some instances can take\n  long to rebuild.\n- Rename the following configuration parameters:\n    - `kerko.citation_formats.*` \u2192 `kerko.bib_formats.*`.\n    - `kerko.features.download_citations_link` \u2192 `kerko.features.download_results_link`\n    - `kerko.features.download_citations_max_count` \u2192 `kerko.features.download_results_max_count`\n    - `kerko.features.print_citations_link` \u2192 `kerko.features.print_results_link`\n    - `kerko.features.print_citations_max_count` \u2192 `kerko.features.print_results_max_count`\n- Rename the following views:\n    - `item_citation_download` \u2192 `item_bib_download`\n    - `search_citation_download` \u2192 `search_bib_download`\n\n\n## 1.0.0alpha0 (2023-06-26)\n\n*Warning:* Upgrading from version 0.9 or earlier will require that you adapt\nyour installation and configuration files, then rebuild your search index. Use\nthe commands below, then restart the application. If you are using KerkoApp,\nmake sure to check its [changelog][KerkoApp_changelog].\n\n```bash\nflask kerko clean index\nflask kerko sync index\n```\n\nFeatures:\n\n- Add many new configuration parameters. Please refer to the configuration\n  parameters documentation for the full list.\n- Add optional \"Open in Zotero\" and \"View on zotero.org\" buttons to item pages.\n  These are disabled by default (see new parameters\n  `kerko.features.open_in_zotero_app` and `kerko.features.open_in_zotero_web`).\n  Even when these are enabled, a user who wishes to use such button must first\n  enable it from the (also new) Preferences dialog.\n- Add a web API endpoint for retrieving information about the last\n  synchronization from Zotero.\n- Add the `kerko config` command to the Flask command line interface for\n  displaying all configuration parameters.\n\nOther changes:\n\n- Restructure and expand documentation into a unified documentation site for\n  both Kerko and KerkoApp.\n- Add Portuguese translation. Thanks to Gon\u00e7alo Cordeiro.\n\nBackwards incompatible changes:\n\n- Raise the minimum required versions of Flask, Flask-Babel, Bootstrap-Flask,\n  and WTForms. If you have a custom application, some of those may introduce\n  breaking changes.\n- The data directory has a new default location relative to the instance path.\n  Please check the documentation for the `DATA_PATH` and `INSTANCE_PATH`\n  configuration parameters. You may need to set one or both of those parameters,\n  and/or move your existing data directory.\n- Almost all configuration parameters have been renamed and/or moved into a\n  hierarchical structure. Hierarchical parameters are referred to using\n  path-like, dot-separated parameter names, and may conveniently be set with the\n  `kerko.config_helpers.config_set()` function. Here is a mapping of the changed\n  parameters:\n    - `KERKO_BOOTSTRAP_VERSION` \u2192 `kerko.assets.bootstrap_version`\n    - `KERKO_CSL_STYLE` \u2192 `kerko.zotero.csl_style`\n    - `KERKO_COMPOSER` \u2192 `kerko_composer`\n    - `KERKO_DATA_DIR` \u2192 `DATA_PATH`. Now optional, relative to the instance\n      path, and defaulting to `kerko` instead of `data/kerko`.\n    - `KERKO_DOWNLOAD_ATTACHMENT_NEW_WINDOW` \u2192 `kerko.features.download_attachment_new_window`\n    - `KERKO_DOWNLOAD_CITATIONS_LINK` \u2192 `kerko.features.download_citations_link`\n    - `KERKO_DOWNLOAD_CITATIONS_MAX_COUNT` \u2192 `kerko.features.download_citations_max_count`\n    - `KERKO_FEEDS` \u2192 `kerko.feeds.formats`\n    - `KERKO_FEEDS_FIELDS` \u2192 `kerko.feeds.fields`\n    - `KERKO_FEEDS_MAX_DAYS` \u2192 `kerko.feeds.max_days`\n    - `KERKO_FEEDS_REJECT_ANY` \u2192 `kerko.feeds.reject_any`\n    - `KERKO_FEEDS_REQUIRE_ANY` \u2192 `kerko.feeds.require_any`\n    - `KERKO_FULLTEXT_SEARCH` \u2192 `kerko.search.fulltext`\n    - `KERKO_HIGHWIREPRESS_TAGS` \u2192 `kerko.meta.highwirepress_tags`\n    - `KERKO_JQUERY_VERSION` \u2192 `kerko.assets.jquery_version`\n    - `KERKO_PAGE_LEN` \u2192 `kerko.pagination.page_len`\n    - `KERKO_PAGER_LINKS` \u2192 `kerko.pagination.pager_links`\n    - `KERKO_POPPER_VERSION` \u2192 `kerko.assets.popper_version`\n    - `KERKO_PRINT_CITATIONS_LINK` \u2192 `kerko.features.print_citations_link`\n    - `KERKO_PRINT_CITATIONS_MAX_COUNT` \u2192 `kerko.features.print_citations_max_count`\n    - `KERKO_PRINT_ITEM_LINK` \u2192 `kerko.features.print_item_link`\n    - `KERKO_RELATIONS_INITIAL_LIMIT` \u2192 `kerko.features.relations_initial_limit`\n    - `KERKO_RELATIONS_LINKS` \u2192 `kerko.features.relations_links`\n    - `KERKO_RELATIONS_SORT` \u2192 `kerko.features.relations_sort`\n    - `KERKO_RESULTS_ABSTRACTS_MAX_LENGTH` \u2192 `kerko.features.results_abstracts_max_length`\n    - `KERKO_RESULTS_ABSTRACTS_MAX_LENGTH_LEEWAY` \u2192 `kerko.features.results_abstracts_max_length_leeway`\n    - `KERKO_RESULTS_ABSTRACTS` \u2192 `kerko.features.results_abstracts`\n    - `KERKO_RESULTS_ABSTRACTS_TOGGLER` \u2192 `kerko.features.results_abstracts_toggler`\n    - `KERKO_RESULTS_ATTACHMENT_LINKS` \u2192 `kerko.features.results_attachment_links`\n    - `KERKO_RESULTS_FIELDS` \u2192 `kerko.search.result_fields`\n    - `KERKO_RESULTS_URL_LINKS` \u2192 `kerko.features.results_url_links`\n    - `KERKO_TEMPLATE_ATOM_FEED` \u2192 `kerko.templates.atom_feed`\n    - `KERKO_TEMPLATE_BASE` \u2192 `kerko.templates.base`\n    - `KERKO_TEMPLATE_ITEM` \u2192 `kerko.templates.item`\n    - `KERKO_TEMPLATE_LAYOUT` \u2192 `kerko.templates.layout`\n    - `KERKO_TEMPLATE_SEARCH` \u2192 `kerko.templates.search`\n    - `KERKO_TEMPLATE_SEARCH_ITEM` \u2192 `kerko.templates.search_item`\n    - `KERKO_TITLE` \u2192 `kerko.meta.title`\n    - `KERKO_WHOOSH_LANGUAGE` \u2192 `kerko.search.whoosh_language`\n    - `KERKO_WITH_JQUERY` \u2192 `kerko.assets.with_jquery`\n    - `KERKO_WITH_POPPER` \u2192 `kerko.assets.with_popper`\n    - `KERKO_ZOTERO_API_KEY` \u2192 `ZOTERO_API_KEY`\n    - `KERKO_ZOTERO_BATCH_SIZE` \u2192 `kerko.zotero.batch_size`\n    - `KERKO_ZOTERO_LIBRARY_ID` \u2192 `ZOTERO_LIBRARY_ID`\n    - `KERKO_ZOTERO_LIBRARY_TYPE` \u2192 `ZOTERO_LIBRARY_TYPE`\n    - `KERKO_ZOTERO_LOCALE` \u2192 `kerko.zotero.locale`\n    - `KERKO_ZOTERO_MAX_ATTEMPTS` \u2192 `kerko.zotero.max_attempts`\n    - `KERKO_ZOTERO_WAIT` \u2192 `kerko.zotero.wait`\n- The Kerko configuration should now be initialized by a call like\n  `kerko.config_helpers.config_update(app.config, kerko.DEFAULTS)`.\n- `Composer.__init__()` now only takes a configuration object as argument\n  instead of a bunch of arguments. Thus, the initial values of the `Composer`\n  instance now depend solely on the configuration.\n- Remove the `KERKO_USE_TRANSLATIONS` configuration variable. Kerko now relies\n  on the application's default Babel domain and translation directories. Custom\n  applications that wish to load Kerko's translations should now add\n  `kerko.TRANSLATION_DOMAIN` and `kerko.TRANSLATION_DIRECTORIES` to their Babel\n  configuration.\n- The `__init__()` method of `FacetSpec` and its subclasses now only accept\n  keyword arguments.\n- The `sort_key` argument to `FacetSpec.__init__()` is now `sort_by`.\n- `Composer` built-in fields `z_dateAdded` and `z_dateModified` are now named\n  `date_added` and `date_modified` respectively.\n\n\n## 0.9 (2022-12-29)\n\n*Warning:* Upgrading from version 0.8.x or earlier will require that you rebuild\nyour search index. Use the following commands, then restart the application:\n\n```bash\nflask kerko clean index\nflask kerko sync index\n```\n\nFeatures:\n\n- Add expand/collapse actions on facet values, allowing full exploration of\n  hierarchical facets without changing the current search.\n- Add an optional initial limit on the number of values to show under each\n  facet. When the initial limit is reached, a \"show more\" button allows the user\n  to expand the full list.\n- Add Atom syndication feeds.\n- Allow searching items by their Zotero key.\n- Add XML sitemap.\n- Add the `kerko count` CLI command (mostly meant for development purposes).\n\nBug fixes:\n\n- Fix last sync time not displayed at the bottom of search results when\n  `KERKO_PRINT_CITATIONS_LINK` and `KERKO_DOWNLOAD_CITATIONS_LINK` are both set\n  to `False`.\n- Fix the `kerko sync` CLI command not returning an error code with some types\n  of failures.\n- Fix invalid HTML in help modal.\n\nOther changes:\n\n- Handle new Zotero fields introduced with the new 'preprint' item type.\n- Apply a boost factor to DOI, ISBN and ISSN fields extracted from the Extra\n  field (previously, only the dedicated Zotero fields had a boost factor).\n- Under each facet, always show the facet's active filters first.\n- Make facet values with long labels easier to read (by indenting wrapped lines\n  to the right of the checkbox).\n- Add link to full bibliography from item pages.\n- Add blocks in templates to facilitate theming.\n- Remove `page` parameter from pagination links when `page=1`.\n- Improve documentation.\n- Make sync and schema-related error messages more helpful and user-friendly.\n- Move pydocstyle config to `pyproject.toml`.\n- Tag package as compatible with Python 3.10 and 3.11.\n- Remove leftover code related to Python versions older than 3.7\n\nBackwards incompatible changes:\n\n- Remove the `KERKO_FACET_COLLAPSING` option. The new initial limit on facets\n  values made this feature largely redundant.\n- Remove the `collapsible` param from the `FacetSpec` class.\n- Remove support for configuration variables `KERKO_ZOTERO_START` and\n  `KERKO_ZOTERO_END` (were only used for development and no longer practical).\n\nChanges that might break custom themes:\n\n- The HTML markup and CSS styles of expand/collapse buttons have changed.\n- The parameters of the `facet`, `facet_item`, `facet_items`, `facet_fields`\n  template macros have changed.\n- The `facets-container`, `facets`, and `facets-modal-body` element ids are now\n  required in `search.html.jinja2`.\n\nPossibly backwards incompatible changes (more or less internal API changes):\n\n- Rewrote the `criteria` module. `Criteria.keywords` and `Criteria.filters` work\n  pretty much as before, but everything else has changed.\n- Rewrote the `query` module, which had organically grown into an tangled mess,\n  now replaced with the `searcher` module. This new API is completely different.\n- Adapted view code to the above-mentioned `searcher` API.\n- Split the monolithic `views` module into multiple modules under `views`\n  (`item_creators`, `item_facets`, `item_relations`, `routes`, `search`), and\n  moved `breadbox`, `meta` (as `item_meta`), `pager`, and `sorter` under\n  `views`.\n\n\n## 0.8.1 (2021-11-16)\n\nBug fixes:\n\n- Fix missing dependency for package building.\n\n\n## 0.8 (2021-11-16)\n\n*Warning:* Upgrading from version 0.7.x or earlier will require that you clean\nand re-sync your existing search index. Use the following commands, then restart\nthe application:\n\n```bash\nflask kerko clean index\nflask kerko sync\n```\n\nFeatures:\n\n- Allow full-text search of PDF attachments. This can be disabled by setting\n  `KERKO_FULLTEXT_SEARCH` to `False`. Since this feature relies on Zotero's\n  full-text indexing, you must make sure that it works in Zotero first; see\n  [Zotero's\n  documentation](https://www.zotero.org/support/searching#pdf_full-text_indexing).\n- Add new search scopes \"Everywhere\" (to search both metadata fields and the\n  text content of attached documents) and \"In documents\" (to search the text\n  content of attached documents). The scope \"In all fields\" allows to search all\n  metadata fields, but not the text content of attached documents.\n- Display \"View on {hostname}\" links under search result items, for quick access\n  to the items' URLs. These can be disabled by setting `KERKO_RESULTS_URL_LINKS`\n  to `False`.\n- Move the \"Read\" buttons under search result items, as \"Read document\" links.\n  These can now be disabled by setting `KERKO_RESULTS_ATTACHMENT_LINKS` to\n  `False`.\n- Display DOI field values as hyperlinks (both in DOI fields, and in the Extra\n  field when lines are prefixed with 'DOI:').\n- Add support for imported file attachments, e.g., PDF files imported in your\n  Zotero library through the Zotero Connector. Previously, only \"attached copies\n  of files\" were supported.\n- Standalone notes and file attachments are now allowed into the search index.\n  Kerko filters them out of search results, but custom applications could search\n  them. A new view, `standalone_attachment_download`, lets one retrieve a\n  standalone file attachment.\n- Add configuration options for truncating long abstracts in search results\n  (`KERKO_RESULTS_ABSTRACTS_MAX_LENGTH` and\n  `KERKO_RESULTS_ABSTRACTS_MAX_LENGTH_LEEWAY`).\n- Embed Highwire Press tags in item pages. This is enabled by default but can be\n  disabled by setting `KERKO_HIGHWIREPRESS_TAGS` to `False`.\n- Allow tracking with Google Analytics (optional).\n- Allow relations in child notes to be specified as HTML links, i.e., in the\n  `href` attribute of `<a>` elements.\n- Allow inclusion or exclusion of items based on multiple tags (previously, only\n  a single pattern could be checked).\n\nBug fixes:\n\n- Fix irrelevant sync warnings, from extractors running on attachment items.\n- Fix empty prev/next links in search pages metadata.\n\nOther changes:\n\n- Make synchronization from Zotero much more efficient through incremental\n  updates. Instead of performing a full synchronization each time, Kerko now\n  retrieves just the newly added or updated items. This dramatically reduces the\n  number of Zotero API calls (and time) required to update Kerko's search index.\n  Note: **More work is planned** to eliminate some Zotero API calls that Kerko\n  still makes early in the synchronization process and that could be avoided\n  when its cache is already up-to-date.\n- Add a `sync cache` command to the command line interface.\n- On narrow screens, stack search form controls for better usability.\n- Respond with an HTTP 503 (Service Unavailable) when the search index is empty\n  or unreadable.\n- Make sorts more efficient by setting the `sortable` Whoosh flag on relevant\n  fields.\n- Leading and trailing underscore characters (`_`) are now trimmed from facet\n  value labels. This happens _after_ sorting the values, which means that the\n  underscore can still be used as a prefix to alter the alphabetical order.\n- Support more timezone names. Timezone names such as 'US/Eastern' or\n  'Europe/London' previously did not work, and times could not be converted\n  to daylight saving times.\n- Change labels:\n    - \"Print this citation\" \u2192 \"Print this record\" (on item pages)\n    - \"Download this citation\" \u2192 \"Download this record\" (on item & search pages)\n- Inject blocks in item Jinja2 template to facilitate theming.\n- Slightly increase some top/bottom margins.\n- Add the `type` HTML attribute to record download links.\n- Add the `rel=\"alternate\"` HTML attribute to record download links on item\n  pages. Also add a corresponding `link` element to the page `head`.\n- Added utilities for running automated integration tests. This will allow\n  testing many areas of Kerko that previously could hardly be tested.\n\nBackwards incompatible changes:\n\n- Remove deprecated `kerko index` CLI command (use `kerko sync` instead).\n\nPossibly backwards incompatible changes (more or less internal API changes):\n\n- Upgrade many dependencies, including new major versions of Flask (2.x), Jinja2\n  (3.x), Werkzeug (2.x), Click (8.x).\n- The default list for the `KERKO_RESULTS_FIELDS` setting now includes the\n  `'url'` field. If you have overridden that setting in your application and\n  `KERKO_RESULTS_URL_LINKS` is enabled, you'll probably have to add `'url'` too.\n- The schema field `item_type` has been renamed to `item_type_label`. If you\n  have custom templates, please review any use of `item.item_type`.\n- The structure of the `kerko/_search-result.html.jinja2` template has changed\n  somewhat. If you have overridden it, you'll need to review the changes.\n- The `ItemContext` class has been eliminated. The `Extractor.extract()` method\n  now receives an item's dictionary instead of an `ItemContext` object, and if\n  an item has children these are now available directly in the item (with the\n  `children` key). If you have created custom extractor classes, their\n  `extract()` method will need to be adapted accordingly.\n- Some extractor classes have been renamed:\n    - `BaseAttachmentsExtractor` \u2192 `BaseChildAttachmentsExtractor`\n    - `BaseNotesExtractor` \u2192 `BaseChildNotesExtractor`\n    - `LinkedURIAttachmentsExtractor` \u2192 `ChildLinkedURIAttachmentsExtractor`\n    - `NotesTextExtractor` \u2192 `ChildNotesTextExtractor`\n    - `RawNotesExtractor` \u2192 `RawChildNotesExtractor`\n    - `RelationsInNotesExtractor` \u2192 `RelationsInChildNotesExtractor`\n    - `StoredFileAttachmentsExtractor` \u2192 `ChildFileAttachmentsExtractor`\n- A view has been renamed:\n    - `item_attachment_download` \u2192 `child_attachment_download`\n- A default field has been renamed:\n    - `alternateId` \u2192 `alternate_id`\n\n## 0.7.1 (2021-02-04)\n\nSecurity fixes:\n\n- Fix unescaped date fields, causing a vulnerability to XSS attacks. This\n  vulnerability was introduced in version 0.7.\n\nBug fixes:\n\n- Fix wrong locale separator in the HTML lang attribute.\n\nOther changes:\n\n- Remove unwanted spacing after dropdown labels.\n\nDocumentation changes:\n\n- Fix missing info about library groupID in configuration docs. Thanks\n  [@drmikeuk](https://github.com/drmikeuk) for reporting the issue.\n\n## 0.7 (2021-01-08)\n\n*Warning:* Upgrading from version 0.6 or earlier will require that you clean and\nre-sync your existing search index. Use the following commands, then restart the\napplication:\n\n```bash\nflask kerko clean index\nflask kerko sync\n```\n\nFeatures:\n\n- Allow users to toggle the display of abstracts on search results pages.\n- Allow inclusion or exclusion of items based on their tags\n  ([#4](https://github.com/whiskyechobravo/kerko/issues/4)).\n- Show attached links to URIs on item pages.\n- Show relations on item pages. The relation types provided by default are:\n  - _Related_, based on Zotero's _Related_ field.\n  - _Cites_, managed through child notes containing Zotero URIs and tagged with\n    the `_cites` tag.\n  - _Cited by_, automatically inferred from _Cites_ relations.\n- The Extra field is now searched when searching \"in any fields\".\n- Items that have a DOI, ISBN or ISSN identifier can be referenced by appending\n  their identifier to your Kerko site's base URL.\n- Requests for the older URL of an item whose ID has changed are now\n  automatically redirected to the item's current URL. This relies on the\n  `dc.replaces` relation that's managed internally by Zotero on some operations\n  such as item merges.\n- Help users who might mistakenly bookmark a search result's URL rather than the\n  item's permanent URL: Add an `id` parameter to the search result URLs, and\n  redirect the user to that item's permanent URL if the search result no longer\n  matches because of database changes.\n- Redirect to the parent item's page when the user tries to request an\n  attachment that no longer exists.\n- Improve accessibility based on WCAG recommendations and WAI-ARIA standards:\n  - Add labels to search form elements.\n  - Add landmark role `search` to the search form.\n  - Make the purpose of various links more obvious through improved or added\n    labels.\n  - Add the `aria-label` attribute to many elements.\n  - Add text to indicate the current value of widgets.\n  - Add the `aria-current` attribute to indicate the current value of widgets.\n  - Remove useless link to the current page from the pagination widget.\n\nBug fixes:\n\n- Fix crash when trying to sync a link attachment\n  ([#3](https://github.com/whiskyechobravo/kerko/issues/3)).\n- Fix unhandled exception during sync when an attachment cannot be downloaded.\n- Fix page numbers greater than the page count in search URLs generating wrong\n  page numbers for search result item URLs.\n- Fix secondary keys getting sorted in reverse order with some sort options,\n  e.g., when sorting by newest first, results having the same date were then\n  sorted by creator name in reverse alphabetical order instead of alphabetical\n  order.\n- Fix empty HTML element taking up horizontal space when there are no badges.\n\nOther changes:\n\n- Display ISO 8601 calendar dates in a more readable format, using the\n  formatting style of the locale.\n- Show a timezone abbreviation along with time of last update from Zotero.\n- Add German translation. Thanks to [@mmoole](https://github.com/mmoole).\n- Fix broken \"Getting started\" example in README.\n- Migrate most package distribution options and metadata from `setup.py` to\n  `setup.cfg`.\n- Migrate project to a `src` layout.\n- Use Flask-Babel instead of its fork Flask-BabelEx, now that is has merged the\n  translation domain features from Flask-BabelEx.\n\nBackwards incompatible changes:\n\n- Drop support for Python 3.6. Kerko is no longer being tested under Python 3.6.\n  Known issue with 3.6 at this point: some ISO 8601 dates cannot be parsed and\n  reformatted; instead of being displayed in a locale-sensitive manner, these\n  get displayed as is. More issues might arise in the future with Python 3.6 as\n  Kerko continues to evolve.\n- All values of the `pager` dict passed to the `_pager.html.jinja2` template are\n  now lists. Previously, only the values at keys `'before'` and `'after'` were\n  lists; now the values at keys `'previous'`, `'first'`, `'current'`, `'last'`,\n  and `'next'` are lists as well.\n- The words `'blacklist'` and `'whitelist'` in variable names are replaced with\n  `'exclude'` and `'include'`.\n- The `KERKO_RESULTS_ABSTRACT` configuration variable is replaced by two\n  variables, `KERKO_RESULTS_ABSTRACTS` (note the now plural form) and\n  `KERKO_RESULTS_ABSTRACTS_TOGGLER`.\n- Citation download URLs now have the form\n  `{url_prefix}/{itemID}/export/{format}` for individual items (`'export'` has\n  been inserted), and `{url_prefix}/export/{format}/` for search result pages\n  (`'download'` has been replaced by `'export'`).\n- The `Extractor` class' interface has changed, improving consistency and\n  separation of concerns:\n  - All arguments to `__init__()` must now be specified as keyword arguments.\n  - The `extract()` method no longer have a `document` argument, and the `spec`\n    argument is now the last one. The method now returns a value instead of\n    assigning it to the document.\n  - The new `extract_and_store()` method handles extraction, encoding, and\n    assignment to the document, assigning the value only when it is not `None`.\n- The `AttachmentsExtractor` class has been renamed to\n  `StoredFileAttachmentsExtractor`.\n- `InCollectionExtractor` now extends collection membership to subcollections.\n  To preserve the previous behavior, set the `check_subcollections` parameter to\n  `False` when initializing the extractor.\n\nPossibly backwards incompatible changes (more or less internal API changes):\n\n- The `search_results` variable passed to the `search.html.jinja2` template is\n  now an iterator of tuples, where the first element of each tuple is a result,\n  and the second element the URL of the result.\n\n## 0.6 (2020-06-15)\n\nSecurity fixes:\n\n- Fix multiple vulnerabilities to XSS attacks. **All previous versions of Kerko\n  were vulnerable, thus an upgrade is highly recommended.**\n\nBackwards incompatible changes:\n\n- Remove default value for the `KERKO_DATA_DIR` configuration variable. KerkoApp\n  users don't need to worry about this as KerkoApp takes care of it, but custom\n  apps that did not already set this variable now have to.\n\nFeatures:\n\n- Open PDF documents in the browser's built-in PDF viewer (instead of opening\n  the browser's file download popup).\n- Add buttons for opening documents directly from search result pages (these\n  replace the previous paperclip badges).\n- Add button at the top of item pages for opening documents (makes the\n  availability of such documents much more obvious).\n- Add the `KERKO_DOWNLOAD_ATTACHMENT_NEW_WINDOW` configuration variable to\n  control whether to open documents in a new window or in the same window.\n- Display the date and time of the last successful synchronization from Zotero\n  at the bottom of search results.\n\nBug fixes:\n\n- Preserve newlines when displaying the value of the Extra field.\n- Preserve newlines when displaying abstracts in search result pages.\n- Fix filters missing on search pages that have no results.\n- Avoid empty box in print media when there is no search criteria.\n- Avoid empty box when the search index is missing.\n- Fix pluralization in CLI time elapsed messages.\n\nOther changes:\n\n- Refer to attachments as \"documents\" in the interface, and replace the\n  paperclip icon with a file icon.\n- Remove CSRF token from search form. Token expiration can impede legitimate\n  users, and the token is unnecessary as the form does not change the\n  application's state.\n- Add a proper message when none of the filters provided in the URL are\n  recognized.\n- Improve documentation.\n- Add INFO-level log message to report successful synchronization from Zotero.\n- Add blocks in templates to facilitate theming.\n\nPossibly backwards incompatible changes (more or less internal API changes):\n\n- Rename the `content_with_badges` template macro as `badges`, and leave it to\n  the caller to display content.\n- Remove badges that are related to attachments.\n\n## 0.5 (2019-11-19)\n\n*Warning:* Upgrading from version 0.4 or earlier will require that you clean and\nre-sync your existing search index. Use the following commands:\n\n```bash\nflask kerko clean index\nflask kerko sync\n```\n\nFeatures:\n\n- Add support for Zotero attachments.\n- Allow configuration of badges on items. The 'attachment' badge is provided by\n  default, displaying an icon on items that have one or more attachments.\n- Add help modal.\n- Improve customizability:\n  - Add `KERKO_TEMPLATE_*` configuration variables for page template names.\n  - Use configurable, separate templates to render facets and badges (see the\n    `renderer` argument to `kerko.specs.FacetSpec`, `kerko.specs.BadgeSpec`).\n  - Add the `KERKO_RESULTS_FIELDS` configuration variable to specify which\n    fields to retrieve with search queries.\n- Add building blocks for creating boolean facets based on collection membership\n  (new class `kerko.extractors.InCollectionExtractor`, new parameters for\n  `kerko.codecs.BooleanFacetCodec`).\n\nBug fixes:\n\n- Fix facets not ordered by weight on item page.\n- Preserve newlines in abstract display.\n- Fix incorrect use of bookmark link on item pages, set canonical link instead.\n- Prevent text overflow in some browsers on citations containing long URLs.\n\nOther changes:\n\n- Deprecate CLI command `kerko index` in favor of new command `kerko sync`.\n- Change title of the \"Refine\" panel to \"Explore\".\n- Change labels of the \"Print\" and \"Download\" buttons to \"Print this citation\"\n  and \"Download this citation\", to prevent any confusion with attachment\n  downloading.\n- Show the facets in a more robust and accessible Bootstrap modal, on small\n  screens, instead of the home-built drawer.\n- Use compact pagination widget on small screens.\n- Tweak sizing, positioning, and spacing of various UI elements.\n- Improve accessibility of various UI elements.\n- Make citation stand out more in item page.\n- Hide some elements and decorations in print media.\n- Make search query more efficient on item page.\n\nPossibly backwards incompatible changes (more or less internal API changes):\n\n- Force keyword arguments with `kerko.composer.Composer.__init__()`.\n- Rename `kerko.composer.Composer.__init__()` arguments\n  `default_note_whitelist_re` as `default_child_whitelist_re`,\n  `default_note_blacklist_re` as `default_child_blacklist_re`.\n- Rename method `kerko.views.item()` as `kerko.views.item_view()`.\n- Rename template file `_facet.html.jinja2` as `_facets.html.jinja2`.\n- Replace argument `checkboxes` in template macro `field()` with `add_link_icon`\n  and `remove_link_icon`.\n\n## 0.4 (2019-09-28)\n\nFeatures:\n\n- Allow search term boosting in relevance score calculation, e.g. `faceted^2\n  search browsing^0.5`.\n\nSecurity fixes:\n\n- Update minimum Werkzeug version to 0.15.3. See\n  [CVE-2019-14806](https://nvd.nist.gov/vuln/detail/CVE-2019-14806): \"Pallets\n  Werkzeug before 0.15.3, when used with Docker, has insufficient debugger PIN\n  randomness because Docker containers share the same machine id.\"\n\nOther changes:\n\n- Update jQuery version to 3.4.1.\n- Update French translations (translate boolean search operators).\n- Improve search form validation and error display.\n- Disable not-so-intuitive boolean search operators (`AndNot`, `AndMaybe`,\n  `Require` were unwanted but enabled by default by Whoosh's `OperatorsPlugin`).\n- Improve documentation.\n- Code cleanup.\n\n## 0.3 (2019-07-29)\n\nFeatures:\n\n- Exporting: users may export individual citations as well as complete\n  bibliographies corresponding to search results. By default, download links are\n  provided for the RIS and BibTeX formats, but applications may be configured to\n  export any format supported by the Zotero API.\n\nBug fixes:\n\n- Fix bad alignment of field names in print mode.\n- Remove warning when indexing an item with no authors\n  ([#1](https://github.com/whiskyechobravo/kerko/issues/1)).\n\nOther changes:\n\n- Move print button to bottom of search pages (next to the new download\n  dropdown).\n- Improve documentation.\n- Compile message catalog before building sdist and wheel.\n\nPossibly backwards incompatible changes (more or less internal API changes):\n\n- Method `kerko.composer.Composer.get_ordered_specs()` replaces\n  `get_ordered_scopes()`, `get_ordered_facets()` and `get_ordered_sorts()`.\n\n## 0.3alpha1 (2019-07-17)\n\n- Fix broken links in documentation.\n\n## 0.3alpha0 (2019-07-16)\n\n- First PyPI release.\n\n\n[KerkoApp_changelog]: https://github.com/whiskyechobravo/kerkoapp/blob/main/CHANGELOG.md\n",
    "bugtrack_url": null,
    "license": "",
    "summary": "A Flask blueprint that provides a faceted search interface for bibliographies based on Zotero.",
    "version": "1.1.0",
    "project_urls": {
        "Changes": "https://github.com/whiskyechobravo/kerko/blob/main/CHANGELOG.md",
        "Code": "https://github.com/whiskyechobravo/kerko",
        "Documentation": "https://whiskyechobravo.github.io/kerko/",
        "Homepage": "https://whiskyechobravo.github.io/kerko/",
        "Issue tracker": "https://github.com/whiskyechobravo/kerko/issues"
    },
    "split_keywords": [
        "academia",
        "bibliography",
        "bibliographies",
        "flask",
        "search",
        "zotero"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "ef51b78face1a6492704115a51b296cbfda349d12384129eb273eeab55c00320",
                "md5": "95290a9e0c7ec8f7eeb5f2074dc2d50a",
                "sha256": "d2176f60ca202bcd76ed785cab19e9f17b28a930cbb4cb83eb834d92d5af6d1f"
            },
            "downloads": -1,
            "filename": "Kerko-1.1.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "95290a9e0c7ec8f7eeb5f2074dc2d50a",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8",
            "size": 202816,
            "upload_time": "2023-12-23T18:56:13",
            "upload_time_iso_8601": "2023-12-23T18:56:13.920048Z",
            "url": "https://files.pythonhosted.org/packages/ef/51/b78face1a6492704115a51b296cbfda349d12384129eb273eeab55c00320/Kerko-1.1.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "c9a0a8b7591430f6af1cdc4da4d570a0b20163b828a9e7e063c0e58217ccc5cf",
                "md5": "c23f77d407c5c8a89f9b2e3ea4b1e8ad",
                "sha256": "0c6df8078b535b29b030c5d6040a2839a0f907ac8c25b7f79382f43765f7fbe8"
            },
            "downloads": -1,
            "filename": "Kerko-1.1.0.tar.gz",
            "has_sig": false,
            "md5_digest": "c23f77d407c5c8a89f9b2e3ea4b1e8ad",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8",
            "size": 383250,
            "upload_time": "2023-12-23T18:56:15",
            "upload_time_iso_8601": "2023-12-23T18:56:15.708953Z",
            "url": "https://files.pythonhosted.org/packages/c9/a0/a8b7591430f6af1cdc4da4d570a0b20163b828a9e7e063c0e58217ccc5cf/Kerko-1.1.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2023-12-23 18:56:15",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "whiskyechobravo",
    "github_project": "kerko",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "tox": true,
    "lcname": "kerko"
}