QuickSearch offers searches on all documents of the website generated by J1. Advantage: no internet access is needed for searches. Searches are based on a pre-build local full-text index loaded by the browser for all pages. The index for a site is generated by the Jekyll index plugin lunr_index.rb located in the plugins folder _plugins.

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

The searchable data in an index is organized as documents containing the text and the words you want to search on. A document is a JSON-based data set 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.

To do a simple full-text search as well as more specific searches, the search core engine Lunar 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 document, the more that term will increase that documents' score, but th 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 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, the relevance, for documents having both words in them at a higher level, and 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 words 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 an logical OR.

The above example will match documents that contain either jekyll or tutorial. Documents that contain both words will increase the score, and the matching documents returned first.

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

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

By default, Lunar 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 :.

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 content, some specific fields are available for searches.

By default, Lunar combines multiple terms in a search with a logical or. A search for jekyll and collections will match documents that contain the word jekyll or contain collections or contain both. This behavior is controllable. For example the presence of each term in matching documents can be specified.

A document must have at least one matching term to return a results. It is possible to specify that a term must be present in documents or that should be absent.

To indicate that a term must be present in matching documents, the term could be prefixed by a plus sign +, and to indicate that a term must be absent, the term should be prefixed by a minus sign -.

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

To simulate a logical function like and in a search of documents that contain the word jekyll and the word collection, prefix both words by a plus sign +.