j1-template 2022.5.0.rc0 → 2022.5.0.rc3

data/lib/starter_web/pages/public/_jupyter/where_to_go.adoc

@@ -0,0 +1,270 @@
+---
+title:                                  Where to go
+tagline:                                presenting data analysis projects
+date:                                   2022-03-28 00:00:00
+description: >
+                                        The package nbinteract aims to enable authors and educators to create and
+                                        share interactive web pages easily. Interactive explanations of concepts are
+                                        useful for communicating and explaining tricky concepts.
+keywords: >
+                                        opensource, free, load, download, start, starter, example,
+                                        high, easy, use, secure, encrypt, standard, popular,
+                                        generate, create, learn, distribute, publish, deploy,
+                                        beginner, advanced, expert, student, learner, educator,
+                                        writer, reader, visitor,
+                                        framework, toolkit, integration, extension, module, api,
+                                        dynamic, static, generator, client, server, internet, local, localhost,
+                                        page, web, website, webdesign, material, design, responsive,
+                                        javascript, nodejs, ruby, windows, linux, osx, mac, os,
+                                        http, https, html, html5, css, scss, style,
+                                        browser, firefox, chrome, edge, opera, safari,
+                                        configuration, generator, navigation, menu, dropdown, fab, action, button,
+                                        application, interface, provider, api, repository,
+                                        cookie, language, translation, gdpr, dsgvo, privacy,
+                                        asciidoc, aciidoctor, bootstrap, jekyll, liquid,
+                                        hyvor, disqus, git, github, netlify, heroku, apple, microsoft,
+                                        provider, service, internet, support,
+                                        google, analytics, advertising, search, console, silverlight, score,
+                                        j1, nbi, j1-nbinteract, nbinteract, template, integration,
+                                        python, jupyter, notebook, textbook, api, app,
+                                        binder, binderhub, jupyterhub
+
+categories:                             [ Software, Python ]
+tags:                                   [ Binder, Jupyter, Notebooks ]
+
+scrollbar:                              false
+fab_menu_id:                            page_ctrl
+personalization:                        true
+
+permalink:                              /pages/public/jupyter/where-to-go/
+regenerate:                             false
+
+resources:                              [ animate, clipboard, rouge ]
+resource_options:
+  - attic:
+      opacity:                          0.3
+      slides:
+        - url:                          /assets/images/modules/attics/tldr-1920x800.jpg
+          alt:                          Photo by Alexander Redl on Unsplash
+          badge:
+            type:                       unsplash
+            author:                     Alexander Redl
+            href:                       https://unsplash.com/@alexanderredl
+
+#      slides:
+#        - url:                          /assets/images/modules/attics/yellow-cactus-1920x1280.jpg
+#          alt:                          Photo by Yellow Cactus on Unsplash
+#          badge:
+#            type:                       unsplash
+#            author:                     Yellow Cactus
+#            href:                       https://unsplash.com/@yellowcactus
+---
+
+// Page Initializer
+// =============================================================================
+// Enable the Liquid Preprocessor
+:page-liquid:
+
+// Set (local) page attributes here
+// -----------------------------------------------------------------------------
+// :page--attr:                         <attr-value>
+//
+// :starter-web-enabled:
+:binder-badges-enabled:                 false
+
+:binder-app-launch--lab:                https://mybinder.org/v2/gh/jekyll-one/j1-binder-repo/main
+:binder-app-launch--tree:               https://mybinder.org/v2/gh/jekyll-one/j1-binder-repo/main?urlpath=/tree
+
+:url-j1-notebook--times-tables:         /pages/public/jupyter/examples/distributed/j1-circular-times-table/
+:url-j1-notebook--climate-change:       /pages/public/jupyter/examples/localized/climate-change-forecast/
+:url-j1-altair-local--visualizations:   /pages/public/jupyter/examples/localized/j1-altair-visualizations/
+:url-j1-bokeh-local--visualizations:    /pages/public/jupyter/examples/localized/j1-bokeh-visualizations/
+:url-j1-nbi-module-docs--local:         /pages/public/jupyter/docs/j1-nbinteract-docs/
+:url-j1-nbi-apis-binder--local:         /pages/public/jupyter/docs/binderhub/
+
+//  Load Liquid procedures
+// -----------------------------------------------------------------------------
+{% capture load_attributes %}themes/{{site.template.name}}/procedures/global/attributes_loader.proc{%endcapture%}
+
+// Load page attributes
+// -----------------------------------------------------------------------------
+{% include {{load_attributes}} scope="global" %}
+
+
+// Page content
+// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+// image:/assets/images/badges/myBinder.png[Binder, link="https://mybinder.org/", {browser-window--new}]
+// image:/assets/images/badges/docsBinder.png[Binder, link="https://mybinder.readthedocs.io/en/latest/", {browser-window--new}]
+// See: https://towardsdatascience.com/ordinal-differential-equation-ode-in-python-8dc1de21323b
+
+ifeval::[{binder-badges-enabled} == true]
+image:https://mybinder.org/badge_logo.svg[Binder, link="{binder-app-launch--lab}", {browser-window--new}]
+endif::[]
+
+Jupyter Notebook (JN) is an open source web application based on the programming
+language _Python_ that allows data scientists to create and share documents
+that include explanatory text, live code, equations, and other multimedia
+resources like images or videos.
+
+To understand the technical terms of Jupyter (JN) better, below you find a
+brief description the base components.
+
+Jupyter Notebook App::
+The Jupyter Notebook *App* is a server-client application that allows editing
+and running notebook documents via a web browser. The Notebook App can be
+executed on a local desktop requiring no internet access or can be installed
+on a remote server and accessed through the internet in a cloud.
+
+Notebook documents::
+Notebook documents (or *notebooks* for short) are documents created by the
+Notebook App, and both computer code (e.g., Python) and rich text may contain
+elements (paragraphs, equations, figures, links, etc.). Notebook documents are
+human-readable documents, alongside code descriptions and results like figures,
+tables, etc.
+
+== The J1 Module NBI
+
+The _Python_ package `nbinteract` allows authors to convert Jupyter Notebooks
+into standalone HTML text pages: the *Textbooks*. The containing elements can
+include arbitrary Python code to generate output as well as Python libraries
+like _NumPy_ and _Pandas_ and libraries that create data visualisation like
+_Matplotlib_, _Plotly_,  _Altair_ or _Bokeh_.
+
+*Anyone* with a modern web browser can use the resulting web pages even if
+*no* Python or Jupyter installed on their computer. To make this possible,
+the J1 module *NBI* uses the freely available cloud service _Binder_.
+
+The built-in Starter Web of the template comes with a suitable NBI
+configuration and notebook documents for testing. You can find examples of
+pages that contain interactive textbooks under the menu `Lern` underneath
+the submenu `Experimental|Distributed Notebooks` or
+`Experimental|Localized Notebooks`.
+
+=== Notebooks vs. Textbooks
+
+Jupyter Notebook documents with the extension `.ipynb` are *data* files in
+the JSON format and can only be run using the *App* of Jupyter Notebook. On
+the other hand, Textbooks are HTML exports of Jupyter Notebooks with the
+extension `.html` to be viewed in a web browser without *no* the need using
+a locally installed Jupyter App to be displayed.
+
+For integrating textbooks in webpages, the notebooks with the extension
+`.ipynb` are to be *exported* to HTML (text) files using the Python program
+`nbinteract`. Textbooks that have already been exported can be found for the
+*Starter Web* in the folder `~/pages/public/jupyter/notebooks` in the
+subfolder `textbooks`.
+
+=== Distributed vs. Localized Textbooks
+
+The Python program `nbinteract` can export all types of containing elements of
+a Jupyter Notebook including embedded Javascript code that all
+modern web browsers can run. Important components of Jupyter notebooks are data
+visualizations to make sense of the data presented to the readers. Another
+important feature of Notebooks is *interactivity* which allows to change or
+select specific data elements to vary the output of data visualizations.
+
+The most flexible solution for interactive Notebooks are elements based on
+native Python code. To run the Python code as part of an HTML page, a
+computation engine is required for its execution. To run arbitrary Python code
+for generating output, the services at _Binder_ come into the game. The J1
+module *NBI* process Textbooks that contain Python code by connecting a running
+Jupyter Notebook instance (JN) in the cloud.
+
+Many modern visualization libraries used for Jupyter Notebooks are based on
+pure Javascript code that web browsers can process without the need of an
+additional (external) computation engine.
+
+Distributed Textbooks::
+Distributed Textbooks use embedded Python code that requires an additional
+computation engine. The module NBI of J1 Template connects via the _Binder_
+service for execution to process and display those notebooks. This remote
+execution allows *all* sorts of data visualization and interactivity Jupyter
+Notebooks can offer.
+
+Localized Textbooks::
+If the module NBI detects localized Textbooks, the module interface does
+*not* execute embedded Python code but displays those elements as *static*
+text sections. Data visualization elements are embedded as images or,
+depending on the visualization library used, as Javascript code that can
+be executed natively by a web browser. Available data visualization and
+interactivity depend on the visualization libraries used.
+
+
+== Where to go
+
+To get an impression of what exported Textbooks by the NBI module are and what
+can be achieved for static websites embedding and presenting Jupyter Notebooks
+the reader should first visit the already prepared Textbooks.
+
+Distributed Notebooks::
+Distributed Notebooks demonstrate the full power of the NBI module. An
+interesting example may be the interactive visualization of well-known
+*Time Tables*. This notebook is fun but shows some magic of mathematics.
+
+You find this fun notebook link:{url-j1-notebook--times-tables}[from here, {browser-window--new}].
+
+Localized Notebooks::
+An example of a simple localized notebook is shown by
+link:{url-j1-notebook--climate-change}[Climate Change Forecast, {browser-window--new}].
+The HTML export contains all text, code and graphical elements but is completely
+static, because no interactive elements are provided.
+
+// For a Starter Web, Altair and Bokeh examples are available only from
+// remote (jekyll.one)
+//
+ifdef::starter-web-enabled[]
+Localized Notebooks are in general limited in terms of interactivity and data
+visualization but can achieve *similar* results if a powerful Javascript-based
+visualization the library is used. An excellent example of such a powerful
+Javascript-based visualization library is demonstrated with the tour through
+the (interactive) graphic elements of
+link:{url-j1-bokeh-visualizations--remote}[Bokeh, {browser-window--new}].
+endif::[]
+
+ifndef::starter-web-enabled[]
+Localized Notebooks are in general limited in terms of interactivity and data
+visualization but can achieve *similar* results if a powerful Javascript-based
+visualization the library is used. An excellent example of such a powerful
+Javascript-based visualization library is demonstrated with the tour through
+the (interactive) graphic elements of
+link:{url-j1-bokeh-local--visualizations}[Bokeh, {browser-window--new}].
+endif::[]
+
+// For a Starter Web, NBI Docs and NBI APIs are available only from
+// remote (jekyll.one)
+//
+ifdef::starter-web-enabled[]
+NBI Documentation::
+Find more about how the NBI module works and what resources are used in
+this section. More about the module configuration and how it is used for static
+web pages can be found in this section:
+link:{url-j1-nbi-module-docs--remote}[NBI Docs, {browser-window--new}].
+endif::[]
+
+ifndef::starter-web-enabled[]
+NBI Documentation::
+Find more about how the NBI module works and what resources are used in
+this section. More about the module configuration and how it is used for static
+web pages can be found in this section:
+link:{url-j1-nbi-module-docs--local}[NBI Docs, {browser-window--new}].
+endif::[]
+
+ifdef::starter-web-enabled[]
+NBI APIs::
+More about the backgrounds of the NBI module and what are APIs are used
+under the hood can be found in this section. As the _Binder_ service is
+intensively used for distributed notebooks, more about these background service
+is provided at the
+link:{url-j1-nbi-apis--binder-remote}[Binder API, {browser-window--new}].
+endif::[]
+
+ifndef::starter-web-enabled[]
+NBI APIs::
+More about the backgrounds of the NBI module and what are APIs are used
+under the hood can be found in this section. As the _Binder_ service is
+intensively used for distributed notebooks, more about these background service
+is provided at the
+link:{url-j1-nbi-apis-binder--local}[Binder API, {browser-window--new}].
+endif::[]
+
+Having fun exploring the world of *Data Science* and *Analysis*.

