j1-template 2020.0.20 → 2021.0.0

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

@@ -1,16 +1,19 @@
 ---
 title:                                  Roundtrip
 tagline:                                themes
-description:                            J1 Template Roundtrip - Template Themes
+date:                                   2020-11-10 12: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.
 
-tags:                                   [ Page, Roundtrip ]
-index:                                  [ Template, Roundtrip, Bootstrap, Themes ]
-categories:                             [ pages ]
+tags:                                   [ Roundtrip, Introduction ]
+categories:                             [ Theme, Module ]
 
 permalink:                              /pages/public/learn/roundtrip/themes/
 regenerate:                             false
 
-resources:                              []
+resources:                              [ rouge, clipboard ]
 resource_options:
   - attic:
       padding_top:                      400
@@ -25,84 +28,70 @@ resource_options:
             href:                       https://unsplash.com/@clemono
 ---
 
+// Page Initializer
+// =============================================================================
 // Enable the Liquid Preprocessor
-// -----------------------------------------------------------------------------
 :page-liquid:
 
-// Set other global page attributes here
+// Set page (local) attributes here
 // -----------------------------------------------------------------------------
-//:my-asciidoc-attribute:
+// :page--attr:                         <attr-value>
+:images-dir:                            {imagesdir}/pages/roundtrip/100_present_images
 
 //  Load Liquid procedures
 // -----------------------------------------------------------------------------
-{% capture set_env_entry_document %}themes/{{site.template.name}}/procedures/global/set_env_entry_document.proc{%endcapture%}
-
-
-// Initialize entry document environmental attributes
-// -----------------------------------------------------------------------------
-{% include {{set_env_entry_document}} %}
-
-// Load tag, url and data attributes
-// -----------------------------------------------------------------------------
-include::{includedir}/attributes.asciidoc[tag=tags]
-include::{includedir}/attributes.asciidoc[tag=urls]
-include::{includedir}/attributes.asciidoc[tag=data]
+{% capture load_attributes %}themes/{{site.template.name}}/procedures/global/attributes_loader.proc{%endcapture%}
 
-// Set local page attributes
+// Load page attributes
 // -----------------------------------------------------------------------------
-// :images-dir:                         {imagesdir}/path/to/page/images
+{% include {{load_attributes}} scope="all" %}
 
 
 // Page content
 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-// Include sub-documents
-// -----------------------------------------------------------------------------
-
 ++++
 <!-- page_path:            {{page_path | debug}} -->
 <!-- site.source:          {{site.source | debug}} -->
 <!-- site.source.size:     {{site.source.size | debug}} -->
 ++++
 
-The themes feature for J1 Template is in a alpha status of the template
+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.
 
-== Themes
+== Template themes
 
 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.
 
-Modifying the CSS styles of link:{bootstrap-home}[Bootstrap, {window}] is not
-rocket science. But, to be honest, some knowledge is needed of
+Modifying the CSS styles of link:{bootstrap-home}[Bootstrap, {browser-window--new}]
+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, {window}] of each and every website.
-Independendly from using Bootstrap or any other CSS framwork.
+link:{w3schools-css-tutorial}[design base, {browser-window--new}] of each and every website.
 
-Thanks to the people at link:{bootswatch-home}[Bootswatch, {window}], a great
-set of already prepared Bootstrap stylesheets in various designs are available
-at their website. No need to start from the scratch, to 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 is at least a good
-base for your modifications: your unique design.
+Thanks to the people at link:{bootswatch-home}[Bootswatch, {browser-window--new}],
+a great set of already prepared Bootstrap stylesheets in various designs are
+available at their website. No need to start from scratch, to 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.
 
