Welcome to the third section of Web in a Day. You’ve survived all the technical stuff and the preparations needed for setting up a development environment.
You may read a lot of marketing stuff around static websites, the tools, and benefits. The following characterizes a static web generated by a Site Generator:
In opposition to CMS systems that use a database to load content dynamically, a static site will directly load the server’s HTML files.
Using a static site generator like Jekyll, the engine separates the content from the Template. Using a static site generator, you will only need to modify it once, and the generator will apply it to all your pages.
The Template System J1 uses Jekyll under the hood and provides a lot of high-level functions to control the web creation process:
J1 is highly customizable. Based on a pure configuration, J1 can create a full-featured website. The template system creates static web pages using Jekyll as the base HTML code generator.
For J1, a rich set of modules are already included. The modules support usual use cases of a website like a flexible navigation system, a local search, lightboxes to present pictures and videos, helpers for smooth scrolling, or to automatically create TOCs (table of contents) for a page.
Are all the statements true? Are static websites easy to create, fast and secure? Is it easy to manage such a web?
Many open question for now!
Let’s start by creating a static web and verify if the promises could be satisfied and what that means for your First awesome Web.
A first awesome Web
To remind you of Ruby GEMs, the module concept of Ruby is different in comparison to other programming languages. For Ruby, a GEM can contain command-line interfaces (CLI, commands) to access higher-level functionality.
The J1 Template GEM contains such a CLI:
j1. The command is used to create (generate) a web project. Generate such a project is the very first step to manage a new website for the J1 Template System.
Creating a J1 project
First, a project folder is needed. J1 can generate a project elsewhere, but I recommend creating a central Web folder to place (all) websites.
Open a command shell (cmd.exe) and run:
md C:\J1Webs && cd C:\J1Webs
Next, a project is to be created for the new website using the CLI j1. It is expected that your current folder (in that shell) is C:\J1Webs.
j1 generate starter
This will take a while for the first J1 project because additional Ruby GEMs are to be downloaded. Because some of the GEMs are platform-specific, the DevKit (installed at the time the Ruby language was installed) is called to compile specific components for the Windows platform.
Running bundle install in C:/J1Webs/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: Fetching rake 12.3.3 Bundler: Installing rake 12.3.3 ... Bundler: Fetching wdm 0.1.1 Bundler: Installing wdm 0.1.1 with native extensions Bundler: Bundle complete! 33 Gemfile dependencies, 85 gems now installed. Bundler: Bundled gems are installed into `../../Users/<user_name>/.gem` Install patches in USER gem folder ~/.gem ... (1) Install patches on path C:/Users/<user_name>/.gem/ruby/2.7.0 ... (2) Generated Jekyll site installed in folder C:/J1Webs/starter (3)
|1||For J1 projects, some Ruby modules are patched to make them usable on Windows|
|2||Ruby GEM folder for userized modules|
|3||J1 Project for the generated website|
|Some Ruby GEMs, eventmachine, and execJS, for example, have to be patched on Windows respective for the newer versions of Ruby. As mentioned earlier, a massive number of libraries are provided by private persons but not continuously updated to make them usable for the recent versions of Ruby’s development system. The affected GEMs are currently not updated for the newer versions of Ruby of v27 or v26. For J1, the needed (patched) components were added to the J1 Template system and applied when a project is generated.|
|Patched versions of the Ruby GEMs eventmachine and execJS are available only using J1. The original versions cannot be used and will make the generator engine Jekyll fail.|
If the generation process has finished, this results in a project scaffold. To make this scaffold a usable J1 project, this data structure is to be initialized first.
Setting up the project
The next step, done only once, is to initialize the project to download and install all resources for your new website, followed by a first creation process for the new website. Initializing a project is managed by the task
setup run by the NodeJS package manager.
A bunch of sub-tasks gets fired. All of them are controlled package manager yarn for you. The J1 project is generated in folder C:\J1Webs\starter. Change to that folder and set up the project using the command
cd C:\J1Webs\starter && 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:/J1Webs/starter/_config.yml Source: C:/J1Webs/starter Destination: C:/J1Webs/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 1 pagination page|s done in 37.609 seconds. Auto-regeneration: disabled. Use --watch to enable. .. build finished. To open the site, run: yarn site Done in 94.94s.
setup takes a while. Typically some minutes for the first run (depending on the performances of your Internet connection and your Desktop PC). A bunch of NPM modules and Ruby Gems gets downloaded, installed, and linked for the project. See the setup task as an extended install and build process to make your new website ready to use.
Run a site
As discussed, all project-related tasks are managed by the package manager for NodeJS — in this case, yarn. The task to run a website is
site and can be issued like so:
The following messages appear in your command shell:
yarn run v1.22.10 $ run-p -s site:* Startup the site .. UTILSRV disabled. Not started. Configuration file: C:/J1Webs/starter/_config.yml (1) Source: C:/J1Webs/starter (2) Destination: C:/J1Webs/starter/_site (3) Incremental build: enabled Generating... J1 QuickSearch: recreate index disabled. J1 Paginator: autopages, disabled|not configured J1 Paginator: pagination enabled, start processing ... J1 Paginator: finished, processed 1 pagination page|s done in 9.618 seconds. Auto-regeneration: enabled for '.' LiveReload address: http://localhost:40001 (5) Server address: http://localhost:40000/ (4) Server running... press ctrl-c to stop. LiveReload: Browser connected (6)
|1||The configuration file for the builder engine Jekyll|
|2||The project folder|
|3||The WebRoot folder for your website creaated|
|4||The URL to access the web|
|5||A LiveReloader is started and listens on port 40001|
|6||A webbrowser has been started automatically and the LiveReloader is connected|
Your default web browser is automatically started, and the website gets loaded.
That should look like this way:
Now, after so much theory and technical stuff, you should explore your new website. The base navigation provided is the Navigation bar (1). and the QuickLink bar (2).
Give your new starter web a try. Take some time to inspect your site, surf on some pages, and come back to the next section: Check your project in a code editor.
Have a pleasant walk-around!
|Some pages of the Starter Web are very the same as used for the J1’s homepage. All pages of the roundtrip are fully included with the example website to help write more complex pages.|
Check your project in a code editor
To manage a J1 project, the most critical tool to do this is the editor you’ve installed. You can use a good code editor for a so-called Integrated Development Environment (IDE). All functions, all features, are included or can be easily added by extensions.
J1 Template comes with no Graphical User Interface (GUI) included. The functionality of a GUI is substituted by the power of the IDE, your code editor. For users not experienced in using code editors have to exercise a bit how to use an editor. You’ll learn how helpful an IDE is and (hopefully) understand why programmers prefer an IDE over any GUI-driven tool to work on code-based projects.
|For examples related to the usage of a code editor, Atom is used. VS Code supports you in the same way.|
The base creating websites using J1 are:
code, source data of your content
data, control information for the builder engine Jekyll how to transform source data into HTML pages
Both are written as simple text files, the reason why a code editor is a good choice. Two types of files are the most important in the beginning to know:
for the code, the source data of your content, the markup language Asciidoc is used
for the data, control information for the builder engine, the markup language YAML is used
In computer text processing, a markup language is a system for annotating a (text-)document by control information: the markups.
Asciidoc is used to annotate the sources of your web content. The Asciido markups indicate, for example, what text in a page should be displayed in boldface, what text should be headlines, where to place images, or what should be transformed in tables or lists.
YAML is used to indicate text as data structures like simple variables or more complex structures like arrays. The data is used by the builder engine Jekyll and by the build-in modules of the J1 Template to control their behavior.
|J1 does not use a Database System in the sense of an RDBMS, a Relational Database Management System as CMS does. For making a template system like J1 flexible and configurable, a database is needed. The database for J1 consists of (text-)files of type YAML.|
You are reading this for the first time. And, understandably, the codebase is difficult to understand. To become familiar with the codebase and folder structure for a J1 project, have a look at your project by your favorite editor. Open the project folder for your Starter Web, for example, C:\J1Webs\starter.
A J1 project consists of several files and folders. Find the structure as below:
├──── . │ └─ _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||J1 Configuration data|
|2||Asciidoc includes (global)|
|3||Build-in plugins (Ruby)|
|4||Assets for the Web|
|5||Folder that contains all Blog Posts|
|6||Folder that contains all Articles|
|7||Central site configuration (Jekyll)|
|9||Homepage for the Web|
|10||J1 Project file (NPM)|
|After setting up a project,some more files are created by the setup process in the project folder. For now, ignore these files.|
The Jekyll configuration file
The Jekyll configuration file
_config.yml sits in the root of your project directory and, as the name suggests, controls the configuration settings how Jekyll and J1 are processing your site (from a global perspective).
Open this file in your editor. The configuration file is of type text, but structured! The extention of .yml indicates this file of type YAML containing markups to specify data. The data in that file in in ordered in sections for easier reading. Comments, starting with a hash (#) are not treated as data. Comments are ignored if such a file is being read and processed for data extraction.
Open this file in your editor. The configuration file is of type text but structured! The extension of .yml indicates this file of type YAML containing markups to specify data. The data in that file is ordered in sections for easier reading. Comments, starting with a hash (#), are not treated as data. Comments are ignored if such a file is being read and processed for data extraction.
From the config file you see, your website is processed in
production mode. The variable
environment is assigned the value
production. Pretty easy to read, isn’t it? Now the first magic of using a code editor. In your editor, press the keys Ctrl+Shift+F to open a project-wide search dialog.
All data for a J1 project are configured with YAML data files. Search project-wide the variable
environment to find what data file specifies this. Search for the data assignment environment: (keep attention on the colon) for all YAML data files. Your’done in no-time and no endless digging in endless GUI menus is needed.
All data for a J1 project are configured with YAML data files. Search project-wide for the variable
environment to find what data file specifies this. Search for the data assignment markup environment: (keep attention on the colon) for all YAML data files in your project. You’re done in no time. No endless digging in never-ending GUI menus and dialogs are needed.
Learning is only possible by practicing. It is a matter of fact, that the learning success requires exercising. To support you, find in this section some examples to execute J1 for real-world usage.
Environment modes are used to specify the built environment of a website, controls the HTML processing. J1 uses these modes to control the output of HTML pages.
| || || |
In production mode (default), the generated HTML pages are compressed for faster loading. All HTML elements not needed are stripped (comments), all whitespaces and not needed control characters are deleted.
In development mode, the generated HTML pages are beatified for better (human) reading. No elements are deleted and available for code inspection.
The destination folder for the generated web pages were set by:
You’ll find a folder _site in your project root. Open that folder in your editor and open the file index.html, the home page for your web. The (HTML) page generated is a single line. All elements not needed for the browser are deleted.
Generating HTML output for production this is called compression, deleting all (HTML) elements not needed. The file size gets reduced to a minimum for faster loading by the webserver. Compressed output is excellent for websites that should be deployed (make them available) to a public place, to a server providing your page on the Internet.
For development, compressed HTML pages are not useful. You’ll see why in a minute. Reconfigure the value for environment. Load the config file _config.yml in your editor, change the value from
development and safe that file.
|If global configuration settions (setting in _config.yml) are changed, the web needs to be rebuild. This is a drawback for static websites.|
Because a global configuration setting has changed, the web needs to be re-created. This process is called rebuilding a site. Stop the running web in the command shell by typing: CTRL+C.
A J1 project runs Jekyll in incremental mode with auto-regeneration enabled. All changes made to your posts and pages at runtime are automatically detected, and the affected files are rebuilt and (live) reloaded. As mentioned, this doesn’t work for global configuration changes.
A web can completely be re-created by running the task
Rebuild site incremental .. Clean up site files .. Configuration file: C:/J1Webs/starter/_config.yml Cleaner: Removing _site... Cleaner: Removing ./.jekyll-metadata... Cleaner: Removing ./.jekyll-cache... Cleaner: Nothing to do for .sass-cache. Configuration file: C:/J1Webs/starter/_config.yml Source: C:/J1Webs/starter Destination: C:/J1Webs/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 1 pagination page|s done in 14.54 seconds. Auto-regeneration: disabled. Use --watch to enable. .. rebuild finished. To open the site, run: yarn site. Done in 24.43s.
If the site has been rebuild, re-run the task
site to make the web available, again
The HTML output has been changed for development. In your code editor, the home page looks very different:
The HTML output is no longer a vast single line. Many (HTML-)comments are available that explain what had happened while processing this page. The comments provide helpful information, what component of the Template system was involved in what processing step to create a page.
|For this tutorial, or for creating webs in general, it’s not needed to know how J1 processes HTML pages. But for people interested in more technical details, the comments explain what had happened in terms of the processing chain. The comments help understand the underlying builder engine and what modules were involved in creating the HTML page.|
The WebRoot folder
Once Jekyll has built a website site, the resulting web, the entire static site, including all assets, gets written to the destination folder. In section The Jekyll configuration file, you’ll find the configuration parameter
destination that controls what folder is used.
├──── . │ └─ assets (1) │ └─ pages (2) │ └─ posts (3) ├──── 204.html (4) ├──── 400.html (4) . ├──── 533.html (4) ├──── favicon.ico (5) ├──── index.html (6) ├──── robots.txt (7) └──── sitemap.xml (8)
|1||Folder that contains all Assets of a website|
|2||Folder that contains all Articles|
|3||Folder that contains all Blog Posts|
|4||Customized error pages|
|5||Default favicon for the site|
|6||The Home Page|
|7||Info file for search engines (crawlers)|
|8||Structure data of the site content used by search engines (crawlers)|
Open the WebRoot folder in your code editor. The home page of your websites is sitting in the WebRoot folder, all other generated HTML content gets written to:
pages, the folder that contains all Articles
posts, the folder that contains all Blog Posts
Compare the folder structures for posts and pages by their corresponding source folders collections and pages in the project root folder. If the folders pages are compared for source and destination, you’ll find some differences.
Much more different is the picture if collections and posts are compared. First, why is the source folder for posts collections? The reason is that Jekyll supports three content types:
The builder engine Jekyll differentiate content into two classes:
I hear your voices: what the hell is that! If not, that was what I did first.
What criteria is Jekyll using to order content? No big deal: it’s the time. For Jekyll websites, blog posts have a timestamp to make them time-lined. That is the same for all Blogging systems in general. The order over time makes it possible to differentiate older posts from the newer ones. The following criteria for ordering blogs post is the category they belong to.
In short, blog articles are ordered by:
followed by their category
If you look at the Blog Navigator J1 provides, check the NavBar of your starter web for Blog, it becomes clearer why ordering content makes sense.
|The content-type collections are not discussed in that course, not to exceed the time frame of a day.|
Contrasting the pages, the unordered content. As the term implies, pages are not ordered. For J1, the content type is sorted using the build-in navigation module.
Each content type follows a specific scheme, the generate so-called perma-links, the base to create URL’s to access your web pages by a web browser. The perma-links gets discuseed in more detail in the following chapters focussing on writing content.
Each content type follows a specific scheme, generating so-called perma-links, the base to create URLs to access your web pages by a web browser. The perma-links get discussed in more detail in the following chapters focussing on writing content.
Finally, compare the assets folder for source and destination. You’ll find many folders were created on the output side but do not exist in your project folder.
Is it magic?
The next again! You finished your step-in into the world of J1 and Jekyll. Time to have a break. You have deserved a break!
If you return, some stuff for wrapping up is provided to consolidate what is learned so far.
The following questions will help you review this chapter for the essential topics for better learning success.
First, answer the questions on paper. Before you look up an answer, take some time to answer the question yourself. If you find it challenging to find the correct answers, refer to the previous sections.
Clicking the link on the question number will open a new page (tab) in your web browser and point you to the answer. This page helps to navigate to the questions by a table of content (TOC). Go for the question number or the chapter title.
|If you finished the questions section, you could close the browser windows (tabs) opened for answers or questions and continue on this page for the next section.|
The J1 Template System is using NodeJS. For what?
A code editor is a critical tool to manage J1 projects. What are the main reasons?
The Jekyll builder engine make use of a central configuration file. Give two examples of the settings and what do they control.
J1 is using two environment modes to control the HTML outputs for a website. What modes are available and what do they control?
A lot you’ve learned, time to summarize what is in behind. The last chapter Summarize! should help on that. Summarize! offer some handy sections to remember what was presented, giving an outlook what could be done next. This section provides an overview on all chapters this tutorial and finally useful links to read more.
See all sections below:
Recap — What has been done, what’s explored in current section
Whats Next — Find to go further, what’s planned next
All Chapters — The full chain, all chapters
Further Reading — List of helpful links to get more
Again, a chapter full of hard stuff, You learned, a website managed a J1 is a project. Creating J1 projects is done by the CLI j1, part of the Ruby GEM j1-template.
You have compared some folders on the source and destination of a J1 project. Jekyll is a tricky thing, as you’ve seen for a closer look what the engine is doing. Document types and classes in the sense of the builder engine are important to know to understand the different behavior outputting a web to a destination.
J1 is a GEM-based template. Nice, but this has consequences! It should be much more understandable, not in all details, what the reasons are why some resources of a web can be found on the destination but not available with the project on a source-level.
J1 projects managed by a NodeJS project manager. The preferred manager tool is yarn. The manager tool yarn is used for all project-related tasks like setting up, running, or rebuilding a web. Find a summary of the tools and tasks in the table below.
| || |
Creating a J1 project is done by the CLI j1, provided by the (Ruby) GEM j1-template. The task
| || |
For managing a J1 project, the (NodeJS) project manager yarn is used. Make an initial scaffold for a project a usable website, a project has to be initialized first.
| || |
Running a website out of a J1 project, the project manager yarn is started by the task
| || |
If making changes to the global configuration, a website needs to be re-created. To rebuild a website from scratch, the (NodeJS) project manager yarn is called for the task
Well done, folks! You managed to create a J1 project and run your first web.
Take some time to relax, save energy for the next!
The following chapters focus on content creation, explain how to write posts and pages using J1. These sections discuss the writing and the use of the markup language Asciidoc for your content.
Make your website real!
Continue on next section to create pages on your own: Writing Articles!
Find here an overview on all chapters this tutorial.
Find from here some interesting links to additional sources of information for further reading. It’s not needed to go for all the pages, but the links will give some more background provided by other people, what they do, and what other experts have on their minds.