data/lib/starter_web/pages/public/blog/navigator/archive/categoryview.html

@@ -20,7 +20,7 @@ analytics:                              true
 comments:                               false
 
 exclude_from_search:                    true
-regenerate:                             true                                    # needed to update pages
+regenerate:                             false                                   # set to 'true', if update posts is required
 
 resources:                              [ animate ]
 resource_options:

data/lib/starter_web/pages/public/blog/navigator/archive/dateview.html

@@ -20,7 +20,7 @@ advertising:                            false
 comments:                               false
 
 exclude_from_search:                    true
-regenerate:                             true                                    # needed to update pages
+regenerate:                             false                                   # set to 'true', if update posts is required
 
 resources:                              [ animate ]
 resource_options:

data/lib/starter_web/pages/public/blog/navigator/archive/tagview.html

@@ -21,7 +21,7 @@ advertising:                            false
 comments:                               false
 
 exclude_from_search:                    true
-regenerate:                             false                                   # page currently NOT used
+regenerate:                             false                                   # set to 'true', if update posts is required
 
 resources:                              [ animate ]
 resource_options:

data/lib/starter_web/pages/public/blog/navigator/archive.html

@@ -20,7 +20,7 @@ advertising:                            false
 comments:                               false
 
 exclude_from_search:                    true
