j1-template 2021.0.2 → 2021.0.7

data/lib/starter_web/pages/public/learn/roundtrip/400_asciidoc_extensions.adoc

@@ -1,7 +1,7 @@
 ---
 title:                                  Roundtrip
 tagline:                                asciidoc extensions
-date:                                   2020-11-07 12:00:00
+date:                                   2020-11-07 00:00:00
 description: >
                                         J1 Template implements some incubating Ruby-based extensions
                                         for Asciidoctor. Most extensions are based on the examples
@@ -37,7 +37,7 @@ resource_options:
 // Enable the Liquid Preprocessor
 :page-liquid:
 
-// Set page (local) attributes here
+// Set (local) page attributes here
 // -----------------------------------------------------------------------------
 // :page--attr:                         <attr-value>
 :images-dir:                            {imagesdir}/pages/roundtrip/100_present_images
@@ -491,19 +491,16 @@ lorem:email[]
 
 // Include documents
 // -----------------------------------------------------------------------------
-
 include::{documentdir}/100_gistblock.asciidoc[]
 
 
 == Whats next
 
 Asciidoc, respectively Asciidoctor, extensions open up the Markup language to
-new use cases; using the full power of programming languages to extend what's
-needed whether it be Ruby, Java, Groovy or JavaScript.
-
-The number of extensions will grow - to get handy and powerful functionality
-that is needed for modern Web pages based on the Asciidoc Markup language
-generated by Jekyll. For sure!
+new use cases. Using the full power of programming languages to extend what's
+needed whether it be Ruby, Java, Groovy or JavaScript. The number of extensions
+will grow - to get handy and powerful functionality that is needed for modern
+web pages based on the Asciidoc Markup language generated by Jekyll. For sure!
 
 The next preview is focussing advanced Bootstrap Modals. The modals feature
 is currently in beta status, but it is a great option to customize your

data/lib/starter_web/pages/public/learn/roundtrip/410_bs_modals_extentions.adoc

@@ -1,7 +1,7 @@
 ---
 title:                                  Roundtrip
 tagline:                                advanced bootstrap modals
-date:                                   2020-11-08 12:00:00
+date:                                   2020-11-08 00:00:00
 description: >
                                         Bootstrap modals are used to add dialogues to your web pages for user
                                         notifications. To highlight important information to your visitor's. Modals
@@ -32,7 +32,7 @@ resource_options:
 // Enable the Liquid Preprocessor
 :page-liquid:
 
-// Set page (local) attributes here
+// Set (local) page attributes here
 // -----------------------------------------------------------------------------
 // :page--attr:                         <attr-value>
 :images-dir:                            {imagesdir}/pages/roundtrip/100_present_images
@@ -71,9 +71,8 @@ critical messages.
 NOTE: For more information on how to use Bootstrap’s JavaScript modal
 plugin, refer to: link:{bs_doc_components_modal}[Bootstrap Docs, {browser-window--new}].
 
-// Include sub-documents
-// -----------------------------------------------------------------------------
-include::{documentdir}/410_table_3_column.asciidoc[]
+// include::{documentdir}/tables/bs_modal_examples.asciidoc[]
+include::{documentdir}/410_table_bs_modal_examples.asciidoc[]
 
 == Whats next
 
@@ -89,5 +88,5 @@ what the link:{roundtrip-responsive-tables}[BS tables extensions] can do!
 
 
 // Include the modals HTML portion
-// -------------------------------------------------------------------
+// -----------------------------------------------------------------------------
 include::{documentdir}/419_advanced_modals_demo.asciidoc[]

data/lib/starter_web/pages/public/learn/roundtrip/420_responsive_tables_extensions.adoc

@@ -1,7 +1,7 @@
 ---
 title:                                  Roundtrip
 tagline:                                responsive tables
-date:                                   2020-11-09 12:00:00
+date:                                   2020-11-09 00:00:00
 description: >
                                         Creating a design for responsive tables is challenging. The approach used by
                                         J1 Template is based on pure CSS on top of the classic Bootstrap styles for
@@ -35,10 +35,9 @@ resource_options:
 // Enable the Liquid Preprocessor
 :page-liquid:
 
-// Set page (local) attributes here
+// Set (local) page attributes here
 // -----------------------------------------------------------------------------
 // :page--attr:                         <attr-value>