-Beside the bunch of different stylesheets at Bootswatch, an
-link:{bootswatch-api}[integration API, {window}] is available that helps a lot
-to integrate available designs into a existing site. This API is the base to
-integrate Bootswatch stylesheets into J1 Template for easy use.
+Besides the bunch of different stylesheets at Bootswatch, a
+link:{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.
 
-Thanks again the people at Bootswatch for this great work.
 
-
-== Apply a theme
+=== Apply a template theme
 
 The base for designing pages using J1 Template is the theme Uno, a modern
 light theme that can be 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
-good base, a starting point. Combining Uno and a different theme may a fast
+a good base, a starting point. Combining Uno and a different theme may a fast
 solution for your site!?
 
 You can find all available themes, all stylesheets to be applied to your pages
@@ -110,18 +99,115 @@ from the menu Themes. You're invited to check how a page is changing for
 their design if other stylesheets, other ideas of web design is used.
 
 NOTE: Changing BS-based styles is one thing, changing from one theme to the
-next at runtime a bit more challanging. For the alpha version of J1 Template,
+next at runtime a bit more challenging. For the first version of J1 Template,
 many styles are automatically changed for J1 specific components as well, but
 not all of them for now.
 
-Simply select a theme from this menu and a new BS-based stylesheet is
+Simply select a theme from this menu, and a new BS-based stylesheet is
 automatically applied to your pages.
 
-Have fun!
+
+== Code Highlighter Rouge
+
+lorem:sentences[5]
+
+lorem:sentences[3]
+
+=== Apply a theme
+
+Make a selection of theme below to preview a theme.
+
+++++
+<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>
+  </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>
+</div>
+<div id="selected" class="mt-1 mb-3"></div>
+++++
+
+=== Liquid
+
+{% raw %}
+[source, liquid]
+----
+Hello {{ 'now' | date: "%Y %h" }}
+
+{% comment %} if item.quantity is 4... {% endcomment %}
+{% for i in (1..item.quantity) %}
+  {{ i }}
+{% endfor %}
+----
+{% endraw %}
+
+=== Javascript
+
+[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;;
+    }
+  }
+}
+----
+
+=== Ruby
+
+[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
+
 
 == Whats next
 
-Hopefully you've enjoyed exploring some of the possibilities J1 offers for
+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
@@ -129,8 +215,8 @@ 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 how to build a website - your site using
-Jekyll  nd the template system J1. It's really a nice journey to explore
-and  learn creating a static web.
+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.
 
 Start your journey from here: link:{kickstarter-web-in-a-day}[Web in a day].

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

@@ -0,0 +1,236 @@
+---
+title:                                  Lunr
+tagline:                                full index search
+date:                                   2020-11-08 12:00:00
+description: >
+                                        Learn the search query language used by Lunr. The DSL used by Lunr
+                                        is quite close to Solr to support a powerful search experience
+                                        for better result. Using search expressions with wildcards, conditions
+                                        like and|or and fuzzy search algorithms are supported.
+
+tags:                                   [ Roundtrip, Introduction ]
+categories:                             [ Search ]
+
+toc:                                    true
+scrollbar:                              false
+
+permalink:                              /pages/public/learn/roundtrip/lunr/
+regenerate:                             true
+
+resources:                              [ lunr, rouge ]
+resource_options:
+  - 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 page (local) 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
+// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+== Searching
+
+After you have built an index of your documents, the next step is to
+perform a search.
+
+The simplest way to start is to pass the text on which you want to
+search into the search method:
+
+[source, javascript]
+----
+idx.search('foo')
+----
+
+The above will return details of all documents that match the term
+“foo”. Although it looks like a string, the `search` method parses the
+string into a search query. This supports special syntax for defining
+more complex queries.
+
+Searches for multiple terms 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 with OR.
+
+[source, javascript]
+----
+idx.search('foo bar')
+----
+
+The above example will match documents that contain either “foo” or
+“bar”. Documents that contain _both_ will score more highly and will be
+returned first.
+
+=== Scoring
+
+The score (also known as relevance) of a document is calculated by the
+https://en.wikipedia.org/wiki/Okapi_BM25[BM25] algorithm, along with
+other factors such as link:#Boosts[boosts]. You don’t need to worry too
+much about the details of how BM25 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.
+
+For example, let’s say you’re indexing a collection of documents about
+JavaScript testing libraries. The terms “JavaScript”, “library”, and
+“test” may occur very frequently throughout the entire collection, so
+finding a document that mentions one of these terms isn’t very
+significant. However, if you’re searching for “integration test”, only
+three documents in the collection have the term “integration” in them,
+and _one_ of them mentions “integration” many times, that will bring the
+score for that one document higher up.
+
+=== Wildcards
+
+Lunr 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 “foo”:
+
+[source, javascript]
+----
+idx.search('foo*')
+----
+
+This will match all documents that end with ‘oo’:
+
+[source, javascript]
+----
+idx.search('*oo')
+----
+
+Leading wildcards, as in the above example, should be used sparingly.
+They can have a negative impact on the performance of a search,
+especially in large indexes.
+
+Finally, a wildcard can be in the middle of a term. The following will
+match any documents that contain a term that begins with “f” and ends in
+“o”:
+
+[source, javascript]
+----
+idx.search('f*o')
+----
+
+It is also worth noting that, when a search term contains a wildcard, no
+stemming is performed on the search term.
+
+=== Fields
+
+By default, Lunr will search all fields in a document for the query
+term, and it is possible to restrict a term to a specific field. The
+following example searches for the term “foo” in the field title:
+
+[source, javascript]
+----
+idx.search('title:foo')
+----
+
+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 “foo” in the title or with “bar” in any field the
+following query can be used:
+
+[source, javascript]
+----
+idx.search('title:foo* bar')
+----
+
+=== 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 “foo bar” will match documents that
+contain “foo” or contain “bar” 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
+should be prefixed with a plus (`+`) and to indicate that a term must be
+absent the term should be prefixed with a minus (`-`). Without either
+prefix the term’s presence in matching documents is optional.
+
+The below example searches for documents that must contain “foo”, might
+contain “bar” and must not contain “baz”:
+
+[source, javascript]
+----
+idx.search("+foo bar -baz")
+----
+
+To simulate a logical AND search of “foo AND bar” mark both terms as
+required:
+
+[source, javascript]
+----
+idx.search("+foo +bar")
+----