-regenerate:                             true                                    # needed to update pages
+regenerate:                             false                                   # set to 'true', if update posts is required
 
 resources:                              [ animate ]
 resource_options:

data/lib/starter_web/pages/public/blog/navigator/index.html

@@ -17,13 +17,13 @@ sort:                                   date
 toc:                                    true
 fab_menu_id:                            default
 
-scrollDynamicPagesTopOnChange:          false                                   # do NOT scroll the page to top on content changes 
+scrollDynamicPagesTopOnChange:          false                                   # do NOT scroll the page to top on content changes
 
 analytics:                              true
 advertising:                            false
 comments:                               false
 
-regenerate:                             true                                    # needed to update the pagination pages
+regenerate:                             false                                   # set to 'true', if update posts is required
 
 resources:                              [ animate, scroller ]
 resource_options:

data/lib/starter_web/pages/public/features/general.adoc

@@ -41,6 +41,8 @@ robots:
   index:                                true
   follow:                               true
 
+fab_menu_id:                            page_ctrl
+
 permalink:                              /pages/public/features/general_features/
 regenerate:                             false
 
@@ -97,29 +99,37 @@ No license issues for private or professional use.
 J1 Template is based on these popular software platforms:
 
 mdi:language-ruby[24px, md-blue ml-3 mr-2]
-Ruby 2.7 +
+<<Ruby>> >= 2.7 +
 mdi:language-ruby[24px, md-blue ml-3 mr-2]
-Jekyll 4.2 +
+<<Jekyll>> 4.2 +
 mdi:nodejs[24px, md-blue ml-3 mr-2]
-NodeJS 12.x
+<<NodeJS>> 14.x
 
 All software-platforms are OpenSource, free to use and available on all
 common operating systems like Windows, Linux, and OSX.
 
-=== Ruby and Jekyll
+=== Ruby
+
+For the latest versions of J1 Template (>= *2022.5.0*), Ruby V3 is recommended.
+The latest Ruby versions offer much better run-time performance. Ruby 3 will
+be up to three times faster compared to Ruby 2.0. This will definively
+speed-up the development processes for your new website.
 
-The template system J1 is based on the Ruby language of version
-2.x. For sure, not the latest language version for Ruby but the
-supported platform for the latest Jekyll software.
+=== Jekyll
+
+The latest version of
+http://jekyllrb.com/news/2022/03/03/jekyll-4-2-2-released/[Jekyll v4.2.2 (March 2022), {browser-window--new}]
+including all fixes for version V4. The upcoming version *v4.3.0* will offer
+some new features and modernized functionality. If this version is released,
+all new features will be implemented in J1 as well.
 
 === NodeJS
 
-Websites created by Jekyll One are projects managed by NodeJS. The
-built-in script engine provided by the package manager `npm` of NodeJS
-simplifies the management of J1 projects a lot. Well-known commands
-typically used to manage software projects are at your fingertips.
-Easy to learn, easy to remember. Commands support creators to
-concentrate on the content.
+Websites created by Jekyll One are projects managed by NodeJS. The built-in
+script engine provided by the package manager `npm` of NodeJS simplifies the
+management of J1 projects a lot. Well-known commands typically used to manage
+software projects are at your fingertips. Easy to learn, easy to remember.
+Simple commands support creators to concentrate on the content.
 
 == Frameworks
 
@@ -128,26 +138,26 @@ extensions, and modules. All build-in frameworks are industry standard,
 well known, and accepted worldwide.
 
 mdi:bootstrap[24px, md-blue ml-3 mr-2]
-Bootstrap V5 +
+<<Bootstrap V5>> +
 mdi:language-html5[24px, md-blue ml-3 mr-2]
-HTML5, CSS and Javascript +
+<<Internet Standards Supported>> (HTML5, CSS and Javascript) +
 mdi:grass[24px, md-blue ml-3 mr-2]
-Icon Fonts +
+<<Icon Fonts>> +
 mdi:application-settings[24px, md-blue ml-3 mr-2]
-Fully configurable components +
+<<Fully Configurable>> +
 
 === Bootstrap V5
 
 For current webs, a must: responsiveness and modern design. Jekyll One is
-based on Bootstrap V5, the leading platform to create today's responsive webs.
+based on Bootstrap V5, the leading platform to create today's responsive
+webs.
 
-=== HTML5, CSS and Javascript
+=== Internet Standards Supported
 
-Professional websites on the internet define standards. All
-current sites support dynamic, fast loading, and some more features.
-For fastest loading, all HTML, CSS, and Javascript have been compressed
-automatically for production. Going further for dynamic, AJAX loading
-for J1 webs is supported as well.
+Professional websites on the internet define standards. All current sites
+support dynamic, fast loading, and some more features. For fastest loading,
+all HTML, CSS, and Javascript have been compressed automatically for production.
+Going further for dynamic, AJAX loading for J1 webs is supported as well.
 
 === Icon Fonts
 
@@ -164,12 +174,12 @@ J1 Template supports popular icons font sets out-of-the-box:
 All the icon sets are excellent in design and have a rich set of icons in
 various categories typically used for the Web.
 
-=== Fully configurable components
+=== Fully Configurable
 
 Software products of today are not easy to manage. To get the complexity
 out of your way, J1 is fully configurable. No need to dive in the deep.
 
-.Example of a text slider configuration (carousel.yml)
+.Example of a Text Slider configuration (`carousel.yml`)
 [source, yaml, role="noclip"]
 ----
 # --------------------------------------------------------------------------
@@ -183,9 +193,9 @@ out of your way, J1 is fully configurable. No need to dive in the deep.
 
     text:             [
                         "<big>Jekyll One Template</big>         </br> <i>Clean, ..</i>",
-                        "<big>Jekyll meets Bootstrap</big>      </br> <i>Best of OpenSource ..</i>",
+                        "<big>Jekyll meets Bootstrap</big>      </br> <i>Best of ..</i>",
                         "<big>J1 is Open Source</big>           </br> <i>No pain ..</i>",
-                        "<big>Explore this site</big>           </br> <i>Learn what's possible ..</i>",
+                        "<big>Explore this site</big>           </br> <i>Learn what's ..</i>",
                         "<big>Create modern static sites</big>  </br> <i>Secure, ..<i>"
                       ]
     options:
@@ -202,11 +212,14 @@ The Web is everywhere. J1 Template supports modern web browsers on all devices
 for best results on PCs, Tablets, and SmartPhones.
 
 mdi:devices[24px, md-blue ml-3 mr-2]
-Desktop and Mobile support +
+<<Desktop and Mobile support>> +
+mdi:near-me[24px, md-blue ml-3 mr-2]
+<<Desktop Web Navigation>> +
 mdi:near-me[24px, md-blue ml-3 mr-2]
-Mobile Web Navigation +
+<<Mobile Web Navigation>> +
 mdi:lighthouse[24px, md-blue ml-3 mr-2]
-Highest Google Lighthouse scores
+<<Best Google Lighthouse Scores>>
+
 
 === Desktop and Mobile support
 
@@ -225,6 +238,29 @@ As of 2021, more than 50 percent of the total web visits are currently mobile.
 For this reason, it is very important to provide good useability of your
 website for mobile devices.
 
+=== Desktop Web Navigation
+
+Then Naviagtion Modules of J1 Template provides multiple sub-modules. An very
+important one: the menu system. Based on a quite simple configuration, give
+your vistors easy access to all of your content pages on a mouse-click.
+
+.Example of a Menu Configuration (`navigator_menu.yml`)
+[source, yaml, role="noclip"]
+----
+# ------------------------------------------------------------------------------
+# Menu LEARN
+#
+- item:                                 Learn
+  sublevel:
+
+    - title:                            Where to go
+      href:                             /pages/public/learn/where_to_go/
+      icon:                             paw
+----
+
+.Desktop Web Navigation
+lightbox::images--desktop-navigation[ 800, {data-images--desktop-navigation} ]
+
 === Mobile Web Navigation
 
 Mobile devices are great for Apps designed for these platforms. Using a web
@@ -234,12 +270,17 @@ navigation systems that cover both worlds: desktops and mobiles.
 .Mobile Web Navigation
 lightbox::images--mobile-navigation[ 400, {data-images--mobile-navigation} ]
 
-=== Google Lighthouse scores
+IMPORTANT: Desktop and Mobile Navigation is using the **same** configuration
+data (`navigator_menu.yml`). The automatically generated menus for Desktop and
+Mobile Devices are displayed based on the size of the viewport.
+
+
+=== Best Google Lighthouse Scores
 
 Performance is a key factor for all users. To not get visitors lost, J1 webs
 are highly optimized. All Websites will achieve the  best Google Lighthouse
 scores for performance, accessibility, best practices, and SEO at the green
 level.
 
-.Google Lighthouse Scores
+.Google Lighthouse Scores (Starter Web at Github)
 lightbox::images--google-lighthouse[ 800, {data-images--google-lighthouse} ]