j1-template 2021.1.12 → 2021.1.17

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

@@ -15,6 +15,10 @@ sort:                                   date
 toc:                                    true
 fam_menu_id:                            open_toc
 
+analytics:                              true
+advertising:                            false
+comments:                               false
+
 regenerate:                             true                                    # needed to update pagination pages
 
 resources:                              []

data/lib/starter_web/pages/public/cookieConsent.adoc

@@ -12,6 +12,9 @@ tags:                                   [ Cookie, Consent ]
 scrollbar:                              false
 fam_menu_id:                            default
 
+advertising:                            false
+comments:                               false
+
 permalink:                              /pages/public/cookieConsent/
 regenerate:                             true
 

data/lib/starter_web/pages/public/learn/quickstart.adoc

@@ -0,0 +1,473 @@
+---
+title:                                  Quickstart
+tagline:                                an amazing site in 15 minutes
+date:                                   2021-03-07 00:00:00
+description: >
+                                        Welcome to the pages of J1 Template. If your here
+                                        first time, a good decision you get on that page first.
+                                        For sure, there is no better place to go.
+
+categories:                             [ Knowledge ]
+tags:                                   [ Quickstart ]
+
+comments:                               true
+fam_menu_id:                            page_ctrl_simple
+
+permalink:                              /pages/public/learn/quickstart/
+regenerate:                             false
+
+resources:                              [ clipboard, rouge ]
+resource_options:
+  - attic:
+      padding_top:                      400
+      padding_bottom:                   50
+      opacity:                          0.5
+      slides:
+        - url:                          /assets/images/modules/attics/matthew-dockery-1920x1280.jpg
+          alt:                          Photo by Matthew Dockery on Unsplash
+          badge:
+            type:                       unsplash
+            author:                     Matthew Dockery
+            href:                       https://unsplash.com/@matt_dockery
+---
+
+// 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="global" %}
+
+
+// Page content
+// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+// Include sub-documents
+// -----------------------------------------------------------------------------
+
+*All you need for your new amazing site.*
+
+Jekyll meets Bootstrap - and makes a lot of friends. J1 Template combines
+the best of OpenSource software for the Web and the Web site generator
+`Jekyll`. J1 is OpenSource, and so are the packaged modules. No pain for
+private or professional use. Check J1 Template today to learn what's possible
+if you go to the Jekyll Way.
+
+*Create powerful modern Static Webs: Secure, Flexible and Fast.*
+
+The template comes with a Web included, a skeleton for new website created
+with J1 Template. This Web is called the *Starter Web*, a general-purpose
+Website scaffold to be modified for your needs. The built-in Starter Web
+can be visited live at https://publish.jekyll.one/[J1 Publish, {browser-window--new}].
+This site show live pages deployed on the Internet on _Github_, _Netlify_
+and _Heroku_.
+
+*Have fun exploring what a modern static web, a Jekyll site can do*!
+
+== The Software needed
+
+J1 is supported on all current x64-based OS:
+
+* Windows 10, build >= 1903
+* Windows WSL 2
+* Linux, kernel version >= 4.15 (e.g. Ubuntu  18.x LTS)
+* OSX, version >= 10.10.5 (Yosemite)
+
+WARNING: Note that 32-bit versions (x32) are generally NOT supported for all
+platforms.
+
+=== Development languages and tools
+
+To run the Development System for J1 Template, the following languages and
+tools expected to be in place with your OS:
+
+* Ruby language, version >= 2.6
+* Javascript language (NodeJS), version >= 12.x
+
+NOTE: More current or older versions may work, but not tested.
+
+=== Software upgrades needed for all platforms
+
+If _Ruby_ and _NodeJS_ are in place, some packages are to be upgraded to
+more *current* versions. Install all packages system-wide with their
+respective product installation pathes.
+
+==== Upgrades needed for Ruby < v2.7
+
+Install latest bundler for Ruby:
+
+[source, sh]
+----
+gem install bundler --no-document
+----
+
+Install latest RubyGems for Ruby:
+
+[source, sh]
+----
+gem install rubygems-update --no-document
+update_rubygems --no-document
+gem update --system
+----
+
+==== Upgrades needed for NodeJS
+
+NodeJS comes with NPM pre-installed. The native CLI for the NodeJS package
+management is `npm`. Besides `npm` there's another quite handy CLI for NPM
+available: *Yarn*.
+
+The CLI `yarn` is developed at Facebook and can be used as a replacement
+for `npm`. From a top-level perspective, both package management clients behave
+pretty much the same. The syntax `yarn` uses is shorter in writing, making
+the command-line look a bit more natural. Therefore, we prefer to use `yarn`.
+
+NOTE: Yarn adds some additional features to the NodeJS package management
+implemented for the needs at Facebook. Regarding the J1 development system,
+those add-ons are neither needed nor used.
+
+Install latest NPM and Yarn packages for NodeJS:
+
+[source, sh]
+----
+npm install -g npm@latest
+npm install -g yarn@latest
+----
+
+== Create a Starter Web
+
+Running the J1 template project is very simple:
+
+* Download the J1 Gem
+* Create a J1 web project
+* Setup the runtime environment for your project
+* Run and develop the buildin starter web
+
+Find all details on this with the sections below.
+
+=== Download the J1 Gem
+
+The Gem for J1 Template (runtime system) is published on _RubyGems_.
+You can get it by installing the package using the Ruby `gem` command or
+by downloading it from link:{url-j1--download}[RubyGems, {browser-window--new}].
+
+.Userized installation
+[source, sh]
+----
+gem install j1-template --remote --user-install --no-document
+----
+
+.System-wide installation
+[source, sh]
+----
+gem install j1-template --remote --no-document
+----
+
+NOTE: To *not* pollute the system-wide Gem folder of a Ruby-installation by
+*user* and *project* specific Gems, it is recommend to install *J1* userized.
+
+J1 is a so-called *gem-based* template, a *Ruby Gem* managed by the (gem)
+internal executeable (command) *j1*. Check your version installed or some
+usage information by running:
+
+.Version information
+[source, sh]
+----
+j1 --version
+----
+
+.Usage information
+[source, sh]
+----
+j1 --help
+----
+
+=== Setup a project
+
+Is the Ruby Gem *J1* installed, a project, a website needs to be generated
+by J1's build-in executable *j1*. The command *j1* is used to manage *base*
+project tasks like generating a *project*.
+
+If a *project* (a website) is generated, all development tasks are managed
+by *NPM scripts* (NodeJS). Development *tasks* are defined as *scripts*
+with the project config file `package.json`.
+
+First, create a projects folder for all website to be generated J1. For the
+following examples, a project is generated on _Windows_ using *C:\Temp*
+for the project's folder.
+
+.Usage information
+[source, sh]
+----
+j1 generate starter
+----
+
+.Output
+----
+Running bundle install in c:/Temp/starter ...
+Install bundle in USER gem folder ~/.gem ...
+
+    Bundler: Fetching gem metadata from https://rubygems.org/ ...
+    Bundler: Fetching gem metadata from https://rubygems.org/.
+    Bundler: Resolving dependencies...
+    Bundler: Using rake 12.3.3
+    Bundler: Using public_suffix 4.0.6
+    ...
+    Bundler: Using wdm 0.1.1
+    Bundler: Bundle complete! 34 Gemfile dependencies, 86 gems now installed.
+    Bundler: Bundled gems are installed into `../../Users/jadams/.gem`
+
+Install patches in USER gem folder ~/.gem ...
+Install patches on path C:/Users/jadams/.gem/ruby/2.6.0 ...
+Generated Jekyll site force installed in folder c:/Temp/starter
+----
+
+=== Setup the runtime
+
+The command *j1 generate* creates a project folder with the name given. In
+this example, the project is *starter*. Change to this folder
+
+[source, sh]
+----
+cd C:\Temp\starter
+----
+
+A J1 project consists in several files and folders. Find a typical structure
+as below:
+
+.J1 Project structure
+----
+  ├──── .
+  │     └─ _data  <1>
+  │     └─ _includes <2>
+  │     └─ _plugins <3>
+  │     └─ assets <4>
+  │     └─ collections <5>
+  │     └─ pages <6>
+  │     └─ utilsrv
+  ├──── _config.yml <7>
+  ├──── config.ru
+  ├──── dot.gitattributes
+  ├──── dot.gitignore
+  ├──── dot.nojekyll
+  ├──── favicon.ico
+  ├──── Gemfile <8>
+  ├──── index.html <9>
+  └──── package.json <10>
+----
+<1>   Configuration data for the website
+<2>   Asciidoc (global) includes
+<3>   Build-in (Ruby) plugins
+<4>   Assets for the web
+<5>   Folder that contains all blog posts
+<6>   Folder that contains all (article) pages
+<7>   Central (Jekyll) site configuration
+<8>   Ruby Gemfile
+<9>   Homepage for the web
+<10>  (NPM) Project file
+
+The first step, done only once, is to initialize a project. What means to
+download and install all resources for your new website followed by an
+initial creation process for the new site. Initializing a project is managed
+by the (NPM) *task* `setup`. A bunch of sub-tasks get fired, all of them
+managed by NPM.
+
+Let's start ...
+
+[source, sh]
+----
+yarn setup
+----
+
+Because a lot of sub-tasks getting started for a (first) `setup`, see below
+the output as a summary:
+
+----
+Setup project for first use ..
+Bootstrap base modules ..
+done.
+Configure environment ..
+done.
+Create project folders ..
+Create log folder ..
+Create archived log folder ..
+Create etc folder ..
+done.
+Bootstrap project modules ..
+Bootstrap utility server modules ..
+done.
+Detect OS ..
+OS detected: Windows_NT
+Build site incremental ..
+Configuration file: c:/Temp/starter/_config.yml
+            Source: c:/Temp/starter
+       Destination: c:/Temp/starter/_site
+ Incremental build: enabled
+      Generating...
+    J1 QuickSearch: creating search index ...
+    J1 QuickSearch: finished, index ready.
+      J1 Paginator: autopages, disabled|not configured
+      J1 Paginator: pagination enabled, start processing ...
+      J1 Paginator: finished, processed 5 pagination page|s
+                    done in 25.687 seconds.
+ Auto-regeneration: disabled. Use --watch to enable.
+.. build finished.
+To open the site, run: yarn site
+
+Done in 88.03s.
+----
+
+The `setup` process will take a while - typically some minutes for the
+*first* run (depending on the performances of your Internet connection
+and your workstation). A bunch of NPM modules and Ruby Gems are downloaded
+and linked for the components part of the project. See `setup` as an extended
+*install* and *build* process to manage an initial setup for your new
+website.
+
+=== Run and develop a starter web
+
+Running the Starter Web for development is done like so:
+
+[source, sh]
+----
+yarn site
+----
+
+The task `site` does a lot for you; whatever is necessary for a full-stack
+Web development. The task will put in place all needed CSS and JS components,
+build the Web content.
+
+----
+Startup the site ..
+Configuration file: c:/Temp/starter/_config.yml
+            Source: c:/Temp/starter
+       Destination: c:/Temp/starter/_site
+ Incremental build: enabled
+      Generating...
+    J1 QuickSearch: creating search index ...
+    J1 QuickSearch: finished, index ready.
+      J1 Paginator: autopages, disabled|not configured
+      J1 Paginator: pagination enabled, start processing ...
+      J1 Paginator: finished, processed 5 pagination page|s
+                    done in 7.1 seconds.
+ Auto-regeneration: enabled for '.'
+LiveReload address: http://localhost:40001
+    Server address: http://localhost:40000/
+  Server running... press ctrl-c to stop.
+        LiveReload: Browser connected
+----
+
+Finally, the starter web get openend in your *default* browser.
+
+Go, go, go ..
+
+=== Rebuild a site
+
+A project runs Jekyll in *incremental* mode with *auto-regeneration* enabled.
+All changes made to the pages (posts) of your web at runtime are automatically
+detected and the affected are rebuild and (live) reloaded.
+
+To rebuild the *site* from the scratch, a web can be completely rebuild by
+running the task `rebuild`:
+
+[source, sh]
+----
+yarn rebuild
+----
+
+----
+Rebuild site incremental ..
+Clean up site files ..
+Configuration file: c:/Temp/starter/_config.yml
+           Cleaner: Removing _site...
+           Cleaner: Removing ./.jekyll-metadata...
+           Cleaner: Removing ./.jekyll-cache...
+           Cleaner: Nothing to do for .sass-cache.
+Configuration file: c:/Temp/starter/_config.yml
+            Source: c:/Temp/starter
+       Destination: c:/Temp/starter/_site
+ Incremental build: enabled
+      Generating...
+    J1 QuickSearch: creating search index ...
+    J1 QuickSearch: finished, index ready.
+      J1 Paginator: autopages, disabled|not configured
+      J1 Paginator: pagination enabled, start processing ...
+      J1 Paginator: finished, processed 5 pagination page|s
+                    done in 25.221 seconds.
+ Auto-regeneration: disabled. Use --watch to enable.
+.. rebuild finished.
+To open the site, run: yarn site.
+Done in 34.88s.
+----
+
+If the site rebuild, re-run:
+
+[source, sh]
+----
+yarn site
+----
+
+and continue developing your website.
+
+=== Reset a project
+
+To start from the beginning, you can reset the runtime system to the
+factory state. The top-level task `reset` does the resetting work for you
+and cleans up each and everything except the NPM modules folder `node_modules`
+stored in the project root.
+
+[source, sh]
+----
+yarn reset
+----
+
+The cleanup runs some tasks for the root folder and in parallel sub-tasks
+using Jekyll for the Web:
+
+----
+Reset project to factory state ..
+Clean up base modules ..
+Clean up site files ..
+Configuration file: c:/Temp/starter/_config.yml
+           Cleaner: Removing _site...
+           Cleaner: Removing ./.jekyll-metadata...
+           Cleaner: Removing ./.jekyll-cache...
+           Cleaner: Nothing to do for .sass-cache.
+Clean up projects files ..
+Remove bundle config folder ..
+Remove log folder ..
+Remove etc folder ..
+Remove various log files ..
+Remove lock files ..
+Clean up utility server ..
+done.
+Done in 10.23s.
+----
+
+To reset the project *completely*, delete the folder `node_modules` manually
+and start from the beginning by running the `setup` task again:
+
+[source, sh]
+----
+yarn setup
+----
+
+If the project is newly setup, re-run:
+
+[source, sh]
+----
+yarn site
+----
+
+and continue developing your website.
+
+Happy Jekylling!