There's a lot of open issues
No release in over a year
A Liquid + Web Component for Bridgetown sites which performs search queries with Lunr.js.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

~> 1.6
~> 13.0
~> 3.0

Runtime

>= 1.2.0.beta2, < 2.0
 Project Readme

Bridgetown Quick Search plugin

This Bridgetown plugin provides a component you can add to your site (likely the top navbar) to allow fast, real-time search of your posts, pages, and other collection documents. It automatically generates a JSON index file which gets built along with the rest of the site, and then the component consumes that file and uses Lunr.js to construct the live search index and provide the search results as you type.


Installation for Bridgetown 1.2+

Run this command to add this plugin to your site's Gemfile:

$ bundle add bridgetown-quick-search

And then add the initializer to your configuration in config/initializers.rb:

init :"bridgetown-quick-search"

(For Bridgetown 1.1 or earlier, read these instructions.)

Next, add this line to the top of your frontend's Javascript index file:

// frontend/javascript/index.js

import "bridgetown-quick-search/dist"

Then add the Liquid component to one of your site templates, for example src/_components/navbar.liquid:

{% render "bridgetown_quick_search/search" %}

If you're using a Ruby-based template (ERB, etc.), you can use the liquid_render helper:

<%= liquid_render "bridgetown_quick_search/search" %>

Component Options

You can provide additional Liquid variables to the component to configure its appearance. These are:

  • placeholder: Text that will appear in the input control when no search value is present
  • input_class: Add custom CSS class names to the input control
  • theme: The component's default theme is a "light" appearance, but you can also set it to use a "dark" appearance
  • snippet_length: The length of the text snippet for each search result. Defaults to 142.

Here's an example of using all variables at once:

{% render "bridgetown_quick_search/search", placeholder: "Search", input_class: "input", theme: "dark", snippet_length: 200 %}

Styling

You can use CSS variables to control aspects of the search results popup. The popup is rendered inside of a Web Component using Shadow DOM, so these variables are the primary method of altering its appearance. The available variables are link-color, divider-color, text-color, border-radius and border-corner-radius.

bridgetown-search-results {
  --link-color: #0f5348;
  --divider-color: #e6e1d7;
  --text-color: #3e3f3a;
}

You can also alter the outer popup container via the custom element directly, as well as the wrapper surrounding the results contents using CSS Shadow Parts:

bridgetown-search-results {
/* Adjust the outer container of the popup */
}

bridgetown-search-results::part(inner) {
/* Adjust the popup contents wrapper */
}

bridgetown-search-results::part(inner-link) {
/* Adjust the link style of each search result */
}

Controlling the Search Index

You can add exclude_from_search: true to the front matter of any page or document to exclude it from the search index JSON. To batch-exclude pages, collections, categories, etc., you could use front matter defaults to set the exclude_from_search variable.

Testing

  • Run bundle exec rspec to run the test suite
  • Or run script/cibuild to validate with Rubocop and test with rspec together.

Contributing

  1. Fork it (https://github.com/bridgetownrb/bridgetown-quick-search/fork)
  2. Clone the fork using git clone to your local development machine.
  3. Create your feature branch (git checkout -b my-new-feature)
  4. Commit your changes (git commit -am 'Add some feature')
  5. Push to the branch (git push origin my-new-feature)
  6. Create a new Pull Request