QuickSearch offers searches on all documents of the website generated by J1 but only for this site. Advantage, no internet access is done for searches because it’s not needed. Searches are based on a pre-build local site full-text index loaded by the browser on a page request. The index for a site is generated by the (Jekyll) plugin lunr_index.rb located in the _plugins folder.

The full-text index is always generated by Jekyll at build-time:

Or, if you’re running a website in development mode, the index get refreshed for all files added or modified.

The searchable data in an index is organized as documents containing the text and the words (terms) you want to search on. A document is a data set (JSON object) with fields that are processed to create the result list for a search.

A document data set might look like this:

In this document, there are several fields, like title, tagline, or description, that could be used for full-text searches. But additional fields are available, like tags or categories that can be used for more specific searches based on identifiers.

To do a simple full-text search as well as more specific searches, the QuickSearch core engine Lunr offers a query language, a DSL (domain-specific language). Find more about QuickSearch|Lunr DSL queries with the section Searching.

The relevance (the score) is calculated based on an algorithm called BM25, along with other factors. You don’t need to worry too much about the details of how this technique works. To summarize: the more a search term occurs in a single document, the more that term will increase that document’s score, but the more a search term occurs in the overall collection of documents, the less that term will increase a document’s score. In other words, seldom words count and increase the score.

Scoring information generated by the BM25 algorithm is added to the (local) search index and allows a very fast calculation of the relevance of documents for queries.

Imagine you’re website contains documents about Jekyll. The term Jekyll may occur very frequently throughout the entire website. Used quite often for the content. So finding a document that mentions the term Jekyll isn’t very significant for a search.

However, if you’re searching for Jekyll Generator, only some documents of the website has the word Generator in them, and that will bring the score (relevance) for documents having both words in them at a higher level, bring them higher up in the search results.

Matching and scoring are used by all search engines - the same as for J1 QuickSearch. You’ll see for QuickSearch a similar behavior in sorting search results as you already know from commercial internet search engines like Google: the top results are the more relevant ones.

The simplest way to run a search is to pass the text (words, terms) on which you want to search on:

The above will return all documents that match the term jekyll. Searches for multiple terms (words) are also supported. If a document matches at least one of the search terms, it will show in the results. The search terms are combined by a logical OR.

The above example will match documents that contain either jekyll OR tutorial. Documents that contain both will increase the score, and those documents are returned first.

To combine search terms in a QuickSearch query by a logical AND, the terms could be prepended by a plus sign (+) to mark them as for the QuickSearch query (DSL) as required:

QuickSearch supports wildcards when performing searches. A wildcard is represented as an asterisk (*) and can appear anywhere in a search term. For example, the following will match all documents with words beginning with Jek:

By default, Lunr will search all fields in a document for the given query terms, and it is possible to restrict a term to a specific field. The following example searches for the term jekyll in the field title:

The search term is prefixed with the field’s name, followed by a colon (:). The field must be one of the fields defined when building the index. Unrecognized fields will lead to an error.

Search queries based on fields can be combined with all other term modifiers like wildcards. For example, to search for words beginning with jek in the title AND the wildcard coll* in a document, the following query can be used:

Besides the document body, an intrinsic field to create the full-text index out of the document content, some more specific fields are available for searches.

By default, Lunr combines multiple terms in a search with a logical OR. That is, a search for jekyll collections will match documents that contain jekyll or contain collections or contain both. This behavior is controllable at the term level, i.e., the presence of each term in matching documents can be specified.

By default, each term is optional in a matching document, though a document must have at least one matching term. It is possible to specify that a term must be present in matching documents or that it must be absent in matching documents.

To indicate that a term must be present in matching documents, the term could be prefixed with a plus sign (+) (required), and to indicate that a term must be absent (not wanted), the term should be prefixed with a minus (-).

The below example searches for documents that must contain jekyll, and must not contain the word collection:

To simulate a logical AND search of documents that contain the word jekyll AND the word collection, mark both terms as required: