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: [ J1
, Template, 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 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 {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:Tempstarter
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 fileThe 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: 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!
-