-
Notifications
You must be signed in to change notification settings - Fork 252
Home
NOTE: This wiki provides developer documentation for the latest Blacklight release. For documentation of older releases, please see the end of this page.
Blacklight is an open source Ruby on Rails "engine" that provides a basic discovery interface for searching an Apache Solr index, including fielded searching, applying and removing facet constraints, sorting and paginating through search results, and more. As an engine, Blacklight components are customizable via Rails (templating) mechanisms to meet the search and discovery needs of heterogeneous data, allowing different information displays for different types of objects.
Other out-of-the-box features include:
- Stable URLs for search and record pages allow users to bookmark, share, and save search queries for later access
- A JSON API For searching and retrieving records
- RSS and Atom feeds of search results
- OpenURL/Z39.88 COinS support, allowing plugins like Zotero to easily extract data from the page.
- OpenSearch and schema.org, a collection of simple formats for the sharing of search results.
This wiki provides high-level documentation of Blacklight and supplements the inline code documentation (also available from RubyDocs). This wiki assumes you have prior experience with Ruby and Ruby on Rails. If you have no prior experience with either, there are some good free resources on the internet for learning Ruby, including:
And resources for learning Rails, including:
Additionally, you may want to review the official Apache Solr Tutorial, as the underlying search index and configuration provides and powers much of the Blacklight user experience but are outside the scope of this guide. This includes topics like how to index data into Solr, how to configure Solr request handlers, and the Solr schema format.
Each version of Blacklight may have specific requirements for underlying technologies and inherits some requirements from upstream software (like Rails, Solr, etc). As of Blacklight 9, these requirements are:
- Ruby 3.3 or greater
- Rails 7.2 or greater (note that Rails has additional prerequisites, including SQLite3)
- Solr 9 or greater (which again has its own system requirements, including Java 11 or greater)
In general, Blacklight provides support for currently supported versions of Ruby, Ruby on Rails, and related components.
The quickstart guide will walk you through running Solr, building a new Rails application with Blacklight, and indexing a sample set of records. You can also start from a pre-generated Blacklight application.
Additional workshop materials are available for learning how to customize and extend the application.
Blacklight provides out-of-the-box support for many types of search interactions through configuration, and with additional customization can be adapted to work with many types of data and user experience needs.
- Connecting to a Solr index
- Indexing your data into Solr
- Extending or Modifying Blacklight Search Behavior How to change the way the Blacklight discovery feature works.
A list of available Blacklight configuration options, and their default values, is available at
blacklight/configuration.rb. In addition to the Blacklight-defined configuration discussed here, you may also add application-specific configuration (e.g. for controlling behavior in overridden partials) or plugin-specific configuration.
There are many ways to override Blacklight's out-of-the-box user experience and search interactions because Blacklight is distributed as a Rails engine that resides within your own application. This means that most any customization can be done within your application by overriding Blacklight-provided behaviors without needing Blacklight to support specific configuration for less common or application-specific use cases. That said, this wiki has a directory of Blacklight plugins that has some types of functionality that is not in core Blacklight but is easily shared across multiple applications.
- Understanding Rails and Blacklight How the Blacklight engine integrates with your application
- Providing your own view templates: Overriding the out-of-the-box Blacklight templates the Rails way.
- Configuring Rails Routes
- Theming: Overriding the Blacklight CSS
- Pagination: Advice on how to customize pagination with Kaminari
- Adding new document actions How to extend the document actions with application-specific behavior
- Internationalization: Translating (or simply customizing) the Blacklight copy
- User Authentication: Connecting Blacklight with an existing Authentication system
- There are lots of plugins and add-ons, documented here.
Don't be scared to ask a question on the #blacklight channel in the Code4Lib Slack team. If you're not on Code4Lib Slack, you can request an invitation. This is the primary place where conversation takes place.
We appreciate you checking the documentation first and asking an educated question, but don't beat your head against the wall -- sometimes the existing documentation may be out of date and inaccurate.
There is also a Blacklight mailing list. In order to reduce spam, the first time you post your email will be held in a moderation queue, but as soon as your first message is approved your posts won’t be held for moderation any longer.
The Blacklight community actively supports the most current version of Blacklight. This support includes bug fixes, code refactoring to accommodate evolving dependencies, and new feature development.
After a new version is released, there is no active support for previous versions. All versions preceding the current version can be effectively considered "End of Life," though no specific EOL date will be assigned. Community members may still patch or backport features to previous versions as per their needs, but it should not be expected.
Contributor: Anyone is welcome to contribute to the Blacklight project. You can participate in Blacklight Community discussions, and provide pull requests, documentation, suggestions, and criticism.
Committer: A committer is a contributor who has write access to the code repository, and the role carries some expectations around engagement in community discussions, code review, and maintenance. See Becoming a Committer.
Priorities for Blacklight are often discussed at the monthly Community Call and annual Blacklight Summit. They are generally based around the needs of participating institutions. Significant changes are expected to be vetted in consultation with the community via the Community Call, Slack, mailing list, and discussions on GitHub issues or pull requests. Decisions are typically indicated in the form of whether or not PRs get approved and merged by committers.
The Blacklight Community Call can help answer questions, brainstorm new initiatives, and identify challenges for future prioritization. The annual Blacklight Summit (example from 2025) is a moment for the community to present initiatives at their institutions, learn more about specific issues, and engage in conversation with colleagues from other institutions.
A Blacklight Usability Working Group was also formed in July 2026. This group will be a good place to propose, discuss, and help steer new feature development.
- Contributing to Blacklight
- Pull Requests for Blacklight
- How to release a version
- Testing and Developing Blacklight
This wiki provides developer documentation for the main branch of Blacklight, which may include documentation of features not present in every Blacklight version. For documentation of specific Blacklight releases, see also:
- Home
- Blacklight 5.9
- Blacklight 4.7
- Blacklight 3.x
- Blacklight 3.0 or 3.1
- Blacklight 2.x for all Blacklight 2.x releases; version-specific documentation is also available: