j1-template 2022.6.3 → 2023.0.0

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

@@ -1,465 +0,0 @@
----
-title:                                  Quickstart
-tagline:                                Amazing Site In Minutes
-date:                                   2021-03-07 00:00:00
-description: >
-                                        The template comes with a Web included, a skeleton for
-                                        a new website created with J1 Template. This Web is called
-                                        the "Starter web", a general-purpose scaffold to be modified
-                                        for your needs.
-
-categories:                             [ Knowledge ]
-tags:                                   [ Template, Quickstart ]
-
-image:
-  path:                                 /assets/images/modules/attics/matthew-dockery-1920x1280.jpg
-  width:                                1920
-  height:                               1280
-  alt:                                  Photo by Matthew Dockery on Unsplash
-
-comments:                               false
-
-permalink:                              /pages/public/learn/quickstart/
-regenerate:                             false
-
-resources:                              [ animate, clipboard, rouge ]
-resource_options:
-  - attic:
-      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 (if any)
-// -----------------------------------------------------------------------------
-The template comes with a Web included, a skeleton for new a website created
-using J1 Template. This Web is called the *Starter web*, a general-purpose
-scaffold to be modified for your needs. The built-in Starter web is available
-live at link:{url-j1--home}/[J1 Home, {browser-window--new}] under the menu
-*Live*. These sites show live pages deployed on the Internet on _Github_ and
-_Netlify_.
-
-A *Starter web* is created in minutes. This section
-
-== 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 needs to be upgraded to
-more *current* versions. Install all packages system-wide with their
-respective product installation paths.
-
-==== 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 websites 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 gets 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 Lunr: creating search index ...
-           J1 Lunr: 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 your Internet connection bandwidth and the workstation
-performance. Many 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 your new website's initial setup.
-
-=== 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 Lunr: creating search index ...
-           J1 Lunr: 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 your web's pages and posts at runtime are automatically
-detected, and the affected pages are rebuilt  and automatically reloaded with
-your browser.
-
-For rebuilding a *site* from scratch, a web can be completely rebuilt 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 Lunr: creating search index ...
-           J1 Lunr: 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!