j1-template 2022.4.10 → 2022.5.0.rc0

data/lib/starter_web/pages/public/learn/_roundtrip/500_themes.adoc

@@ -0,0 +1,250 @@
+---
+title:                                  Roundtrip
+tagline:                                themes
+date:                                   2020-11-10 00:00:00
+description: >
+                                        The themes feature for J1 is in an experimental
+                                        state for the template system. Anyway, it makes
+                                        sense to present what is possible using different
+                                        versions of Bootstrap's CSS styles for a website.
+
+categories:                             [ Roundtrip ]
+tags:                                   [ Introduction, Module, Themes ]
+
+scrollbar:                              false
+fab_menu_id:                            page_ctrl
+
+permalink:                              /pages/public/learn/roundtrip/themes/
+regenerate:                             false
+
+resources:                              [ animate, rouge, clipboard, lightbox ]
+resource_options:
+  - attic:
+      slides:
+        - url:                          /assets/images/pages/roundtrip/themes-1920x1280-bw.jpg
+          alt:                          Photo by Clem Onojeghuo on Unsplash
+          badge:
+            type:                       unsplash
+            author:                     Clem Onojeghuo
+            href:                       https://unsplash.com/@clemono
+---
+
+// Page Initializer
+// =============================================================================
+// Enable the Liquid Preprocessor
+:page-liquid:
+
+// Set (local) page attributes here
+// -----------------------------------------------------------------------------
+// :page--attr:                         <attr-value>
+:images-dir:                            {imagesdir}/pages/roundtrip/100_present_images
+
+//  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
+// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+// Include sub-documents (if any)
+// -----------------------------------------------------------------------------
+[role="dropcap"]
+Themes for the template system J1 are based on the free and open-source CSS
+front-end framework {url-bs--home}[Bootstrap, {browser-window--new}] of
+version V5. Bootstrap is an HTML, CSS & JS Library that focuses on simplifying
+the development of modern web pages. The primary purpose of applying the
+framework to J1 is to provide a general standard for colors, sizes, fonts,
+and the overall layout of a J1-based site. Bootstrap provides basic style
+definitions for all commonly used HTML elements.
+
+Using Bootstrap base style only results in a uniform appearance for the
+content in terms of the overall layout, text, tables, and form elements
+across all modern web browsers available on the market. In addition,
+developers can take advantage of CSS classes defined in Bootstrap to
+customize content individually.
+
+The themes feature for J1 is in an experimental state for the template
+system. Anyway, it makes sense to present what is possible using different
+versions of Bootstrap's CSS styles for a website.
+
+== The Themes menu
+
+Themes step in the framework to further adjust the website's appearance
+based on the core CSS rules and definitions of Bootstrap. Themes do not
+change the framework's functionality but modify rule-based, e.g., the
+color scheme, fonts, sizes, or the appearance of more complex elements like
+forms or tables. Additionally, a theme may add additional components but in
+the *sense* of Bootstrap's framework rules and philosophy.
+
+It is expected that many people will change the template for their needs. To
+create unique websites. Fundamental to do this is are CSS styles
+defined by Bootstrap.
+
+Modifying the CSS styles of link:{url-bootstrap--home}[Bootstrap, {browser-window--new}]
+is not rocket science. But, to be honest, some knowledge is needed for
+link:{url-w3org--css-spec}[the CSS technology] to do so. We encourage you to spend
+some time first on learning CSS. To learn what is the
+link:{url-w3schools--css-tutorial}[design base, {browser-window--new}] of each and
+every website.
+
+.Themes menu (Bootswatch)
+lightbox::images--themes-menu[ 1024, {data-images--themes-menu} ]
+
+Thanks to the people at link:{url-bootswatch--home}[Bootswatch, {browser-window--new}],
+a great set of already prepared Bootstrap stylesheets in various designs are
+available on their website. There is no need to start from scratch, re-define all
+the Bootstrap variables, and rebuild the framework files to create a new
+theme. Many different styles are available. What is already available at
+Bootswatch is at least a good base for your modifications; your unique design.
+
+Besides the bunch of different stylesheets at Bootswatch, an
+link:{url-bootswatch--api}[Integration API, {browser-window--new}] is available
+that helps a lot to integrate available designs into an existing site. This API
+is the base to integrate selectable Bootswatch stylesheets into the J1 Template
+navigation system for easy use.
+
+=== Apply a theme
+
+The base for designing pages using the J1 Template is the theme Uno, a modern
+light theme used for many types of websites. And what we mentioned
+already, web design is not: one size fits all. The theme Uno can be seen as
+a good base, a starting point. Combining Uno and a different theme may be a fast
+solution for your site!?
+
+You can find all available themes and stylesheets on your pages
+from the menu Themes. You're invited to check how a page is changing for
+its design if other stylesheets, other ideas of web design are used.
+
+NOTE: Changing BS-based styles is one thing. Changing from one theme to the
+next at runtime is a bit more challenging. For the first version of the J1
+Template, many styles are automatically changed for J1 specific components,
+but not all of them for now.
+
+Select a theme from this menu, and a new BS-based stylesheet is
+automatically applied to your pages.
+
+== Code Highlighter Rouge
+
+_Rouge_ is a pure Ruby and themeable syntax highlighter. It can highlight
+100+ different languages and output HTML or ANSI 256-color text. Find all
+available themes and examples for several languages of how
+highlighting works using _Rouge_.
+
+For the default theme `Uno` of J1 Template, the following _Rouge_ themes
+are used:
+
+* light: `igorpro`
+* dark: `monokai.sublime`
+
+NOTE: The default themes used for the J1 Template can be configured with the
+global template config file `~/_data/j1_config.yml`.
+
+
+=== Apply a theme
+
+Make a selection of a theme below to preview.
+
+++++
+<div class="btn-group">
+  <!-- See: https://stackoverflow.com/questions/47242702/force-bootstrap-dropdown-menu-to-always-display-at-the-bottom-and-allow-it-go-of -->
+  <!-- NOTE: control the behaviour of popper.js for positioning -->
+  <!-- NOTE: set attribute data-flip="false" to open the SELECT list at the BOTTOM of the BUTTON -->
+  <button class="btn btn-primary btn-flex btn-lg dropdown-toggle" data-flip="false" type="button" data-bs-toggle="dropdown" data-bs-target="#navbarDropdown" aria-haspopup="true" aria-expanded="false">
+  Select Theme<span class="caret"></span>
+  </button>
+  <ul class="dropdown-menu scrollable-menu" role="menu">
+    <li><a class="dropdown-item" onclick="j1.adapter.rouge.reaplyStyles('base16')"> <i class="mdi mdi-view-quilt mdi-18px mr-2" style="color: #9E9E9E"></i>base16</a></li>
+    <li><a class="dropdown-item" onclick="j1.adapter.rouge.reaplyStyles('base16.dark')"> <i class="mdi mdi-view-quilt mdi-18px mr-2" style="color: #9E9E9E"></i>base16.dark</a></li>
+    <li><a class="dropdown-item" onclick="j1.adapter.rouge.reaplyStyles('base16.light')"> <i class="mdi mdi-view-quilt mdi-18px mr-2" style="color: #9E9E9E"></i>base16.light</a></li>
+    <li><a class="dropdown-item" onclick="j1.adapter.rouge.reaplyStyles('base16.monokai')"> <i class="mdi mdi-view-quilt mdi-18px mr-2" style="color: #9E9E9E"></i>base16.monokai</a></li>
+    <li><a class="dropdown-item" onclick="j1.adapter.rouge.reaplyStyles('base16.monokai.dark')"> <i class="mdi mdi-view-quilt mdi-18px mr-2" style="color: #9E9E9E"></i>base16.monokai.dark</a></li>
+    <li><a class="dropdown-item" onclick="j1.adapter.rouge.reaplyStyles('base16.monokai.light')"> <i class="mdi mdi-view-quilt mdi-18px mr-2" style="color: #9E9E9E"></i>base16.monokai.light</a></li>
+    <li><a class="dropdown-item" onclick="j1.adapter.rouge.reaplyStyles('base16.solarized')"> <i class="mdi mdi-view-quilt mdi-18px mr-2" style="color: #9E9E9E"></i>base16.solarized</a></li>
+    <li><a class="dropdown-item" onclick="j1.adapter.rouge.reaplyStyles('base16.solarized.dark')"> <i class="mdi mdi-view-quilt mdi-18px mr-2" style="color: #9E9E9E"></i>base16.solarized.dark</a></li>
+    <li><a class="dropdown-item" onclick="j1.adapter.rouge.reaplyStyles('base16.solarized.light')"> <i class="mdi mdi-view-quilt mdi-18px mr-2" style="color: #9E9E9E"></i>base16.solarized.light</a></li>
+    <li><a class="dropdown-item" onclick="j1.adapter.rouge.reaplyStyles('colorful')"> <i class="mdi mdi-view-quilt mdi-18px mr-2" style="color: #9E9E9E"></i>colorful</a></li>
+    <li><a class="dropdown-item" onclick="j1.adapter.rouge.reaplyStyles('github')"> <i class="mdi mdi-view-quilt mdi-18px mr-2" style="color: #9E9E9E"></i>github</a></li>
+    <li><a class="dropdown-item" onclick="j1.adapter.rouge.reaplyStyles('gruvbox')"> <i class="mdi mdi-view-quilt mdi-18px mr-2" style="color: #9E9E9E"></i>gruvbox</a></li>
+    <li><a class="dropdown-item" onclick="j1.adapter.rouge.reaplyStyles('gruvbox.light')"> <i class="mdi mdi-view-quilt mdi-18px mr-2" style="color: #9E9E9E"></i>gruvbox.light</a></li>
+    <li><a class="dropdown-item" onclick="j1.adapter.rouge.reaplyStyles('igorpro')"> <i class="mdi mdi-view-quilt mdi-18px mr-2" style="color: #9E9E9E"></i>igorpro</a></li>
+    <li><a class="dropdown-item" onclick="j1.adapter.rouge.reaplyStyles('molokai')"> <i class="mdi mdi-view-quilt mdi-18px mr-2" style="color: #9E9E9E"></i>molokai</a></li>
+    <li><a class="dropdown-item" onclick="j1.adapter.rouge.reaplyStyles('monokai')"> <i class="mdi mdi-view-quilt mdi-18px mr-2" style="color: #9E9E9E"></i>monokai</a></li>
+    <li><a class="dropdown-item" onclick="j1.adapter.rouge.reaplyStyles('monokai.sublime')"> <i class="mdi mdi-view-quilt mdi-18px mr-2" style="color: #9E9E9E"></i>monokai.sublime</a></li>
+    <li><a class="dropdown-item" onclick="j1.adapter.rouge.reaplyStyles('pastie')"> <i class="mdi mdi-view-quilt mdi-18px mr-2" style="color: #9E9E9E"></i>pastie</a></li>
+    <li><a class="dropdown-item" onclick="j1.adapter.rouge.reaplyStyles('thankful_eyes')"> <i class="mdi mdi-view-quilt mdi-18px mr-2" style="color: #9E9E9E"></i>thankful_eyes</a></li>
+    <li><a class="dropdown-item" onclick="j1.adapter.rouge.reaplyStyles('tulip')"> <i class="mdi mdi-view-quilt mdi-18px mr-2" style="color: #9E9E9E"></i>tulip</a></li>
+  </ul>
+</div>
+<div id="selected" class="mt-1 mb-3"></div>
+++++
+
+=== Highlight Liquid code
+
+{% raw %}
+[source, liquid]
+----
+Hello {{ 'now' | date: "%Y %h" }}
+
+{% comment %} if item.quantity is 4... {% endcomment %}
+{% for i in (1..item.quantity) %}
+  {{ i }}
+{% endfor %}
+----
+{% endraw %}
+
+=== Highlight Javascript code
+
+[source, javascript]
+----
+// helper functions
+//
+function styleSheetLoaded(styleSheet) {
+  var sheets     = document.styleSheets,
+      stylesheet = sheets[(sheets.length - 1)];
+
+  // find CSS file 'styleSheetName' in document
+  for(var i in document.styleSheets) {
+    if(sheets[i].href && sheets[i].href.indexOf(styleSheet) > -1) {
+      return true;;
+    }
+  }
+}
+----
+
+=== Highlight Ruby code
+
+[source, ruby]
+----
+require 'asciidoctor/extensions' unless RUBY_ENGINE == 'opal'
+include Asciidoctor <1>
+
+Asciidoctor::Extensions.register do
+  class J1BlockMacro < Extensions::BlockMacroProcessor
+    use_dsl
+    named :banner
+    name_positional_attributes 'role'
+
+    def process parent, target, attrs
+      html = %(<div id="#{target}" class="#{attrs['role']}"></div>)
+      create_pass_block parent, html, attrs, subs: nil
+    end
+  end
+  block_macro J1BlockMacro
+end
+----
+<1> don't miss to load the Asciidoctor ruby
+
+
+== What next
+
+Using a theme, the character of a website can change a lot. If you don't want
+to support multiple themes with your site, a theme is a good base to create
+your theme, anyway.
+
+An important feature for larger webs is searching. The visitors should be able
+to search your site to find pages and posts they are interested in. Check what
+is searching a J1 website all about at link:{url-roundtrip--quicksearch}[Quicksearch].

