RubyGems - j1-template - Versions diffs - 2023.7.0 → 2023.8.1 - Mend

j1-template 2023.7.0 → 2023.8.1

Files changed (134) hide show

data/lib/starter_web/pages/public/learn/roundtrip/lunr_search.1.asciidoc DELETED Viewed

@@ -1,460 +0,0 @@
----
-title:                                  Search
-title_extention:                        Integrated site search based on Lunr for J1 Template
-tagline:                                Lunr For J1
-date:                                   2020-11-08
-#last_modified:                         2023-01-01
-description: >
-                                        The search option for the J1 Template is based on the
-                                        search engine Lunr and is fully integrated with the
-                                        template system. Lunr is designed to be lightweight
-                                        yet full-featured to provide users with a great search
-                                        experience on websites.
-keywords: >
-                                        open source, free, template, jekyll, jekyllone, web,
-                                        sites, static, jamstack, bootstrap,
-                                        lunr, site search, quick search, find,
-                                        google, bing
-categories:                             [ Roundtrip ]
-tags:                                   [ Module, Site search ]
-image:
-  path:                                 /assets/images/modules/attics/lunr-1280x800.jpg
-  width:                                1920
-  height:                               1280
-regenerate:                             false
-permalink:                              /pages/public/learn/roundtrip/quicksearch/
-resources:                              [ animate, clipboard, lightbox, rouge ]
-resource_options:
-  - attic:
-      slides:
-        - url:                          /assets/images/modules/attics/lunr-1280x800.jpg
-          alt:                          Lunr Search Engine
----
-// Page Initializer
-// =============================================================================
-// Enable the Liquid Preprocessor
-:page-liquid:
-// Set (local) page attributes here
-// -----------------------------------------------------------------------------
-// :page--attr:                         <attr-value>
-//  Load Liquid procedures
-// -----------------------------------------------------------------------------
-{% capture load_attributes %}themes/{{site.template.name}}/procedures/global/attributes_loader.proc{%endcapture%}
-// Load page attributes
-// -----------------------------------------------------------------------------
-{% include {{load_attributes}} scope="all" %}
-// Page content
-// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-[role="dropcap"]
-The search option for the J1 Template is based on the search engine _Lunr_
-and is fully integrated with the Template. _Lunr_ is designed to be lightweight
-yet full-featured to provide users with a great search experience. Using Lunr for
-a Jekyll website, there is no need to integrate complex external, server-sided
-search engines like Google or Bing.
-WARNING: Searching a website using the build-in search engine is different
-from engines used by _Google_ or Microsoft _Bing_. Those search platforms
-are using complex artificial intelligence algorithms to make sense out of
-a *handful* of words given for an *Internet* search.
-Nevertheless, QuickSearch, the J1 built-in implementation, is simple like
-searching at _Google_ or _Bing_ but offers additional features to do searches
-specifically for *local websites*. QuickSearch provides an easy-to-use
-query language for better search results.
-mdi:clock-time-five-outline[24px, md-gray mt-4 mr-2]
-*10-15 Minutes* to read
-// Include sub-documents (if any)
-// -----------------------------------------------------------------------------
-[role="mt-5"]
-== Core concepts
-Understanding some of the concepts and terminology that QuickSearch based on
-_Lunr_ uses will allow users to provide powerful search functionality - to
-get more relevant search results of the *current* website.
-[role="mt-4"]
-=== Indexing Documents
-QuickSearch offers searches on *all* documents of the website generated by
-the template system but only for *this* site. Advantage, no internet access
-is required for *local* searches. 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* `lunr_index.rb`
-located in the root *_plugins* folder `/_plugins`.
-The full-text index is always generated by Jekyll at *build-time*:
-.Index creation at buildtime
-----
-Startup the site ..
-Configuration file: ...
- Incremental build: enabled
-      Generating...
-     J1 QuickSearch: creating search index ...
-     J1 QuickSearch: finished, index ready.
-     ....
-----
-Or, if you're running a website in development mode, the index get refreshed
-for all files added or modified.
-.Index creation if files added, or modified
-----
-site:       Regenerating: n file(s) changed at ...
-site:       ...
-site:      J1 QuickSearch: creating search index ...
-site:      J1 QuickSearch: finished, index ready.
-           ...
-----
-[role="mt-4"]
-=== Lunr Index
-The searchable data in an index is organized as data sets containing the
-text and the words, named as terms, you want to search on. A document is
-a *JSON data* set with fields that are processed to create the result list
-for a search.
-The *JSON data* data set might look like so:
-.Generated JSON data
-[source, json, role="noclip"]
-----
-{
-  "id": 3,
-  "title": "Roundtrip",
-  "tagline": "present images",
-  "url": "/pages/public/learn/roundtrip/present_images/",
-  "date": "2020-11-03 +0100",
-  "tags": [
-    "Introduction",
-    "Module",
-    "Image"
-  ],
-  "categories": [
-    "Roundtrip"
-  ],
-  "description": "Welcome to the preview page ... and galleries.\n",
-  "is_post": false
-}
-----
-In this data, there are several fields, like title `title`, tagline `tagline`,
-or description `description`, that could be used for *full-text* searches.
-Additional fields are available, like tas `tags` or categories `categories`,
-for more specific searches based on so-called *identifiers*.
-NOTE: The data *content* is collected by the intrinsic *body* field `<body`.
-To limit the index data loaded by the browser, the *body* field is removed
-from the data set, but the *content* is still fully searchable.
-To do a simple full-text search as well as more specific searches, the
-QuickSearch core engine Lunr offers a *query language* --a domain-specific
-language DSL. Find more about *QuickSearch|Lunr DSL* queries with the section
-<<QuickSearch>>.
-[role="mt-4"]
-=== Lunr Scoring
-The *relevance*, the so-called *score*, is calculated based on an algorithm
-called *BM25*. You don’t need to worry too much about the details of how this
-technique works. The *more* a search term occurs in a single page, the score
-is increased and *seldom* words will *decrease* the score.
-Scoring information is added to the local stored  search index and allows
-a very fast calculation of the relevance of all pages of a website for
-search queries.
-Imagine you’re website contains pages about Jekyll. The term *Jekyll* may
-occur very *frequently* throughout the entire website. So finding a page
-that mentions the term *Jekyll* isn’t very significant for a search.
-However, if you’re searching for the tem *Jekyll Generator*, only some pages
-of the website has the word *Generator* in them. That will bring the
-relevance for documents having *both* words in them at a higher level, and
-show 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.
-[role="mt-5"]
-== QuickSearch
-To access QuickSearch, a magnifier button
-// <a href="#" aria-label="Search"><i class="nav-icon mdib mdib-magnify mdib-2x"></i></a>
-is available in the `Quicklinks` area in the menu bar at the top-right of
-every page.
-.Search button (magnifier) in the quick access area
-lightbox::quicksearch-icon[ 800, {data-quicksearch-icon} ]
-A mouse-click on the magnifier button opens the search input and disables
-all other navigation to focus on what you're intended to do: searching.
-.Input bar for a QuickSearch
-lightbox::quicksearch-input[ 800, {data-quicksearch-input} ]
-Search queries look like simple text. But the search `engine` under the
-hood of QuickSearch transforms the given search string (text) always into a
-search query. Search queries support a special syntax, the DSL, for defining
-more complex queries for better (scored) results.
-As always: start simple!
-=== Simple Searches
-The simplest way to run a search is to pass the text (words, terms) on which
-you want to search on:
-[source, text]
-----
-jekyll
-----
-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`.
-[source, text]
-----
-jekyll tutorial
-----
-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.
-NOTE: Comparing to a Google search (terms are combined at Google by a
-logical `AND`) a Quicksearch combines the terms by an `OR`.
-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*:
-[source, text]
-----
-+jekyll +tutorial
-----
-[role="mt-4"]
-=== Searches using Wildcards
-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*  `Jek`:
-[source, text]
-----
-jek*
-----
-NOTE: Language grammar rules are not relevant for searches. For simplification,
-all words (terms) are transformed to lower case. As a result, the word
-`Jekyll` is the same as `jekyll` from a search-engines perspective. Language
-variations of `Jekyll's` or plurals like `Generators` are reduced
-to their base form. For searches, don't take care of grammar rules but the
-spelling. If you're unsure about the spelling of a word, use wildcards.
-////
-[role="mt-4"]
-=== Searches using Fields
-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:
-[source, text]
-----
-title:jekyll
-----
-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:
-[source, text]
-----
-+title:jek* +coll*
-----
-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.
-.Available fields (all documents)
-[cols="3a,3a,6a, options="header", width="100%", role="rtable mt-3"]
-|===
-|Name |Value |Description\|Example\|s
-|`title`
-|`string`
-|The headline of a document (article, post)
-Example\|s: QuickSearch
-[source, text]
-----
-title:QuickSearch
-----
-|`tagline`
-|`string`
-|The subtitle of a document (article, post)
-Example\|s: full index search
-|`tags`
-|`string`
-|Tags describe the content of a document.
-Example\|s: Roundtrip, QuickSearch
-|`categories`
-|`string`
-|Categories describe the group of documnets a document belongs to.
-Example\|s: Search
-|`description`
-|`string`
-|The description is given by the author for a document. It gives a brief
-summary what the document is all about.
-Example\|s: QuickSearch is based on the search engine Lunr, fully integrated
-with J1 Template  ...
-|===
-=== Boosts
-In multi-term searches, a single term may be important than others. For
-these cases Lunr supports term level boosts. Any document that matches a
-boosted term will get a higher relevance score, and appear higher up in
-the results. A boost is applied by appending a caret (`^`) and then a
-positive integer to a term.
-[source, javascript]
-----
-idx.search('foo^10 bar')
-----
-The above example weights the term “foo” 10 times higher than the term
-“bar”. The boost value can be any positive integer, and different terms
-can have different boosts:
-[source, javascript]
-----
-idx.search('foo^10 bar^5 baz')
-----
-=== Fuzzy Matches
-Lunr supports fuzzy matching search terms in documents, which can be
-helpful if the spelling of a term is unclear, or to increase the number
-of search results that are returned. The amount of fuzziness to allow
-when searching can also be controlled. Fuzziness is applied by appending
-a tilde (`~`) and then a positive integer to a term. The following
-search matches all documents that have a word within 1 edit distance of
-“foo”:
-[source, javascript]
-----
-idx.search('foo~1')
-----
-An edit distance of 1 allows words to match if either adding, removing,
-changing or transposing a character in the word would lead to a match.
-For example “boo” requires a single edit (replacing “f” with “b”) and
-would match, but “boot” would not as it also requires an additional “t”
-at the end.
-[role="mt-5"]
-== Lunr Term presence
-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`:
-[source, text]
-----
-+jekyll -collection
-----
-To simulate a logical *AND* search of documents that contain the word `jekyll`
-*AND* the word `collection`, mark both terms as required:
-[source, text]
-----
-+jekyll +collection
-----
-////
-[role="mt-5"]
-== What next
-You reached the end of the roundtrip. Hopefully you enjoyed exploring what J1
-can do for your new website. To make things real for your site, go for
-_J1 in a Day_.
-J1 in a Day is a tutorial learning to create modern websites using the J1
-Theme. This Tutorial focuses on the basics of Jekyll and J1, which all
-people need to know for a successful way to a modern static website. Jekyll
-(and J1) is quite different from classic Content Management Systems (CMS).
-If you would like to learn more about the use of Jekyll and J1 Template, the
-tutorials present what you need to know:
-* The basics of modern static webs
-* Creating an awesome Site
-* Development System
-* Project Management
-* Create Content
-It sounds much, spending a whole day to get Jekyll and J1 to know. Yes, it is
-much. But it makes sense to get a full overview of what can be achieved by
-modern static websites.
-It's a pleasant journey to learn what modern static webs can offer today.
-Start your journey from here:
-link:{url-j1-kickstarter--web-in-a-day}[J1 in a Day, {browser-window--new}].
-Have fun!