-:debug:
 :images-dir:                            {imagesdir}/pages/roundtrip/100_present_images
 
 //  Load Liquid procedures
@@ -57,58 +56,6 @@ Creating a design for responsive tables is challenging. The approach used by
 J1 Template is based on pure CSS on top of the classic Bootstrap styles for
 simplicity and portability to be viewed best on all devices and browsers.
 
-ifdef::debug[]
-
-.Source, options NOT set
-[source, md, role="noclip"]
-----
-[cols=",", options="header", ]
-|===============================================================================
-|Bratze |Bru
-
-|Fick
-|dich
-
-|===============================================================================
-----
-
-
-.Options NOT set
-[cols=",", options="header", ]
-|===============================================================================
-|Bratze |Bru
-
-|Fick
-|dich
-
-|===============================================================================
-
-.Source, options SET
-[source, adoc, role="noclip"]
-----
-[cols="6a,6a", options="header", width="100%", role="table-responsive mt-3"]
-|===============================================================================
-|Bratze |Bru
-
-|Fick
-|dich
-
-|===============================================================================
-----
-
-.options set
-[cols="6a,6a", options="header", width="100%", role="table-responsive mt-3"]
-|===============================================================================
-|Bratze |Bru
-
-|Fick
-|dich
-
-|===============================================================================
-endif::[]
-
-
-
 == Table types
 
 But, for sure, the solution provided is a compromise. To fit the common needs

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

@@ -1,14 +1,17 @@
 ---
 title:                                  Roundtrip
 tagline:                                themes
-date:                                   2020-11-10 12:00:00
+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
+                                        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.
 
-tags:                                   [ Roundtrip, Introduction ]
-categories:                             [ Theme, Module ]
+tags:                                   [ Bootstrap, Themes ]
+categories:                             [ Introduction, Features ]
+
+scrollbar:                              false
 
 permalink:                              /pages/public/learn/roundtrip/themes/
 regenerate:                             false
@@ -33,7 +36,7 @@ resource_options:
 // Enable the Liquid Preprocessor
 :page-liquid:
 
-// Set page (local) attributes here
+// Set (local) page attributes here
 // -----------------------------------------------------------------------------
 // :page--attr:                         <attr-value>
 :images-dir:                            {imagesdir}/pages/roundtrip/100_present_images
@@ -46,15 +49,26 @@ resource_options:
 // -----------------------------------------------------------------------------
 {% include {{load_attributes}} scope="all" %}
 
-
 // Page content
 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-++++
-<!-- page_path:            {{page_path | debug}} -->
-<!-- site.source:          {{site.source | debug}} -->
-<!-- site.source.size:     {{site.source.size | debug}} -->
-++++
+// Include sub-documents
+// -----------------------------------------------------------------------------
+
+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 V4.
+
+Bootstrap is a HTML, CSS & JS Library that focuses on simplifying the
+development of modern web pages. The primary purpose to apply the framework
+to J1 is to provide a general standard colors, sizes, fonts and the overall
+layout of a J1-based site. Bootstrap provides basic style definitions for all
+common used HTML elements.
+
+This 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
@@ -62,6 +76,13 @@ versions of Bootstrap's CSS styles for a website.
 
 == Template themes
 
+Themes step in the framework to further adjust the appearance of a website
+based on the core CSS rules and definitions of Bootstrap. Themes does not
+change the functionality of the framwork, but modifies 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 additonal 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
 really create unique websites. Fundamental to do this is are CSS styles
 defined by Bootstrap.