data/lib/starter_web/pages/public/learn/_roundtrip/600_quicksearch.adoc

@@ -0,0 +1,425 @@
+---
+title:                                  QuickSearch
+tagline:                                full text search based on lunr
+date:                                   2020-11-08 00:00:00
+description: >
+                                        QuickSearch is based on the search engine Lunr,
+                                        fully integrated with the J1 Template. Lunr is designed
+                                        to be lightweight yet full-featured to provide a
+                                        great search experience. No need for complex external,
+                                        server-sided search engines or commercial services
+                                        on the Internet like Google.
+
+categories:                             [ Roundtrip ]
+tags:                                   [ Introduction, Module, Lunr, QuickSearch ]
+
+toc:                                    true
+scrollbar:                              false
+fab_menu_id:                            page_ctrl
+
+permalink:                              /pages/public/learn/roundtrip/quicksearch/
+regenerate:                             false
+
+resources:                              [ animate, lunr, rouge, lightbox, clipboard ]
+resource_options:
+  - toccer:
+      collapseDepth:                    3
+  - attic:
+      slides:
+        - url:                          /assets/images/modules/attics/banner/lunr-banner-1280x800.jpg
+          alt:                          Lunr
+---
+
+// 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
+// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+// Include sub-documents (if any)
+// -----------------------------------------------------------------------------
+[role="dropcap"]
+QuickSearch is based on the search engine Lunr, fully integrated with the J1
+Template. Lunr is designed to be lightweight yet full-featured to provide a
+great search experience. No need for complex external, server-sided search
+engines or commercial services on the Internet like Google. Searching a website
+using QuickSearch is different from search engines like Google or Microsoft
+Bing. Those search platforms using complex algorithms to provide a simple
+interface to the public but using a lot of artificial intelligence (AI) methods
+to make sense of results out of a handful of words given for a search.
+
+Nevertheless, QuickSearch, the J1 implementation of Lunr, is simple like
+searching at Google but offers additional features to do searches more
+specifically - if wanted. QuickSearch provides an easy-to-use query language
+for better results - anyway!
+
+== Core concepts
+
+Understanding some of the concepts and terminology that QuickSearch (Lunr)
+uses will allow users to provide powerful search functionality - to get more
+relevant search results.
+
+=== Indexing documents
+
+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:
+
+.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.
+           ...
+----
+
+=== Documents
+
+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:
+
+[source, json, role="noclip"]
+----
+{
+  "id": 3,
+  "title": "Roundtrip",
+  "tagline": "present images",
+  "url": "/pages/public/learn/roundtrip/present_images/",
+  "date": "2020-11-03 00:00:00 +0100",
+  "tags": [
+    "Introduction",
+    "Module",
+    "Image"
+  ],
+  "categories": [
+    "Roundtrip"
+  ],
+  "description": "Welcome to the preview page ... and galleries.\n",
+  "is_post": false
+}
+----
+
+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`.
+
+NOTE: The document *content* is collected by the (intrinsic) field `body`.
+To limit the index data loaded by the browser, the body field is removed from
+a document. The `body` field not available as an *explicit* field for searches,
+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 DSL (domain-specific
+language). Find more about *QuickSearch|Lunr DSL* queries with the section
+<<Searching>>.
+
+=== Scoring
+
+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.
+
+== Searching
+
+To access QuickSearch, a magnifier button 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
+----
+
+=== 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`:
+
+[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.
+
+
+=== 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.
+////
+
+=== 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
+----
+
+== 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_. This tutorial guides you through all the steps on how to
+setup your environment, manage and build a website and how to create content.
+
+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!