@@ -70,7 +91,8 @@ Modifying the CSS styles of link:{bootstrap-home}[Bootstrap, {browser-window--ne
 is not rocket science. But, to be honest, some knowledge is needed to
 link:{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:{w3schools-css-tutorial}[design base, {browser-window--new}] of each and every website.
+link:{w3schools-css-tutorial}[design base, {browser-window--new}] of each and
+every website.
 
 Thanks to the people at link:{bootswatch-home}[Bootswatch, {browser-window--new}],
 a great set of already prepared Bootstrap stylesheets in various designs are
@@ -85,7 +107,6 @@ 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 template theme
 
 The base for designing pages using J1 Template is the theme Uno, a modern
@@ -106,49 +127,90 @@ not all of them for now.
 Simply select a theme from this menu, and a new BS-based stylesheet is
 automatically applied to your pages.
 
-
 == Code Highlighter Rouge
 
-lorem:sentences[5]
+_Rouge_ is a pure Ruby and themeable syntax highlighter. It can highlight
+100+ different languages, and output HTML or ANSI 256-color text. Find with
+this section all available themes and examples for several lanuguages how
+highlightning 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 J1 Template can be configured with the
+global template config file `~/_data/j1_config.yml`.
 
-lorem:sentences[3]
 
 === Apply a theme
 
-Make a selection of theme below to preview a theme.
+Make a selection of a theme below to preview.
 
 ++++
 <div class="btn-group">
-  <button class="btn btn-primary btn-raised btn-flex btn-lg dropdown-toggle" type="button" data-toggle="dropdown" data-target="#navbarDropdown" aria-haspopup="true" aria-expanded="false">
-  Select a theme<span class="caret"></span>
+  <!-- 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-raised btn-flex btn-lg dropdown-toggle" data-flip="false" type="button" data-toggle="dropdown" data-target="#navbarDropdown" aria-haspopup="true" aria-expanded="false">
+  Select Theme<span class="caret"></span>
   </button>
-  <div class="dropdown-menu">
-    <a class="dropdown-item" active="true" href="javascript:void(0)" onclick="j1.adapter.rouge.reaplyStyles('base16')"> <i class="mdi mdi-view-quilt mdi-18px mr-2" style="color: #9E9E9E"></i>base16</a>
-    <a class="dropdown-item" href="javascript:void(0)" onclick="j1.adapter.rouge.reaplyStyles('base16.dark')"> <i class="mdi mdi-view-quilt mdi-18px mr-2" style="color: #9E9E9E"></i>base16.dark</a>
-    <a class="dropdown-item" href="javascript:void(0)" onclick="j1.adapter.rouge.reaplyStyles('base16.light')"> <i class="mdi mdi-view-quilt mdi-18px mr-2" style="color: #9E9E9E"></i>base16.light</a>
-    <a class="dropdown-item" href="javascript:void(0)" onclick="j1.adapter.rouge.reaplyStyles('base16.monokai')"> <i class="mdi mdi-view-quilt mdi-18px mr-2" style="color: #9E9E9E"></i>base16.monokai</a>
-    <a class="dropdown-item" href="javascript:void(0)" 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>
-    <a class="dropdown-item" href="javascript:void(0)" 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>
-    <a class="dropdown-item" href="javascript:void(0)" onclick="j1.adapter.rouge.reaplyStyles('base16.solarized')"> <i class="mdi mdi-view-quilt mdi-18px mr-2" style="color: #9E9E9E"></i>base16.solarized</a>
-    <a class="dropdown-item" href="javascript:void(0)" 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>
-    <a class="dropdown-item" href="javascript:void(0)" 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>
-    <a class="dropdown-item" href="javascript:void(0)" onclick="j1.adapter.rouge.reaplyStyles('colorful')"> <i class="mdi mdi-view-quilt mdi-18px mr-2" style="color: #9E9E9E"></i>colorful</a>
-    <a class="dropdown-item" href="javascript:void(0)" onclick="j1.adapter.rouge.reaplyStyles('github')"> <i class="mdi mdi-view-quilt mdi-18px mr-2" style="color: #9E9E9E"></i>github</a>
-    <a class="dropdown-item" href="javascript:void(0)" onclick="j1.adapter.rouge.reaplyStyles('gruvbox')"> <i class="mdi mdi-view-quilt mdi-18px mr-2" style="color: #9E9E9E"></i>gruvbox</a>
-    <a class="dropdown-item" href="javascript:void(0)" onclick="j1.adapter.rouge.reaplyStyles('gruvbox.light')"> <i class="mdi mdi-view-quilt mdi-18px mr-2" style="color: #9E9E9E"></i>gruvbox.light</a>
-    <a class="dropdown-item" href="javascript:void(0)" onclick="j1.adapter.rouge.reaplyStyles('igorpro')"> <i class="mdi mdi-view-quilt mdi-18px mr-2" style="color: #9E9E9E"></i>igorpro</a>
-    <a class="dropdown-item" href="javascript:void(0)" onclick="j1.adapter.rouge.reaplyStyles('molokai')"> <i class="mdi mdi-view-quilt mdi-18px mr-2" style="color: #9E9E9E"></i>molokai</a>
-    <a class="dropdown-item" href="javascript:void(0)" onclick="j1.adapter.rouge.reaplyStyles('monokai')"> <i class="mdi mdi-view-quilt mdi-18px mr-2" style="color: #9E9E9E"></i>monokai</a>
-    <a class="dropdown-item" href="javascript:void(0)" onclick="j1.adapter.rouge.reaplyStyles('monokai.sublime')"> <i class="mdi mdi-view-quilt mdi-18px mr-2" style="color: #9E9E9E"></i>monokai.sublime</a>
-    <a class="dropdown-item" href="javascript:void(0)" onclick="j1.adapter.rouge.reaplyStyles('pastie')"> <i class="mdi mdi-view-quilt mdi-18px mr-2" style="color: #9E9E9E"></i>pastie</a>
-    <a class="dropdown-item" href="javascript:void(0)" onclick="j1.adapter.rouge.reaplyStyles('thankful_eyes')"> <i class="mdi mdi-view-quilt mdi-18px mr-2" style="color: #9E9E9E"></i>thankful_eyes</a>
-    <a class="dropdown-item" href="javascript:void(0)" onclick="j1.adapter.rouge.reaplyStyles('tulip')"> <i class="mdi mdi-view-quilt mdi-18px mr-2" style="color: #9E9E9E"></i>tulip</a>
-  </div>
+  <ul class="dropdown-menu scrollable-menu" role="menu">
+    <li><a class="dropdown-item" href="javascript:void(0)" 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" href="javascript:void(0)" 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" href="javascript:void(0)" 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" href="javascript:void(0)" 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" href="javascript:void(0)" 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" href="javascript:void(0)" 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" href="javascript:void(0)" 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" href="javascript:void(0)" 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" href="javascript:void(0)" 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" href="javascript:void(0)" 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" href="javascript:void(0)" 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" href="javascript:void(0)" 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" href="javascript:void(0)" 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" href="javascript:void(0)" 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" href="javascript:void(0)" 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" href="javascript:void(0)" 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" href="javascript:void(0)" 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" href="javascript:void(0)" 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" href="javascript:void(0)" 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" href="javascript:void(0)" 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>
+
+<style>
+/* jadams, 2021-02-16: unclear why global styles defined in CSS file */
+/* (bootsttrap.css) not applied. For that reason, given locally for now */
+.scrollable-menu {
+    height: auto;
+    max-height: 300px;
+    overflow-x: hidden;
+}
+
+.scrollable-menu::-webkit-scrollbar {
+    -webkit-appearance: none;
+    width: 12px;
+    background-color: #f5f5f5;
+}
+
+.scrollable-menu::-webkit-scrollbar-thumb {
+  border-radius: 10px;
+  -webkit-box-shadow: inset 0 0 6px rgba(255, 255, 255, 0.3);
+  background-color: #424242;
+}
+
+.scrollable-menu::-webkit-scrollbar-track {
+  -webkit-box-shadow: inset 0 0 6px rgba(0, 0, 0, 0.3);
+  border-radius: 0px;
+  background-color: #f5f5f5;
+}
+</style>
 ++++
 
-=== Liquid
+=== Highlight Liquid code
 
 {% raw %}
 [source, liquid]
@@ -162,7 +224,7 @@ Hello {{ 'now' | date: "%Y %h" }}
 ----
 {% endraw %}
 
-=== Javascript
+=== Highlight Javascript code
 
 [source, javascript]
 ----
@@ -181,7 +243,7 @@ function styleSheetLoaded(styleSheet) {
 }
 ----
 
-=== Ruby
+=== Highlight Ruby code
 
 [source, ruby]
 ----
@@ -207,16 +269,10 @@ end
 
 == Whats next
 
-You've explored some of the possibilities J1 offers for
-managing themes. But much, much more can the J1 do for your website.
-
-This was the last place to go for the roundtrip. More details of the most
-common elements of Bootstrap can be found on the previewer for a theme. Have
-a look at the link:{previewer-theme}[Theme previewer].
-
-To make things real for your new site, go for Web in a day. This tutorial
-guides you through all the steps on how to build a website - your site using
-Jekyll and the template system J1. It's really a pleasant journey to learn to
-create today's static webs.
+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 own theme, anayway.
 
-Start your journey from here: link:{kickstarter-web-in-a-day}[Web in a day].
+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 websites all about at link:{roundtrip-quicksearch}[Quicksearch].

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

@@ -0,0 +1,433 @@
+---
+title:                                  QuickSearch
+tagline:                                full index search based on lunr
+date:                                   2020-11-08 00:00:00
+description: >
+                                        QuickSearch is based on the search engine Lunr,
+                                        fully integrated with J1 Template. Lunr is designed
+                                        to be lightweight, yet full featured to provide a
+                                        great search experience. No need for complex external,
+                                        server-sideed search engines, or commercial services
+                                        on the Internet like Google.
+
+tags:                                   [ Roundtrip, QuickSearch ]
+categories:                             [ Search ]
+
+toc:                                    true
+scrollbar:                              false
+
+permalink:                              /pages/public/learn/roundtrip/quicksearch/
+regenerate:                             false
+
+resources:                              [ lunr, rouge, lightbox, clipboard ]
+resource_options:
+  - toccer:
+      collapseDepth:                    3
+  - attic:
+      padding_top:                      400
+      padding_bottom:                   50
+      opacity:                          0.5
+      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
+// -----------------------------------------------------------------------------
+
+
+QuickSearch is based on the search engine Lunr, fully integrated with J1
+Template. Lunr is designed to be lightweight, yet full featured to provide a
+great search experience. No need for complex external, server-sideed search
+engines, or commercial services on the Internet like Google.
+
+Searching a website using QuickSearch is different in compare to search engines
+like Google or Microsoft Bing. Those search platforms using complex algorithm
+to provide a simple interface to the public, but using a lot of artificial
+intelligence (AI) methods in behind to make senseful results out of a handfull
+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
+specific - if wanted. QuickSearch provides a 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 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 gets 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 that contains the
+text, the words (terms), that you want to be able to search on. A document is
+a data set (JSON object) with a set of fields that are processed to create the
+result list for a search.
+
+A document data set might look like this:
+
+[source, json, role="noclip"]
+----
+{
+  "title": "Web in a Day",
+  "tagline": "meet & greet jekyll",
+  "url": "/pages/public/learn/kickstarter/web_in_a_day/meet_and_greet/",
+  "date": "2018-05-01 00:00:00 +0000",
+  "tags": [
+    "Introduction"
+  ],
+  "categories": [
+    "Jekyll",
+    "Knowledge",
+    "Tutorial"
+  ],
+  "description": "Web in a Day is the first in a series of tutorials ..."
+}
+----
+
+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 size of 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 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 section
+<<Searching>>.
+
+=== Scoring
+
+The relevance (the `score`) of a document 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 technically 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 counts, and increase the score.
+
+Scoring information, generated by the BM25 algorithm, is added to the (local)
+search index. This 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 have 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 is used by all search engines; the same to J1 QuickSearch.
+You'll see for QuickSearch a similiar 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 itended to do: searching.
+
+.Input bar for a QuickSearch
+lightbox::quicksearch-input[ 800, {data-quicksearch-input} ]
+
+Search queries looks like simple text. But the search `engine` under the
+hood of QuickSearch transforms the given search string (text) always into a
+search query. This supports 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 be returned first.
+
+NOTE: In difference 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. To simplify an
+index, all words (terms) are transformed to lower case. As result, a word
+`Jekyll` is the same as `jekyll` from a search-engines prospective. Language
+variations of words like `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 name of the field, followed by a
+colon (`:`). The field _must_ be one of the fields defined when building
+the index. Unrecognised fields will lead to an error.
+
+Field-based searches can be combined with all other term modifiers and
+wildcards, as well as other terms. 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*
+----
+
+==== Available fields
+
+Beside 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 together 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 behaviour
+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 contains the word `jekyll`
+*AND* the word `collection`, mark both terms as required:
+
+[source, text]
+----
++jekyll +collection
+----
+
+
+== Whats next
+
+You've explored some of the possibilities J1 offers for websites. But much,
+much more can J1 do for your project. This was the last place to go for the
+roundtrip. More details of the most common elements of Bootstrap can be found
+on the previewer for a theme. Have a look at the
+link:{previewer-theme}[Theme previewer].
+
+To make things real for your new site, go for *Web in a day*. This tutorial
+guides you through all the steps on how to build a website. Your site using
+Jekyll and the template system J1. It's really a pleasant journey to learn what
+modern static webs can offer today.
+
+// Start your journey from here: link:{kickstarter-web-in-a-day}[Web in a day].