![Accessing scheme for a CMS (dynamic web)](/assets/image/collections/blog/featured/dynamic-web-access.jpg)
Web Browser
Web Server
Server-side rendered (prepared) static content
A CMS (Content Management System) is a software application that allows the creation and delivery of digital content in general. The flavor Web Content Management System (WCMS) is widely used to publish websites. Well known (W)CMS are WordPress, Joomla, and Drupal.
A WCMS lets multiple contributors create, edit and publish websites from a central place to the web. Huge web projects, like an enterprise website, benefits from the centralized architecture but requires a large toolset to process data stores in a database into simple web pages provided by a webserver.
A typical CMS-driven website works by building every page dynamically. That means fetching the content from a database to pass them over to a template system (engine) to load the page content, adding the required structure information (e.g., CSS styles) and Javascript components if needed. This means every page is assembled on demand.
Web Browser
Web Server
Rendering Engine (e.g. PHP-based)
Database (e.g. MySQL, Postgres)
Static content (Images, Videos, JS- and CSS files) and Caches
J1 Theme (J1) is a boilerplate for websites created with Jekyll, a builder engine for static webs. J1 based websites are not static. J1 websites are full dynamic Webs but follow the principles of the JAMstack.
On the one hand, J1 sites are pure static sites based on a folder with HTML and supporting assets like JavaScript, Cascading Style Sheets (CSS), images, font files delivered by a web server. On the other hand, J1 has no moving parts processed by middleware systems like PHP to extract pages from a database like CMS (e.g. WordPress) does.
The builder engine Jekyll for J1 generates all components needed from JAM sources upfront. JAM sources include all CSS and Javascript files and APIs used to build a dynamic website.
Netlify provides everything needed to build fast, modern websites based on static websites generated by modern site generators like Jekyll and many others (Next.js, Hugo, Gatsby, 11ty). The platform supports powerful features like continuous deployment and serverless functions support your website for the better.
Netlify is an option to deploy, to place a J1-base static web on the Internet. Running a web on this platform is easy to manage, very fast, and can be done for free.
A content delivery network (CDN) ensures fast and reliable delivery of the contents of a website directly out of the region in which the visitors of a website are located. The network consists of a group of servers distributed around the world. This network enables the delivery of web content at the highest speed by providing temporary copies of files (caching) to the users.
One of the central strategies of the JAMstack is the creation of static Web content. All components of a static web like HTML pages, CSS and JavaScript files are already fully prepared. The Web server can deliver all files directly without any intermediate processing.
Static content enables a CDN to serve entire webs from the caches and thus leads to a significantly better processing speed than would ever be possible with classic content management systems (CMS).
GitHub is a code hosting platform for version control and collaboration using the version control system Git. The platform lets programmers and others work together on projects from anywhere. Millions of developers and companies build, ship, and maintain their software on GitHub.
Jekyll is the engine behind the service GitHub Pages, a GitHub feature that allows users to host websites based on their GitHub repositories for no additional cost. J1 based web projects are typically tracked under the control of Git. Placing such a repo at GitHub is good for public projects and small groups.
The JAMstack is a construction method for building websites and applications consisting of JavaScript, APIs, and Markup. Sounds trivial because all modern web technologies are using JAM components to create Webs.
The JAMstack is a philosophy, an approach to build modern Webs. It is not a compilation of developer tools, a software bundle like the LAMP Stack. In other words: the JAMstack technology describes how to create a web, not defining toolset to be used.
Today, JavaScript (JS) is omnipresent in all browsers. JS is the Virtual Machine (VM) for the Web to add dynamic to any web page. The VM is the processing engine at runtime of a web to modify or load the changing parts on all pages. And it is the runtime layer for the JAMstack.
An API (Application Programming Interface) is an intermediary that allows applications to communicate with each other. Understand APIs for the Web as an abstract interface for querying a particular service. A web server can load local (JS-)based APIs to add, e.g., additional items to a page at runtime or request a provider API on the Internet for a service to translate pages.
A markup language (ML) is a machine-readable language for structuring and formatting texts and data. Affiliations, and forms of representation of text sections are described by marking them with keywords: the tags. Markup languages aim to separate the structure and presentation of any text. A text marked this way must first be interpreted to achieve the desired output form.
However, it is possible to convert the selected text into any output format. The markup language enables a neutral description of text and data, regardless of the form of representation used for the output. The marked text can be prepared for output in a web browser with a suitable interpreter. However, the same markup text can be used to generate PDF files or for output to a printer.
J1 Theme makes intensive use of markup languages to generate HTML pages and CSS and JavaScript files of a website. According to the JAMstack approach, all marked (text) data are pre-processed to deliver all website files directly from a CDN.
The template J1 comes with a website included, a boilerplate for new a website This Web is called the Starter Web, a general-purpose scaffold to be modified for your needs.
The people on Netlify provide a really easy workflow to bring a website to life using a template like JekyllOne Theme on the Internet in minutes: The 1-Click Deployment. The Workflow allows users to deploy a website on the Internet without a locally running installation on their computers. I invite you on a journey to using the 1-Click Deployment for your new site on the Internet. At the end of this chapter, which only takes a few minutes, you will have your presence, a website on the Internet. You don’t need any software to be installed on your computer. You won’t pay anything for this.
Two service providers are required to make this happen: Github and Netlify. The platforms provided by Github and Netlify are used to build and control a J1 website on the Internet. Both providers give full access to their services with no limits.
If you have already worked on the section Rocketstart, you can skip this chapter. A Starter Web is on Github and Netlify already in place and can be used for the next section Development System. |
If you do not already have accounts, sign up to be prepared for the journey:
It is recommended to sign up for Github first. You can use the account data from Github to register on Netlify. |
The people on Netlify prepared a really easy process to bring a website live using a (JAMstack-based) template like J1 on the Internet in minutes. This is magic but real.
The 1-Click Deployment on Netlify opens a new window, a new tab in your browser. From the section Deployment Reference you find all the steps for this process in all details. To control the deployment process better, place the browser’s windows side-by-side.
Start the magic on Netlify!
As you have seen, a website is created in just a few minutes with J1’s built-in basic web. This section will deal with preparing a toolset to edit your site from your local workstation. On the one hand, the local editing corresponds to the basic idea of version management using Git. On the other hand, the local development system will make the work much easier.
Setting up the required software and tools takes a lot of time. Depending on how proficient you are in installing applications, you will need between one and two hours to complete all installations.
Enough of the long speech: Now comes your tool kit for your personal websites.
Modern hardware is expected for all desktop computers or Laptops For your reference a typical setup looks like so:
a multi-core CPU,> = Intel i5 or AMD Ryzen 5
8 GB of RAM, 3-4GB free memory
an internet connection, bandwidth> = 16k (simple DSL)
a current monitor, display size> = 21 inches
For developing a website, some performance of your computer hardware is essential to work smoothly. It’s no fun having to wait for ages to modify the project and process the changes. A modern monitor is necessary to run multiple programs in parallel on different windows on one screen in parallel. It is possible to use a laptop with a 15-inch display but be prepared for some inconveniences in its operation.
For controlling J1 projects, a shell is required to run commands at the command line (Windows: command prompt). The easiest way to run a shell on Windows operating system is to create a shortcut for the command prompt cmd.exe
on your desktop.
First, right-click the mouse on your desktop. This calls up a context menu from which a new link can be created.
In the first dialog box, type cmd.exe for the program to run.
Then name the shortcut in the second dialog box to Shell.
Take a detailed look at the steps in the following screenshots.
With the help of this link, a command shell is started easily at any time.
It is necessary to work with elevated system rights from time to time. Working as an administrator will only be necessary for rare operations with the template system. For example, for updates to software installed system-wide.
Right-click on the new desktop icon Shell you can reach the context menu. From the context, you can create a new shell as a administrator.
Everything necessary to prepare the installation is now done. The next steps are necessary to install the toolset for the development environment managing J1 projects.
Jekyll and J1 Theme can be used on all current 64-bit operating systems:
Windows 10|11
Linux, Kernelversion >= 4.15 (z.B. Ubuntu >= 18.x LTS)
Apple OSX, Version >= 10.10.5 (Yosemite)
The 32-bit versions (x32) of the Windows and Linux operating systems cannot be used. In particular for the Windows operating system, 32-bit versions for simple home PCs are still widespread. It is easy to find out what architecture a Windows operating system is. To do this, copy the following command to the clipboard:
cmd /K wmic os get osarchitecture
Paste the copied command into the Windows search on the taskbar (magnifying glass symbol). After copying, the app will start, and it will open a (new) window with a display of the respective architecture.
A connection to the Internet is required for the following software installations. |
To be able to run the development system for the J1 Theme, the following programming languages are required:
Ruby, Version >= 2.7 (V3 recommended)
NodeJS, Version >= 16.x ⇐ 18.x (npm v8.5.0)
To install the required versions of the programming languages for the Windows platform system, the appropriate download links can be found in the following table.
Language | Architecture | Download |
---|---|---|
|
| |
|
|
First, download both installers. The installation programs are required for the following sections.
Administrative rights for the respective operating system are required to install the development tools. The software must be installed system-wide in privileged directories. For the Windows operating system, these are typically the directories |
The program for installing NodeJS node-v14.21.3-x64.msi was downloaded in the default download location. Start the installer directly from your browser or use the folder Download to start the installer program executable from there.
In step Additional tools of the installation process, the DevKit for NodeJS can be installed. These tools are not required for the J1 development environment and should not be installed. The DevKit for NodeJS contains applications for generating platform-specific modules for NodeJS (JS libraries). Under Windows, this is quite a complex process. If necessary, a DevKit installation can be done later at any time in a separate step. |
The procedure for installing Ruby is very similar to installing NodeJS. Since the installation steps are the same in some parts, the description is a little more compact and skips some parts that you already know.
The program for installing Ruby rubyinstaller-devkit-3.1.3-1-x64.exe was downloaded in the default download location. Start the installer directly from your browser or use the folder Download to start the installer program executable from there.
Installation of the DevKit For the final step of the Ruby installation, use option 3 to install all applications for the DevKit. To complete this installation, press Enter. |
The first part of setting up the development environment has been completed. Add additions and updates are required to use the latest versions of the tools for the development environment. Finally, the template system J1 can then be set up.
After completing the NodeJS and Ruby installations, some additional components, such as updates, are required to work with J1.
The necessary additions and updates can be applied directly at the command line. To process, use a shell with administrator rights to enter the necessary commands for the Windows operating system. Start an administrative shell as described in the section Administrative Shells.
Similar to Ruby, NodeJS uses a package manager to install and manage modules (libraries). The package manager for NodeJS is NPM (Node Packet Manager). In addition to NPM, there is another program for administering modules available for NodeJS: Yarn.
The package manager Yarn is being developed by Facebook and can be used as an alternative to NPM. In general, both programs behave in the same way. However, yarn is shorter and simpler when writing commands. The following examples use yarn as the package manager since the program is easier to use at the command line. |
For the installations of the current versions of NPM and Yarn, copy the following commands and paste the commands into the administrative shell:
npm install -g npm@latest && npm install -g yarn@latest (1)
1 | A global installation is carried out using the -g switch, which is then available to all users |
The installation software for Ruby can be many months older than the current versions of the built-in base components. Keeping the most important basic components of a Ruby installation and available tools for Ruby up to date is highly recommended.
Modules for Ruby (Gems) can be installed in different versions being. Depending on the project, however, a certain version is necessary. Otherwise, there will inevitably be conflicts in execution. To that very well-known problem of escaping the hell of dependencies, the module (Gem) bundler
is used.
Which gem (modules) a project uses in what versions defines the configuration file Gemfile . Such a Gemfile is also used for J1 projects, that specifies all necessary modules in the required versions running Jekyll. |
Bundler provides the functions necessary for Ruby projects to obtain the modules in the required versions for the respective project. The Gem Bundler must be system-wide in Ruby’s privileged directories to be set up. Copy the following command and paste in the administrative shell:
gem install bundler --no-document
The basic software RubyGems for the Ruby package manager gem
is also a module: rubygems
. An update is also recommended here, as the installation software for Ruby can be many months older than the current version of RubyGems.
As usual, the module for RubyGems can be brought up to date with Ruby Package Manager. RubyGems must also be set up system-wide in Ruby’s privileged directories. Copy the following commands and paste them into the administrative shell:
gem install rubygems-update --no-document && ^
update_rubygems --no-document && ^
gem update --system
The difficult part of installing and updating NodeJS and Ruby development tools is completed. The good news: updates are rarely necessary. Nevertheless, an update can prevent many difficulties that can be traced back to older software versions with new installations. And this is often not easy to find out!
For all further work with J1, no administrative shell is required, and the (previous) command prompt as administrator can be closed. All further steps require a shell started as a regular user. Running commands in the user scope ensures that programs cannot make changes to the operating system without your knowledge can perform. Better safe than sorry.
Start a shell via the Command prompt icon on the desktop and copy the following commands to display the versions of NodeJS and Ruby:
cls && ^
echo|set /p dummyName="NodeJS " && node --version && ^
echo|set /p dummyName="NPM " && npm --version && ^
echo|set /p dummyName="Yarn " && yarn --version && ^
echo|set /p dummyName="Ruby (Core) " && ruby --version && ^
echo|set /p dummyName="RubyGems " && gem --version && ^
bundler --version
NodeJS v14.19.3 NPM 6.14.17 Yarn 1.22.17 Ruby (Core) ruby 3.1.3p185 (2022-11-24 revision 1a6b16756e) [x64-mingw-ucrt] RubyGems 3.3.26 Bundler version 2.3.26
If difficulties are working with J1, the version status of the development environment can be very helpful and serve as an orientation as to whether incorrect versions are the cause of problems.
The elementary tools for managing and editing the contents of a web includes:
Git, the version management
Github CLI, GitHub command line interface
A source code editor (e.g. Atom)
The version management Git is used to manage the sources of a J1 project. Versioning will do a lot for you. With the help of Git, you manage the central repo on Github, which is also a very secure backup of all project data. Even if there are errors in the local working copy, you can always fall back on working versions of your website.
Version control will protect you from serious data loss. With the help of Git, you will first create a development version. With the help of the development version, you can make and test changes without changing the main version. You will find out how helpful it is to make significant changes without the risk of your site on the Internet being affected.
Download the latest version (03/23) for Windows from here: Git v2.40.0.
A powerful source code editor like Atom is the backbone of the developer toolset. The code editor is like a second skin for developers. Many important functions are already built into the editor or can be easily installed later. If you are already using such an editor, continue to use the tool. I’m pretty sure, you won’t change the editor.
For those who have not yet worked on any source projects, such an editor is recommended. Sure, it’s another new tool to learn, but your efforts will be richly rewarded.
Installing programs is anything but exciting. Learn about some product features during the installation, the screenshots of the individual steps of the installation are commented.
The screenshots help you to choose the right options, and at the same time, you get to know several technical terms that can help with your work.
The installation of the Git installer comes with a bunch of dialogs. Many Git settings are queried during installation. The individual steps are commented on to understand the various dialogs better.
To protect your Git installation bits for unwanted changes, the default (privileged) path |
Default selections make sense. To create some handy icons on the desktop, tick |
For users on Windows, it is recommended to create an additional folder for the (Windows) Start Menu. If your desktop icons get lost, you find all important applications from there. |
To add changes to the repo for versioning, a so-called commit is needed. Every commit is accompanied by a message text describing the changes. The message text can be given at command-line (git command commit) or edited in a simple text editor. The default editor for Git is |
Understand a branch for Git repos as the name of the current track of changes. The main track is named master for historical reasons. This name is not longer used today. To sync with Github, use main for the name. |
The Git versioning system is originally developed on Unix systems like Linux. Git on Windows uses native Unix/Linux commands under the hood supported by a compatibility system called MSYS. Like the command The default option is highly recommended to avoid conflict running commands having the same name. |
As already mentioned, Git has its roots in Unix. On Unix-like systems, the Secure Shell (SSH) subsystem is widely used to establish secure and encrypted connections. On Windows, no SSH subsystem is build-in. In most cases using Git on Windows, the default option (use of the bundled OpenSSH subsystem) should be used. |
Similar to SSH, SSL libraries are not available on Windows by default. The Secure Shell (SSH) subsystem depends on SSL libraries to establish secure and encrypted connections. For compatibility reasons, use the default option (OpenSSL). |
So-called The best compromise for managing different line endings are to let Git decide what type should be used. All (text) files checked-in a Git repo uses the character |
As already mentioned, Git uses MSYS for Unix world commands to be executed on Windows. In addition to native Windows shells, such as the cmd.exe command prompt, the Git shell may be used as an alternative. Git shells are based on the Unix shell bash, which is widely used on Linux systems. A Windows shell is completely sufficient for working with J1 projects. Nevertheless, a real Unix shell can be helpful and useful on a case-by-case basis. Accept the default setting and leave the Git Shell unchanged. |
You have already learned Git as a distributed versioning system. The essential character of this distribution is a remote repository and local working copies for editing the sources. Ultimately, the local working copies will have to be merged back into the remote repository. It is certainly easy to imagine that bringing these together will not be very easy and that this operation can produce errors. The version management Git provides different strategies to merge sources. The simplest and most common strategy is fast-forward. The strategy of fast merging is based on the assumption that the changes in the sources do not differ greatly. If changes are transferred very regularly to the remote repo, it is also the case that the sources do not differ very much from one another. This strategy is well suited for regular merging and can be adopted as a default setting. |
You have already got to know Github as a service provider and have an account for managing your repositories. Unfortunately, the Internet is not a peaceful place. Unfortunately, you have to say it that way over and over again. Nevertheless, ways have to be found to enable smooth work even if access to an account is necessary that belongs to a service provider on the Internet. The secure storage of account data on your PC is made possible by the Git Credential Helper. Accept the default settings here to synchronize the repositories' data in a simple and very safe way. |
The version management also integrates extended functions of the operating system to manage files and directories. Extended functions apply to all operating systems. Accept both options for the best support for files and directories. |
Experimental functions can be helpful but are reserved for experienced users. These options are not required for using Git for J1 projects and should not be selected. |
Working with version control will be a theme in the following sections. At the moment, there is no repository. Starting a Git Shell doesn’t make much sense. Reading the version information on software products is very important. The knowledge of relevant changes of a product applies particularly to upgrades when changing to a new version. In the case of a new installation, reading all the version details can be done later if the information matters. |
To control J1 projects, mostly simple commands are used, which are entered on the command line. The Github CLI is useful for working with Git repositories managed at Github.
To download the installer, go for Gihub CLI Home or download the latest installer (version of 01/22) for Windows from here Installer v2.4.0.
The installation is very simple and can be done quickly in just a few steps.
The installation of the Atom editor is done very quickly. A large number of useful presettings are made automatically by the installer. After the installation is complete, very few settings are required and the editor is ready for use.
The individual steps are commented on to understand the various dialogs better.
The installation of the Atom editor is fully automatic. All the necessary settings are made during the installation and can then be adjusted later should this be necessary. After completing the installation, the editor is started, and a few settings have to be made. |
A Uniform Resource Identifier (URI) identifies a logical or physical resource used by web technologies. URIs provide a means of locating and retrieving information resources on a network, either the Internet or resources on local systems such as a computer filesystem. The editor Atom specifies the URI |
Lastly, it is on you to send usage information back to the makers of Atom over an active Internet connection. I’m using Atom on Windows mainly for J1 projects, and the editor’s setup is very basic. I expect less relevant information to develop Atom as a product and reject on that. But, it is on you! |
As an option, a welcome guide tab can be shown if you start a new editor instance. For the first time using Atom, this might be helping somewhat. A lot of excellent articles about using Atom are available on the Internet. It is on you to leave this enabled. You can disable the welcome guide at any time. |
Installing and updating the development environment for J1 was a tough job. Creating and starting a J1 project, on the other hand, is much easier. After a handful of steps you have arrived and can finally start your new web. In the following, you will know all the necessary work steps for managing a J1 project. There are different ways to create a J1 project or a new website. You already know one way: 1-click deployment via Netlify. This type of deployment has automatically created a new repo in your workspace on Github.
The opposite way is, of course, also possible. That means you first create a J1 project locally on your PC and then connect the local project as a Git Repo with Github. It is also very easy to provide the website via Netlify. Only a few steps will be required to publish locally generated sites via Netlify.
The basis for the administration of J1 projects is the Ruby Gem j1-template
. The first step is to download the current version of this module over the Internet. Modules (Gems) are loaded directly with the tools of the Ruby programming language: the Ruby Package Manager gem
downloads and installs modules in one step.
In general, modules for the Ruby language can be system-wide or installed on a computer for a specific user (userized installation). The installation of Ruby Gems (modules) in user directories does not require elevated operating system rights and makes the loading of modules for projects much easier.
Every user can manage the required Ruby Gems for a project without administrative rights. The default user Gems folder for J1 projects should be
|
.gems
folder on WindowsTo create the`.gems` folder on Windows, the environment variables %HOMEDRIVE%
and %HOMEPATH%
can be used to specify your home directory on Windows.
.gems
folder on Windowsmd %HOMEDRIVE%%HOMEPATH%\.gem
.gems
folder on Unix/LinuxTo Create the`.gems` folder on Unix or Linux,
.gems
folder on Linuxmkdir ~/.gem
cls && gem install j1-template --remote --user-install --no-document (1) (2) (3)
1 | Download the module via Internet from rubygems.org (--remote ) |
2 | Copy/Install module userized, folder home of the user (.gem/ruby) (--user-install ) |
3 | No need to install developer documents (skipped) (--no-document ) |
J1 is a so-called gem-based template for the Jekyll generator.The software requires several other modules, automatically loaded as dependencies. Below you see a summary of the screen outputs of an installation:
Fetching warden-1.2.9.gem
Fetching rack-2.2.3.gem
...
WARNING: You don't have c:/users/<user_name>/.gem/ruby/3.1.0/bin in your PATH, (2)
gem executables will not run.
...
Successfully installed rack-2.2.3
Successfully installed warden-1.2.9
...
Building native extensions. This could take a while... (1)
...
Successfully installed j1-template-2024.3.13
64 gems installed
1 | During the Installation, platform-specific extensions are generated |
2 | An important note is the warning in the output of the installation. To do this, read Extend the search path. |
The first Installation of J1 will take a while. On the one hand, one must download several other gems (modules) for Ruby. On the other hand, some modules require the creation of platform-specific extensions for the respective operating system. However, all steps are automatic expire and do not require any further input.
The Installation of Ruby modules in the user’s home directory has a side effect that has to be taken into account: modules for Ruby can also contain programs. And that is the case for the J1 Theme. To use the build-in control program j1
from the module j1-template
, expand the search path (PATH) for programs. The next section Extend the search path shows how to extend the search path on the Windows operating system.
Besides the depending components for website development, with the Gem j1-template
, a easy to use control program j1
is integrated to manage J1 projects. After Installation, all programs included in modules (gems) are installed in the user’s home directory located in the following folder:
C:\Users\<user_name>\.gem\ruby\3.1.0\bin
The search path (environment) is to expand to start gem-based applications. The extension of the search path for the operating system Windows is managed by running the following command in a shell (command prompt):
SETX PATH "%PATH%;%HOMEDRIVE%%HOMEPATH%\.gem\ruby\3.1.0\bin"
SUCCESS: Specified value was saved.
The extension of the search path, unfortunately, has a catch. The value of PATH in the environment of a user has been saved immediately but is still unknown in the current shell. Restart the shell to take effect the changes of the user’s environment.
Under Windows, this means: close all the previous started shells (all windows of type Command Prompt) and restart the apps. Restarting is required for all further steps to manage J1 projects, to be able to start the control command j1 from a user’s directory. |
The control program for J1 projects is j1
is used to manage projects. After installing the Gem j1-template
, check in a shell what version of J1 Theme Gem has been loaded.
j1 --version
j1 2024.3.13
As of 02/22, the version from J1 is 2024.3.13. Older versions should not be used from this on. |
Further information on using the CLI j1
is available from the help function.
j1 --help
j1 2024.3.13 -- J1 Theme is a gem-based Template made for Jekyll
Usage:
j1 <subcommand> [options]
Options:
-h, --help Show this message
-v, --version Print the name and version
-t, --trace Show the full backtrace when an error occurs
Subcommands:
generate Generates a J1 project scaffold in PATH
help Show the help message, optionally for a given subcommand
patch Install patches available for J1 projects
rebuild Rebuild the J1 projects website (1)
reset Reset a J1 project to factory state
setup Initialize a J1 project for first use
site Run the website of a J1 project
1 | rebuild , reset , setup and site are so-called top-level commands to control J1 projects |
You’ve installed the versioning system Git already, but the system is not configured yet. To create and use Git repos for local J1 projects, the CLI git
can be used from command line. A basic setup of Git is very simple. Only two properties used by Git are required to set your account’s default identity for the versioning system:
your user name
your personal email address
Rum a command shell and run the following commands:
git config --global user.name "<your_user_name>" (1)
1 | Replace <your_user_name> by your user name used of the platform you’re using (the operating system Windows for example) |
git config --global user.email "<you@example.com>" (1)
1 | Replace <you@example.com> by your personal email address |
That’s all for the basic setup of Git. In the future, all Git commands will use these personal settings to identify what person has made changes to a repository and what email address is available for contact.
Creating and starting a J1 project is very easy. Already after a handful of steps you have arrived, and you can start your new website. The next sections describe all the details on the steps for managing J1 projects.
Here is an overview of the necessary steps:
setup a project
if required: setup a project as a repo (Git)
initialize a project
start a project and run the included website
A project consists of several files and folders. A typical structure of a J1 project is shown 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) └──── README.md
1 | Configuration data for the website |
2 | Global includes used by all (Asciidoc) content sources |
3 | Build-in (Ruby) plugins for Jekyll |
4 | Static assets for the Web (images for example) |
5 | Content folder which contains all blog posts |
6 | Content folder which contains all (article) pages |
7 | Central Jekyll site configuration |
8 | Central Ruby Gemfile to declare all depending modules |
9 | Homepage for the Web |
10 | Central (NPM) project file to manage a website |
The new website, which was created by Netlify using the 1-click method in the chapter Awesome Site, is a repo in the work area of your personal Github account. In the sense of the version management Git, this repo is the so-called remote, the central instance of your J1 project.
If you have’nt created a website at Github or you won’t use the service providers Github and Netlify for now, you can create a local J1 Project. To create and manage pure local J1 projects, you don’t need any service provider. Continue for pur local projects on the next section Create new J1 projects. |
The following steps will create a local working copy, the so-called local in terms of Git. With the help of the local working copy, the website can then be edited with the development environment and synchronized with the central instance on Github to develop your contents.
First, connect to Github using your personal Github account from the Github login page.
URL for your repo at Github
Access your personal account
Select URI to access a repo from Git
Now it is necessary to use Git versioning for the first time. Similar to the control command j1
for J1 projects, the control command for the administration of Git repos is the command git
. To work on J1 projects, controlling the repositories via the command line is highly recommended. Most repository-related operations can be done by very simple commands that are also easy to remember.
First, create a directory on your PC in which your websites' future projects are to be created. In the following examples, projects are created in the project folder C:\J1\Projects
.
mkdir C:\J1\Projects && cd C:\J1\Projects
Creating a (local) working copy from your (remote) repo at Github can be done this way:
git clone <URI_of_your_repo_at_Github> (1)
1 | URI: Copy the URI from the web interface at Gh as shown in the screen shot from above (3) |
What repo should be copied (cloned) is given by the URI to access Git repos at Github. Copy the URI for your repository from the Github web interface using the button Code for the HTTPS protocol.
clone
Cloning into '<name_of_your_repo>'...
remote: Enumerating objects: 1930, done.
remote: Counting objects: 100% (1930/1930), done.
remote: Compressing objects: 100% (777/777), done.
remote: Total 1930 (delta 1022), reused 1927 (delta 1019), pack-reused 0
Receiving objects: 100% (1930/1930), 27.76 MiB | 4.83 MiB/s, done.
Resolving deltas: 100% (1022/1022), done.
Well done, that’s all to create a local working copy using a Git command. Skip the next section and continue on Initialize a project to make your J1 project ready to use!
If the Gem j1-template
is installed, completely new projects for J1-based websites can be generated from scratch. All projects for J1 are created using the control program j1
(on the command line).
If not already done, create a directory in which your websites' future projects (local copies) are to be created. In the following examples, projects are created in the project folder C:\J1\Projects
.
mkdir C:\J1\Projects && cd C:\J1\Projects
The command j1 generate
creates a new folder (my-start) on your project’s location.
j1 generate my-start
YYYY-MM-DD hh:mm:ss - GENERATE: Running bundle install in <path_to_your_projects>/my-start ...
YYYY-MM-DD hh:mm:ss - GENERATE: Install bundle in USER gem folder ~/.gem ...
YYYY-MM-DD hh:mm:ss - GENERATE: Fetching gem metadata from https://rubygems.org/...
YYYY-MM-DD hh:mm:ss - GENERATE: Resolving dependencies...
YYYY-MM-DD hh:mm:ss - GENERATE: Using bundler 2.3.26
YYYY-MM-DD hh:mm:ss - GENERATE: Using ruby2_keywords 0.0.5
YYYY-MM-DD hh:mm:ss - GENERATE: Fetching public_suffix 5.0.1
YYYY-MM-DD hh:mm:ss - GENERATE: Fetching asciidoctor 2.0.18
YYYY-MM-DD hh:mm:ss - GENERATE: Fetching bump 0.10.0
YYYY-MM-DD hh:mm:ss - GENERATE: Fetching builder 3.2.4
YYYY-MM-DD hh:mm:ss - GENERATE: Fetching colorator 1.1.0
YYYY-MM-DD hh:mm:ss - GENERATE: Fetching concurrent-ruby 1.2.2
YYYY-MM-DD hh:mm:ss - GENERATE: Fetching date 3.3.3
YYYY-MM-DD hh:mm:ss - GENERATE: Fetching unf_ext 0.0.8.2 (x64-mingw-ucrt)
YYYY-MM-DD hh:mm:ss - GENERATE: Fetching eventmachine 1.2.7
YYYY-MM-DD hh:mm:ss - GENERATE: Fetching http_parser.rb 0.8.0
YYYY-MM-DD hh:mm:ss - GENERATE: Fetching execjs 2.8.1
...
YYYY-MM-DD hh:mm:ss - GENERATE: C:/Users/<user>/.gem/ruby/3.1.0;C:/DevTools/Ruby31/lib/ruby/gems/3.1.0;
YYYY-MM-DD hh:mm:ss - GENERATE: Install patches in USER gem folder ~/.gem ...
YYYY-MM-DD hh:mm:ss - GENERATE: Install patches on path C:/Users/<user>/.gem/ruby/3.1.0 ...
YYYY-MM-DD hh:mm:ss - GENERATE: Install patches successful
YYYY-MM-DD hh:mm:ss - GENERATE: Generated Jekyll site installed in folder <path_to_your_projects>/my-start
The command j1 generate starter
creates new directory my-start
on your project’s location, and all necessary project files are generated in this folder. If done, change to the specified directory (my-start). The final step in creating new projects is to bring the new project under the control of Git, the versioning system.
The versioning system is your safety net for managing projects. It is highly recommended to bring a project under version control. To initialize the new project for a Git repo, change the current folder to the project folder.
cls && cd C:\J1\Projects\my-start
git add . && git commit -am "Initial version"
If you got an error like so: Author identity unknown *** Please tell me who you are. Run git config --global user.email "you@example.com" git config --global user.name "Your Name" to set your account's default identity. Omit --global to set the identity only in this repository. fatal: unable to auto-detect email address (got 'user@hostname.(none)') you need to setup your account’s default identity first. To manage this, check the section [Setting up Git] for more details. |
Your safety net is in place, a really good choice. To make a new project ready to use, continue on the next section’s steps to initialize.
In this example, the name of the project is my-start
. For the next steps in setting up the project, switch to your project folder.
cls && cd C:\J1\Projects\my-start
The project needs to be initialized once. An initialization will create additional resources (modules) for NodeJs and Ruby. The modules are necessary and loaded for controlling the development system of the website and for the execution of the builder engine Jekyll.
All tasks for developing a web are defined as scripts of the NodeJS package manager NPM . All scripts are defined in the central project configuration file package.json . Only a small set of top-level scripts are required to control a project. |
A project can be controlled by the package managers yarn or npm via top-level scripts. For the people not experienced in using NodeJS projects, all scripts can be started using the CLI j1 as well. |
The initialization of a project is operated by the control command j1
via the task (top-level script) setup
. Setting up a project will issue a large number of subtasks, but all of them will be processed automatically by the project control.
j1 setup
For an overview of which subtasks are carried out for a setup
, the output as a summary:
Check consistency of the J1 project ...
YYYY-MM-DD hh:mm:ss - SETUP: Running bundle install in <path_to_your_projects>\my-start ...
YYYY-MM-DD hh:mm:ss - SETUP: Install bundle in USER gem folder ~/.gem ...
YYYY-MM-DD hh:mm:ss - SETUP: Fetching gem metadata from https://rubygems.org/...
YYYY-MM-DD hh:mm:ss - SETUP: Using bundler 2.3.26
YYYY-MM-DD hh:mm:ss - SETUP: Using ruby2_keywords 0.0.5
YYYY-MM-DD hh:mm:ss - SETUP: Using public_suffix 5.0.1
YYYY-MM-DD hh:mm:ss - SETUP: Using asciidoctor 2.0.18
YYYY-MM-DD hh:mm:ss - SETUP: Using builder 3.2.4
YYYY-MM-DD hh:mm:ss - SETUP: Using bump 0.10.0
YYYY-MM-DD hh:mm:ss - SETUP: Using colorator 1.1.0
YYYY-MM-DD hh:mm:ss - SETUP: Using concurrent-ruby 1.2.2
YYYY-MM-DD hh:mm:ss - SETUP: Using date 3.3.3
YYYY-MM-DD hh:mm:ss - SETUP: Using unf_ext 0.0.8.2 (x64-mingw-ucrt)
YYYY-MM-DD hh:mm:ss - SETUP: Using eventmachine 1.2.7
...
YYYY-MM-DD hh:mm:ss - SETUP: Bundle complete! 30 Gemfile dependencies, 79 gems now installed.
YYYY-MM-DD hh:mm:ss - SETUP: Bundled gems are installed into `C:/Users/<user>/.gem`
YYYY-MM-DD hh:mm:ss - SETUP: Install patches in USER gem folder ~/.gem ...
YYYY-MM-DD hh:mm:ss - SETUP: Install patches on path C:/Users/<user>/.gem/ruby/3.1.0 ...
YYYY-MM-DD hh:mm:ss - SETUP: Initialize the project ...
YYYY-MM-DD hh:mm:ss - SETUP: Be patient, this will take a while ...
YYYY-MM-DD hh:mm:ss - SETUP:
YYYY-MM-DD hh:mm:ss - SETUP: > j1@2024.3.13 setup <path_to_your_projects>/my-start
YYYY-MM-DD hh:mm:ss - SETUP: > npm --silent run setup-start && npm --silent run setup-base && run-s -s setup:*
YYYY-MM-DD hh:mm:ss - SETUP:
YYYY-MM-DD hh:mm:ss - SETUP: Setup project for first use ..
YYYY-MM-DD hh:mm:ss - SETUP: Bootstrap base modules ..
YYYY-MM-DD hh:mm:ss - SETUP: done.
YYYY-MM-DD hh:mm:ss - SETUP: Configure environment ..
YYYY-MM-DD hh:mm:ss - SETUP: done.
YYYY-MM-DD hh:mm:ss - SETUP: Create project folders ..
YYYY-MM-DD hh:mm:ss - SETUP: Create log folder ..
YYYY-MM-DD hh:mm:ss - SETUP: Create archived log folder ..
YYYY-MM-DD hh:mm:ss - SETUP: Create etc folder ..
YYYY-MM-DD hh:mm:ss - SETUP: done.
YYYY-MM-DD hh:mm:ss - SETUP: Bootstrap project modules ..
YYYY-MM-DD hh:mm:ss - SETUP: Bootstrap utility server modules ..
YYYY-MM-DD hh:mm:ss - SETUP: done.
YYYY-MM-DD hh:mm:ss - SETUP: Detect OS ..
YYYY-MM-DD hh:mm:ss - SETUP: OS detected: Windows_NT
YYYY-MM-DD hh:mm:ss - SETUP: Build site incremental ..
YYYY-MM-DD hh:mm:ss - SETUP: Configuration file: <path_to_your_projects>/my-start/_config.yml
YYYY-MM-DD hh:mm:ss - SETUP: Source: <path_to_your_projects>/my-start
YYYY-MM-DD hh:mm:ss - SETUP: Destination: <path_to_your_projects>/my-start/_site
YYYY-MM-DD hh:mm:ss - SETUP: Incremental build: enabled
YYYY-MM-DD hh:mm:ss - SETUP: Generating...
YYYY-MM-DD hh:mm:ss - SETUP: J1 Lunr: enabled
YYYY-MM-DD hh:mm:ss - SETUP: J1 Lunr: generate search index
YYYY-MM-DD hh:mm:ss - SETUP: J1 Feeds: enabled
YYYY-MM-DD hh:mm:ss - SETUP: J1 Feeds: generate rss feeds for: excerpts only
YYYY-MM-DD hh:mm:ss - SETUP: J1 Feeds: generate rss feeds for: #posts of unlimited
YYYY-MM-DD hh:mm:ss - SETUP: J1 Feeds: generate rss feeds for: all posts
YYYY-MM-DD hh:mm:ss - SETUP: J1 SEO Tags: enabled
YYYY-MM-DD hh:mm:ss - SETUP: J1 SEO Tags: generate seo tags
YYYY-MM-DD hh:mm:ss - SETUP: J1 Sitemap: enabled
YYYY-MM-DD hh:mm:ss - SETUP: J1 Sitemap: generate sitemap files
YYYY-MM-DD hh:mm:ss - SETUP: J1 Paginator: enabled
YYYY-MM-DD hh:mm:ss - SETUP: J1 Paginator: generate auto pages: disabled
YYYY-MM-DD hh:mm:ss - SETUP: J1 Paginator: generate paginator pages: enabled
YYYY-MM-DD hh:mm:ss - SETUP: J1 Paginator: generate paginator pages: 2 page|s generated
YYYY-MM-DD hh:mm:ss - SETUP: done in 64.236 seconds.
YYYY-MM-DD hh:mm:ss - SETUP: Auto-regeneration: disabled. Use --watch to enable.
YYYY-MM-DD hh:mm:ss - SETUP: .. build finished.
YYYY-MM-DD hh:mm:ss - SETUP: To open the site, run: yarn site
YYYY-MM-DD hh:mm:ss - SETUP: Initializing the project finished successfully.
YYYY-MM-DD hh:mm:ss - SETUP: To open your site, run: j1 site
The process of setting up a project takes a while. Usually a few minutes for the first run (depending on the performance of your Internet connection and your PC' hardware). If necessary, additional modules for NodeJS and Ruby downloaded and made it usable for the project.
Understand the setup
task as an extended process of installing the necessary modules for the project and then creating the new website using the Jekyll engine.
After the project has been set up, all necessary components can be used, and all necessary steps to start a web have been completed. Running the starter web is also carried out by a top-level command accessible from the CLI command j1
.
j1 site
The site
task will do a lot for you again. What is now still required for the development of the website is then completed. Finally, the generated website is automatically opened in a browser after completing a start.
The browser started depends on the standard browser set up with your operating system. |
Check consistency of the J1 project ...
Check setup state of the J1 project ...
YYYY-MM-DD hh:mm:ss - SITE: Starting up your site ...
YYYY-MM-DD hh:mm:ss - SITE:
YYYY-MM-DD hh:mm:ss - SITE: > j1@2024.3.13 j1-site <path_to_your_projects>/my-start
YYYY-MM-DD hh:mm:ss - SITE: > run-p -s j1-site:*
YYYY-MM-DD hh:mm:ss - SITE:
YYYY-MM-DD hh:mm:ss - SITE: Startup the site ..
YYYY-MM-DD hh:mm:ss - SITE: Startup UTILSRV ..
YYYY-MM-DD hh:mm:ss - SITE: Log file exists : messages_YYYY-MM-DD
YYYY-MM-DD hh:mm:ss - SITE: Stop the server. Exiting ...
YYYY-MM-DD hh:mm:ss - SITE: Reset file: messages_2023-04-07
YYYY-MM-DD hh:mm:ss - SITE: Configuration file: <path_to_your_projects>/my-start/_config.yml
YYYY-MM-DD hh:mm:ss - SITE: Auto-regeneration: enabled for '.'
YYYY-MM-DD hh:mm:ss - SITE: LiveReload address: http://localhost:30001
YYYY-MM-DD hh:mm:ss - SITE: Server address: http://localhost:30000/
YYYY-MM-DD hh:mm:ss - SITE: Server running... press ctrl-c to stop.
YYYY-MM-DD hh:mm:ss - SITE: LiveReload: Browser connected
While developing a website, it may be necessary to rebuild a site. J1 projects are executed via Jekyll in an incremental mode with automatic regeneration. Automatic regeneration means that changes to your web content are automatically recognized, and the affected pages are recreated and loaded in the web browser.
In a few cases, this will not work. If changes are made to the project’s configuration, the website must be rebuilt. Performing the rebuild
task will reconstruct a website from scratch.
j1 rebuild
Check consistency of the J1 project ...
Check setup state of the J1 project ...
REBUILD: Rebuild the projects website ...
REBUILD: Be patient, this will take a while ...
YYYY-MM-DD hh:mm:ss - REBUILD:
YYYY-MM-DD hh:mm:ss - REBUILD: > j1@2024.3.13 rebuild <path_to_your_projects>/my-start
YYYY-MM-DD hh:mm:ss - REBUILD: > run-s -s rebuild:* && run-s -s post-rebuild:*
YYYY-MM-DD hh:mm:ss - REBUILD:
YYYY-MM-DD hh:mm:ss - REBUILD: Rebuild site incremental ..
YYYY-MM-DD hh:mm:ss - REBUILD: Clean up site files ..
YYYY-MM-DD hh:mm:ss - REBUILD: Configuration file: <path_to_your_projects>/my-start/_config.yml
YYYY-MM-DD hh:mm:ss - REBUILD: Cleaner: Removing _site...
YYYY-MM-DD hh:mm:ss - REBUILD: Cleaner: Removing ./.jekyll-metadata...
YYYY-MM-DD hh:mm:ss - REBUILD: Cleaner: Removing ./.jekyll-cache...
YYYY-MM-DD hh:mm:ss - REBUILD: Cleaner: Nothing to do for .sass-cache.
YYYY-MM-DD hh:mm:ss - REBUILD: Configuration file: <path_to_your_projects>/my-start/_config.yml
YYYY-MM-DD hh:mm:ss - REBUILD: Source: <path_to_your_projects>/my-start
YYYY-MM-DD hh:mm:ss - REBUILD: Destination: <path_to_your_projects>/my-start/_site
YYYY-MM-DD hh:mm:ss - REBUILD: Incremental build: enabled
YYYY-MM-DD hh:mm:ss - REBUILD: Generating...
YYYY-MM-DD hh:mm:ss - REBUILD: J1 Lunr: enabled
YYYY-MM-DD hh:mm:ss - REBUILD: J1 Lunr: generate search index
YYYY-MM-DD hh:mm:ss - REBUILD: J1 Feeds: enabled
YYYY-MM-DD hh:mm:ss - REBUILD: J1 Feeds: generate rss feeds for: excerpts only
YYYY-MM-DD hh:mm:ss - REBUILD: J1 Feeds: generate rss feeds for: #posts of unlimited
YYYY-MM-DD hh:mm:ss - REBUILD: J1 Feeds: generate rss feeds for: all posts
YYYY-MM-DD hh:mm:ss - REBUILD: J1 SEO Tags: enabled
YYYY-MM-DD hh:mm:ss - REBUILD: J1 SEO Tags: generate seo tags
YYYY-MM-DD hh:mm:ss - REBUILD: J1 Sitemap: enabled
YYYY-MM-DD hh:mm:ss - REBUILD: J1 Sitemap: generate sitemap files
YYYY-MM-DD hh:mm:ss - REBUILD: J1 Paginator: enabled
YYYY-MM-DD hh:mm:ss - REBUILD: J1 Paginator: generate auto pages: disabled
YYYY-MM-DD hh:mm:ss - REBUILD: J1 Paginator: generate paginator pages: enabled
YYYY-MM-DD hh:mm:ss - REBUILD: J1 Paginator: generate paginator pages: 2 page|s generated
YYYY-MM-DD hh:mm:ss - REBUILD: done in 63.599 seconds.
YYYY-MM-DD hh:mm:ss - REBUILD: Auto-regeneration: disabled. Use --watch to enable.
YYYY-MM-DD hh:mm:ss - REBUILD: .. rebuild finished.
YYYY-MM-DD hh:mm:ss - REBUILD: To open the site, run: yarn site
REBUILD: The projects website has been rebuild successfully.
REBUILD: To open the site, run: j1 site
The web can be restarted via the task site
and loaded in the browser if a website is newly created.
j1 site
Unfortunately, mistakes are inevitable. Wherever work is done, mistakes arise. Incorrect settings in the configuration of a J1 web can lead to the site no longer starting or undesirable behavior. In those cases, resetting a site’s configuration to its original state can help.
Resetting projects does not change any existing content. The content of the website remains unaffected. |
The reset
task does the reset for you and cleans up all configurations, deletes modules and files that are no longer required.
j1 reset
Check consistency of the J1 project ...
Check setup state of the J1 project ...
YYYY-MM-DD hh:mm:ss - RESET: Reset the project to factory state ...
YYYY-MM-DD hh:mm:ss - RESET: Be patient, this will take a while ...
YYYY-MM-DD hh:mm:ss - RESET:
YYYY-MM-DD hh:mm:ss - RESET: > j1@2024.3.13 reset <path_to_your_projects>/my-start
YYYY-MM-DD hh:mm:ss - RESET: > run-s -s reset:*
YYYY-MM-DD hh:mm:ss - RESET:
YYYY-MM-DD hh:mm:ss - RESET: Reset project to factory state ..
YYYY-MM-DD hh:mm:ss - RESET: Clean up base modules ..
YYYY-MM-DD hh:mm:ss - RESET: Clean up site files ..
YYYY-MM-DD hh:mm:ss - RESET: Configuration file: <path_to_your_projects>/my-start/_config.yml
YYYY-MM-DD hh:mm:ss - RESET: Cleaner: Removing _site...
YYYY-MM-DD hh:mm:ss - RESET: Cleaner: Removing ./.jekyll-metadata...
YYYY-MM-DD hh:mm:ss - RESET: Cleaner: Removing ./.jekyll-cache...
YYYY-MM-DD hh:mm:ss - RESET: Cleaner: Nothing to do for .sass-cache.
YYYY-MM-DD hh:mm:ss - RESET: Clean up projects files ..
YYYY-MM-DD hh:mm:ss - RESET: Remove bundle config folder ..
YYYY-MM-DD hh:mm:ss - RESET: Remove log folder ..
YYYY-MM-DD hh:mm:ss - RESET: Remove etc folder ..
YYYY-MM-DD hh:mm:ss - RESET: Remove various log files ..
YYYY-MM-DD hh:mm:ss - RESET: Remove lock files ..
YYYY-MM-DD hh:mm:ss - RESET: Clean up utility server ..
YYYY-MM-DD hh:mm:ss - RESET: done.
YYYY-MM-DD hh:mm:ss - RESET: The project reset finished successfully.
YYYY-MM-DD hh:mm:ss - RESET: To setup the project, run: j1 setup
If the project has been reset, the project must be initialized again using the setup
task.
j1 setup
If the project is set up again, the web can be restarted via the task site
and loaded in the browseras you’ve done before already.
j1 site
The content of a website matters; there is no doubt about that. Therefore, the first chapter on editing a website should be dedicated to this topic. Working on the content will be the largest part of all the tasks to create a website.
As soon as you start work on the first page, you will notice that all pages are written as a source text. The sources are easy to read as they are plain text. However, it is not immediately apparent what the resulting page will look like when the actual HTML target is formatted and generated to be displayed in a browser.
Using Sources may appear like a disadvantage to some. In particular, those who have had little contact with sources and their processing. Projects based on sources follow their laws in processing. Barely someone will be able to create error-free programs out of the box, nor will website authors create print-ready pages. Both programmers and authors are initially interested in writing down what they see on their minds: The concept. This very creative process of creating the concept would be interrupted again and again unnecessarily if one also had an eye on the final results.
When working with sources, you will first be interested in the general idea. With a little practice and experience, you will be able to create the concept of writing down the skeleton of your idea as a source, which is also technically and formally correct as of the source text for later translation into a target system.
JAM-Stack-based websites like J1 are programmed in the best sense. Each project requires appropriate programming languages; so does J1 Theme and the JAM Stack: The Markup Languages. The sites based on Jekyll and J1 Theme essentially use the markup languages YAML for control and Asciidoc for formulating the content.
The creation of websites is a craft and art at the same time. The craft requires suitable tools, the art your creativity. This chapter is designed to help you with both. Learning the craft and stimulating your creativity.
When working with this section, some new questions will arise. Some of them could be these questions:
Which pages already exist?
How can the existing content used for your pages?
What types of content does Jekyll support?
How and in what way does the Jekyll builder engine generate web pages?
How does the template system J1 support the creation of new pages and the modular structure of a website?
How can recurring components of a website be configured and made re-usable with the help of the J1 Theme?
Let’s start now. Learn how to create modern websites and present the content optimally using J1 Theme.
The primary tool for this exploration and editing is the source code editor. The editor is the swiss army knife, the ultimate tool for daily work on websites. The editor offers essential functions for fast and reliable editing of the content, such as creating and adapting the configuration of the template system.
If not already done, start a new command shell, change the folder to your J1 project and fire up the build-in website:
cls && cd C:\J1\Projects\my-start && j1 site
For the following example, the source code editor Atom is used. Start your editor and open your project’s folder (the project my-start
is used for all the next examples):
Menu section
Project section
From the project section (2), navigate in the tree view to the folder pages/public/about
and double-click the file about_site.adoc
to open and edit.
The quickest and most direct way to gain initial experience in dealing with a website’s content is to examine pages that are already finished, that already exist. The website built into the J1 Theme will help a lot to understand most of the elements used by the Jekyll engine and J1 Theme. The site supports you to learn the J1 Theme in a quite visual way and helps you to practice everyday routines and procedures.
All website pages have one thing in common: using layouts to generate the HTML code. The home page makes no difference in the use of layouts. See the Layouts section for more details.
---
layout: home
compress: true
title: Jekyll One
tagline: explore what J1 Theme can do
---
<pre> (1)
This page is created by the layout: home.
If this text is displayed (instead of the home page expected),
something went wrong with the layout definitions. Check the
output of the Jekyll engine building this site.
Check the contents of folder _layouts. Verify if the base
layout "home" exists and the referring chain
(inheritance) is correct.
</pre>
1 | No contents are specified in the source part for the Homepage. |
The Homepage behaves different in the source part for the content. All the content of a homepage is configured by the layout
using lanes
to reference different (content) generators for building blocks like banners and panels.
# ------------------------------------------------------------------------------
# Layout configuration settings
#
lanes:
# ----------------------------------------------------------------------------
# HEADER region (body-header)
#
# MASTER header (attic)
#
# All pages are using a specific (master) header placed at the top
# postion of a page (if enabled). Attics are fully configurable and
# can provide text information and|or image-related data like pictures
# or videos. Find the configuration for 'attics' with:
#
# attics: ~/_data/modules/attics.yml
#
# ----------------------------------------------------------------------------
#
- lane:
enabled: true (1)
id: header
region: body-header
type: sync
base: _includes/themes/j1
path: modules/attics
file: generator.html
# ----------------------------------------------------------------------------
# CONTENT region (region body-main)
#
# For the J1 Theme GEM (J1 run-time version), ONLY the building
# blocks already prepared can be used to generate the contents of
# a home page. To change the content for a 'lane', find the configuration
# for 'banners', 'panels' and FABs (floting action button) with:
#
# banners: ~/_data/blocks/banner.yml
# panels: ~/_data/blocks/panel.yml
# fab: ~/_data/modules/fab.yml
#
# NOTE:
# Do NOT add any HTML CONTENT here (directly).
#
# ----------------------------------------------------------------------------
# ----------------------------------------------------------------------------
# TEASER banner
#
# Simple intro element for a page to give an overview on the contents
# provided. Find the configuration with:
#
# banners: ~/_data/blocks/banner.yml
#
# NOTE:
# The property 'id' of a banner element MUST be the same as specified
# the configuration for banners (banner.yml).
#
# ----------------------------------------------------------------------------
#
- lane:
enabled: true (2)
id: home_teaser_banner
region: body-main
type: async
properties: g-2 elevated-z0
# ----------------------------------------------------------------------------
# CUSTOM content
#
# Load custom rendered static HTML data files or custom HTML templates
# using LIQUID processing.
#
# NOTE:
# Only includes from folder '~/_includes' are accepted to load
# HTML data (include) files from.
#
# ----------------------------------------------------------------------------
#
- lane:
enabled: false (3)
id: custom_content
region: body-main
type: sync
base: _includes/custom
path: static
file: custom_teaser.html
...
1 | Place the top header (attic) |
2 | Enable|Place a teaser (banner) element |
3 | Disabled element (not placed on a page) |
The main reasons for the diffrence in configuring the contents of the Homepage are:
complexity of a Homepage (the landing page)
a lot of moving parts are used by dynamic content
the use of already existing building blocks like banners and panels
How to configure a homepage can be found in section Configure the Homepage.
In the editor on the right, you find all open files organized in tabs. For now, only a single file is opened: the about file about_site.adoc
. To work on content pages, typically, you’ll have to open multiple files in your editor, but it is easy to switch from one file to the next using those tabs.
The following screenshots is showing a typical structure of a content page. You can identify two main blocks in each of a content file:
a control block
a content block
The control block consists of the front matter and the prologue section. The name control block suggests that the control sections are used by the builder engine for individual page settings. The content block defines the unique content of a page. Remarkable here is, the block content does not contain any HTML code; no HTML markups.
Assume that the page contains the source code for a HTML page that must be processed by a magic first, then it’s understandable that writing content is not done by using HTML code. The page about_site.adoc
is of type text, but the file extension is .adoc
. The reason for that is, this text file contains source code of Asciidoc markup, not HTML.
Front matter section
Prologue section
Content block
You can guess that the magic behind processing the source files has to do with the Jekyll builder engine. Other magics are provided via the template system J1 in combination with Jekyll builder engine:
processing of the (J1) prologue section
processing Asciidoc code (markups)
This very rough overview should be enough for the time being to do a few practical things: change existing content.
The page about_site
has been discussed already, but how can this page be accessed? Now, J1’s menu system comes into the game. Open the page as shown in the screenshot.
The menu system of J1 is a module, a fairly complex component that provides a lot of functionality. The menu system supports visitors to get access to all website pages of type page . Because of the complexity of the menu module, it makes no sense to talk about it here in more detail. Find some information how to use the module in section J1 Modules. |
For a simple change, duplicate the paragraph:
Whether you work solo or as part of a team, it’s always a great idea to help visitors ...
Mark the block in your editor and copy (Ctrl + c
) and paste (Ctrl + v
) this block below the existing one and save the file (Ctrl + s
). In your shell, you see the changes has been detected and processed.
YYYY-MM-DD hh:mm:ss - SITE: Regenerating: 1 file(s) changed at YYYY-MM-DD hh:mm:ss YYYY-MM-DD hh:mm:ss - SITE: pages/public/about/about_site.adoc YYYY-MM-DD hh:mm:ss - SITE: J1 QuickSearch: creating search index ... YYYY-MM-DD hh:mm:ss - SITE: J1 QuickSearch: finished, index ready. YYYY-MM-DD hh:mm:ss - SITE: J1 Paginator: autopages, disabled|not configured YYYY-MM-DD hh:mm:ss - SITE: J1 Paginator: pagination enabled, start processing ... YYYY-MM-DD hh:mm:ss - SITE: J1 Paginator: finished, processed 2 pagination page|s YYYY-MM-DD hh:mm:ss - SITE: ...done in 9.6753299 seconds.
In the webbrowser, the page should has been automatically reloaded and shown like so:
By default, Jekyll uses the Webrick webserver to YYYY-MM-DD hh:mm:ss - SITE: [YYYY-MM-DD hh:mm:ss] ERROR Errno::ECONNABORTED: An established connection was aborted by the software in your host machine. @ io_fillbuf - fd:16 YYYY-MM-DD hh:mm:ss - SITE: PATH_TO_RUBY/lib/ruby/2.7.0/webrick/httpserver.rb:82:in `eof?' YYYY-MM-DD hh:mm:ss - SITE: PATH_TO_RUBY/lib/ruby/2.7.0/webrick/httpserver.rb:82:in `run' YYYY-MM-DD hh:mm:ss - SITE: PATH_TO_RUBY/lib/ruby/2.7.0/webrick/server.rb:307: in `block in start_thread' The good news: error messages of this type can be ignored. It seems this is a side-effect of the caching strategy of Jekyll if a site is served in incremental mode by Webrick. The bad news: no solution has been available to fix this issue until now. For the time being, please ignore all errors of this type. |
A Front matter is a YAML data block and must be the first section in the file of all content pages. This section is defined by triple-dashed lines to set predefined variables or set custom ones of your own.
The Front matter defines a set of variables and metadata on individual pages for the Jekyll build-in template engine Liquid as well as for the Markup processing engines to generate HTML code from Markdown and Asciidoc sources for the content. The template engine Liquid is used by Jekyll to create dynamically the common HTML code that is shared by all content pages of a page layout.
Find more information on Liquid with the Liquid User Guide. |
The Markup processing engines transform the content portion of an individual page into the resulting HTML code. The template engine Liquid and the Markup processing engines are working closely together. The engine Liquid produces the HTML code shared by all pages of a specific layout and injects the HTML-code portion generated by the Markup processing engines individually for a specific content page. Later in this chapter, with section Layouts, you’ll learn more about the relationship of the processing engines to understand better how Jekyll (engines) processes the Source Pages of a website.
Don’t repeat yourself If you don’t want to repeat yourself for frequently used Front matter variables over and over, define defaults for them and only override them where necessary. The defauls are configured with the Jekyll site configuration file |
With the help of the Front matter, all web pages are customized in a very simple way. Typical individual settings of websites are the page title and the tagline. The page title describes which page it is. The tagline provides additional information about the content of the page in question.
Other important individual page settings are:
the description (description), which is displayed in the local search (QuickSearch) for hits as a summary of the page
the keywords generated as (HTML) metadata for each page. Search engines use keywords to analyze the content of web pages and contribute to better search results
the categories and tags to organize the content. Categories and tags are displayed in the local search (QuickSearch) for hits on a page and can help your visitors to classify better a page they have found
the permalink to optimize the catalogs of search engines (SEO) to simplify the URLs of your web pages
the used J1 modules (resources) of the website, which are not generally loaded for a page
the options of the loaded modules (resource_options), which allow individual settings for each page
Use the about_site
page again to modify the settings for the variables title and tagline:
title: J1 Theme
tagline: about
Change the tagline like so:
you should know about
and save the page. Creating (HTML) pages are a dynamic process. All changes to the Front matter are dynamically applied to the site. Sure, changing the tagline is a simple example, but it shows Jekyll’s dynamic behavior. All values of variables are taken into account in the templates (layouts), and after re-creating a modified page, they also carry the adjusted settings.
The Prologue (Page Initializer) is a feature of the J1 Theme. Behind this are additional settings for the Asciidoctor generator, such as additional programs (procedures) of the template engine Liquid, which are automatically applied to each page.
The settings for the Asciidoctor generator are formulated as Asciidoc-Markup language tags. The About page uses the badges-enabled
tag to control the output of badges. When the value of the tag badges-enabled
is set to true
, an additional line with badges is generated in the further processing of the page:
This is where another magic of J1 Theme comes into play: procedures for the template engine Liquid and attributes
(variables) evalualted by the Ascidoc processor Asciidoctor. With the help of both, collections of Asciidoc variables can be processed for a page.
Collections of Asciidoc variables are stored in files. The files of these control variables are named attributes.asciidoc
and can be found in two locations:
global: ~/_includes/attributes.asciidoc
(your project folder, e.g. my-start
)
local: <your_page_folder>/_includes/attributes.asciidoc
Asciidoc attributes (variables) defines:
frequently used URLs
Frequently used special characters and character chains (strings)
Author information
Data on image and video files
The use of variables increases the readability of the source code and can significantly simplify the notation when using data elements for Asciidoc macros. Individual Asciidoc variables can be defined and frequently used attributes can be loaded from files via the prolog of the source code of a page.
With the help of conditional code blocks, you can easily individualize the content of a page. A simple example of the application is the output of a line with badges common on the Internet. In the Prolog section of the source code, you can find the local attribute badges-enabled
. The variable is used to control a conditional code block. Just rewrite the value of this (Asciidoc) variable to the value true
.
:badges-enabled: true
This means that the additional code is evaluated when the modified page is generated and transferred to the output of the HTML page.
Try to find out what lies behind the attributes of each Badge (for example: badge-j1—license ) are hidden. |
In addition to simple tags, the Asciidoc markup language offers a large set of macros for generating more complex HTML structures that can be used to integrate font icons (macro icon:
) or HTTP hyper links ((macro link:
) for example. Asciidoc attributes are very useful and will greatly simplify the notation of Ascidoc markups for macros.
Add the following code to the about_site
page and save the changes to include the additional lines of code in the HTML output:
A battery symbol is used on the pages of the J1 Theme documentation,
which symbolizes the individual level of knowledge for the use of:
* Functions for beginners of template system J1: {level--beginner}
* Functions for users with basic knowledge of J1: {level--intermediate}
* Advanced J1 features: {level--advanced}
* Functions for experts in the application of J1: {level--expert}
You find an overview of all the functions of the template system J1 on the
page link:{url-j1--features}[J1 Theme Features, {browser-window--new}].
In behind the attribute {level—xyz}
, the Asciidoctor macro icon:
is used. Check the global attribute configuration ~/_includes/attributes.asciidoc
for more details.
// TAGS, global asciidoc attributes (variables)
// -----------------------------------------------------------------------------
tag::tags[]
...
:icon-battery--quarter: icon:battery-quarter[role="md-gray"]
...
// level indicators
//
:level--beginner: {icon-battery--quarter}
The notation of the link:
macro benefits in two ways in terms of readability:
the URL parameter is shorter than the actual HTML link and is easier to read and understand in the source text due to the symbolic notation
the additional parameter via the browser-window—new
attribute is self-explanatory. Clicking on this link will open a new browser tab (window) to display the page.
For Jekyll, many templates are available that cover all typical use cases for websites. The bad story: most of them require programming and low-level customization. Deep knowledge of Jekyll and valuable experience of templating techniques using HTML, CSS, and Javascript are required.
This not the case if you’re using J1. Typical examples of using the configuration capabilities in conjunction with integrated software of the the following sections explain the template system.
Jekyll, like Asciidoctor, is extendable by additional functions. One large number of plugins are available here. Extensive functional extensions are usually offered as additional Ruby GEMs. The gem-based ones Plugins are installed like ordinary GEM and then via the Site configuration ~/_config.yaml
included.
# ----------------------------------------------------------------------------
# PLUGIN configuration
#
plugins:
- asciidoctor
- jekyll-asciidoc
- jekyll-sitemap
- j1-paginator
For minor extensions that don’t necessarily require the procedures of Ruby GEM, the program code of a plugin is installable in the folder ~_plugins
of the J1 project. Plugins in the ~_plugins
directory automatically integrated without additional configuration settings. The restriction here compared to a GEM: The plugin’s source must consist of only one file.
Many lightweight plugins are already available in the ~_plugins
directory. All extensions for the Asciidoc markup language or the engine Asciidoctor are stored in the directory ~_plugins/asciidoctor-extensions
.
The simpler and clearer the website’s source code, the better the source to be read without generating the HTML output. In addition, the code becomes more compact and generally easier to write down. As simpler the code, the fewer errors can occur in the notation.
Blocks that result in complex HTML markup in later HTML output are noted in Asciidoc via macros. Macros are parameterizable markups and the parameters control how the Asciidoc engine processes to generate target code.
There are two AsciiDoc macro types: block and inline. As for all macros, the block and inline forms differ by the number of colons that follow the macro name. The block form uses two colons (::), whereas the inline form only uses a single one (:). |
Inline macros can either be integrated within a section of the text, for example, a paragraph, or, like block macros, can create independent code sections. A good example of using these macros is so-called blind texts, known as Lorem-Ipsum texts. If a new content page is developed, the content of new articles should be written down in rough sections by the authors first. The sections outline the idea of what the page is supposed to describe, but the actual text is (still) unknown.
Blind texts can be a great help when providing sketches of new pages with a type of text. The sketch will be much more similar to a real page with dummy text and will help the author develop the page’s structure and content.
You can find examples of dummy texts supported by the J1 Theme in the round trip on the page Asciidoc Extensions. |
The page about_site.adoc
should be used again for experiments with dummy texts. Suppose your new website describes your business as a Delivery service for breakfast buffets. The About pages provide an overview of what the company can do for customers and what can be found on the pages of your presence.
A sketch of the content could have the following sections:
Experience in catering since YYYY
Your services
Large selection of national and internal dishes
Compilation of buffets per person
Crockery and cutlery service
Your delivery service
Delivery areas
Delivery times and days
Contact addresses Contact person PPP
Service mailbox MMM
These sections can initially be formulated as headings. This skeleton type makes the page clear whether sections are also be used later for the final text.
== Experience in catering since YYYY
== Our services
=== Large selection of national and internal dishes
=== Compilation of buffets per person
=== Crockery and cutlery service
== Our delivery service
=== Delivery areas
=== Delivery times and days
== Contact addresses
Contact person PPP +
Service mailbox MMM
Copy the heading skeleton into the about_site.adoc
page. If the page is newly generated, you will find that pure headings do not look good. The source text resembles a real skeleton and is not pleasant to read from this perspective. Writing content is not easy. Terrible source code and websites are more than terrifying from a psychological point of view. The motivation at work will suffer, and many things that need to be done become more tedious and even harder to do.
Change the first headings like this:
== Experience in catering since YYYY
lorem:sentences[5]
lorem:sentences[7]
== Our services
lorem:sentences[7]
lorem:sentences[5]
=== Large selection of national and internal dishes
lorem:sentences[5]
The impression of the page as a source and in the generated web page changes significantly. Customize the page with additional dummy texts and replace the placeholders PPP and MMM with appropriate Lorem macros.
Inline macros can be used like block macros if blank lines are placed around the inline macros. The blank lines create new sections, as are automatically generated with block macros. |
Complex markup typically includes all elements related to images. These web page components will never be part of sections: they are separate, independent parts of a page.
The base path for all image-related data is a side-wide (Asciidoc) configuration (see _config.yml ) and points per default to /assets/images . The base path is automatically added to each image. If you want to use the default asset path for images, a relative path needs to be given for path/to/image . |
A commonly used Asciidoc block-macro to place images on a page is the image::
macro:
.image_title
image::<path_to_image>["<alt_text>", role="<additional CSS styles"]
The role parameter for specifying additional CSS styles is optional in the image:: macro and can be omitted. |
Again, change the content of about_site
to add a simple image to that page. To make it simple for now, use the image GrandPa’s 80th Birthday. Add the following markup to that page and watch the outcome:
.Your added image
image::/assets/image/modules/gallery/old_times/image_01.jpg["GrandPa's 80th Birthday", role="mb-4"]
The additional CSS style (role) mb-4
comes from the Bootstrap framework and adds a margin
below the image. Play a bit with the additional CSS styles. The parameter wm-800
is a CSS style provided by J1 is used to limit the witdh of an block element to a maximum of 800 pixels in a page. Add the next snippet below the existing one.
.Your added image - Limit the image width
image::/assets/image/modules/gallery/old_times/image_01.jpg["GrandPa's 80th Birthday", role="mb-4 wm-800"]
Other, more complex Asciidoc Macros are available with J1 for image-based data discussed in section J1 Modules. More configuration changes on a page and additional configuration is needed to make use of J1 Modules like Lightboxes and Galleries for image data.
Admonition macros are emphased text elements placed in the running text but create independent sections. Admonitions are intended to draw the reader’s attention to the text, noted in 5 different levels.
Name | Example | ||
---|---|---|---|
|
| ||
|
| ||
|
| ||
|
| ||
|
|
Two variants can be used for the notation of Admonition Macros:
NOTE: Your text goes here.
.Admonition title
[NOTE]
====
Your text goes here.
====
The simplified notation is well suited if the text consists of only a few sentences and only Asciidoc inline-macros are used to design the test. The notation as a Block element is necessary if title lines or more complex block macros such as source blocks or tables are used.
Admonition using a title Admonition NOTE written as a block element using a |
Add the about_site
page again and add various Admonition macros to the source code. Use both spellings. A title element can also be used for block notation.
You were already able to examine the general structure of a source page in the Page blocks section. You learned that the source of a page consists of the control-block and the content-block. Your modified about_site
page might look like this:
Besides the actual content of the page from the content-block , there are a lot of other elements like that Navigation and page header . Look at other sites You’ll find that all pages on your site have these elements on your site.
This behavior is explained by the page model that the Jekyll builder engine uses to generate HTML pages. Besides the unique content of a page from the content block, all pages inherit components fundamentally required for each page. In other words, all pages consist of general elements that each page has and that unique content.
The structure of an HTML page is complex. In addition to the visible elements displayed in the browser, many other invisible HTML elements are required for a complete web page. For this, take a look at the HTML code of a web page. Displaying the HTML code can be called up with the key combination Ctrl+U. The HTML code of the fairly simple page about_site
consists of hundreds of lines. The code contains many invisible HTML elements, which are required for loading the resources used, for example. The resources of a page include the required CSS styles that give a page its shape and Javascript components responsible for the dynamic behavior of pages.
An important promise of the template system J1 is: To create a website is no programming. No programming is required because all required programs exist already and are appropriately used by the builder engines to generate the resulting HTML codes of the pages. Knowledge of the details of these programs is not necessary, but it is very helpful to know how the HTML code of a page is created, how the Jekyll builder engine generates the resulting HTML code from source pages.
Jekyll’s page model for generating HTML code from page sources is difficult to understand. But even here, it is not necessary to know all the details. However, you should be familiar with principles: The layouts.
Layouts are construction templates for HTML pages, each describing a specific step of processing. The resulting HTML code is created by applying several layouts in a specific order: inheritance.
Jekyll applies a strategy of inheriting content along a line of inheritance to layouts. The unique content is created via the layout of the respective page type. For example, page
for regular content pages or post
for blog posts. Content shared across all pages is described using the default
layout. As a very simple picture of processing pages with Jekyll can be the following (Inheritance) succession are understood:
HTML-Code < Jekyll < layout-default < layout-page < Source code (Asciidoc)
The Jekyll builder engine first reads the source code of a webpage, the page about_site,
for example. The source of this page is connected with the layout page
. This construction template processes only the specific parts of a page: the content portion. The layout page
is associated with layout default
to add all the general components, like CSS- and Javascript files, needed for a full webpage.
The construction step via the default
layout complements all general components of a website. It connects (inherits) the results from the (base) layout page
with the results of processing from the (general) layout default
to the final resulting HTML code.
Layouts describe which programs are called and in which order. These programs are associated with configuration data that describes the details of the work step in question. All Configuration data is in the project directory _data . In this data directory, you will find a folder layouts containing control files with the same name for all available layouts. |
Layout | Configuration | Description |
---|---|---|
|
| All general components of a website are generated via the |
|
| All individual components of the homepage are generated via the details specified in the layout |
|
| All individual components of a website of type page are generated via the |
The template system J1 uses many other layouts. To not completely go beyond the scope of this tutorial, these layouts will not be discussed. |
The Template System J1 uses HTML generators to create the layouts. The HTML Generators process certain sections of an HTML page. If you have a look at the general structure of an HTML page, the code sections are very simple:
<!DOCTYPE html> (1)
<html>
<head>
invisible content (3)
</head>
<body>
visible content (4)
</body>
<html> (2)
1 | Instruction to the web browser about what version of HTML the page is written in (HTML5 and beyond). |
2 | Specifies the data container for the HTML code |
3 | Invisible content of a webpage. Specifies required resources like CSS or JavaScript files to be loaded for a page |
4 | Visible content of a webpage |
J1 Theme divides the sections (3) and (4) into more specific parts:
Invisible content
Definition of meta data
Loading CSS files
Loading Javascript files
Definition of control data
Visible content
Page Header
Page Navigation
Page Content
Page Footer
To make J1 Theme fully configurable and flexible as much, the specific parts of HTML pages are specified as so-called lanes
. The lane structure is based on the sections of an HTML page, but devides the <head>
and <body>
section in more specific (logic) parts.
Lanes in a layout are configured top-down and create a stack processed in the order they are configured. Have a look at the configuration of the layout page
(_data/layouts/page.yml
):
# Layout configuration settings
#
lanes:
# ----------------------------------------------------------------------------
# MASTER header (attic)
# All pages are using a specific header to display a title and a
# tagline. Title and tagline are to be configured with the FRONTMATTER
# of a page for individual data (text).
#
# ----------------------------------------------------------------------------
#
- lane: (1)
enabled: true
region: body-header
type: sync
base: _includes/themes/j1
path: modules/attics
file: generator.html
# ----------------------------------------------------------------------------
# PAGE content
#
- lane: (2)
enabled: true
region: body-main
type: sync
base: _includes/themes/j1
path: layouts
file: content_generator_page.html
# ----------------------------------------------------------------------------
# PAGE fab
#
- lane: (3)
enabled: true
id: fab-container
region: body-main
type: async
1 | specifies a generator to create a header |
2 | specifies a generator to create the content portion |
3 | specifies a placeholder for the FAB button |
As mentioned earlier, the layout page
is associated with layout default
. This association means the default layout specifies lanes that contain generators to complete a page for all the HTML code that all webpages are using.
As said initially, Jekyll’s page model for generating HTML code via layouts is not easy to understand. And J1 Theme adds some additional complexitity to make the Template system fully configurable. The key takeaways from the previous section should be:
pages are not created as monolithic blocks but in individual steps defined as layouts.
layouts take on specific sub-tasks in the generation sequence
layouts are linked to each other through an inheritance
a layout defines content generators that run in row as given by the lanes specified
If you are interested, the configuration files of the layouts can provide information about which programs are started to generate the HTML code of a page in which order.
In the source view of a browser to display the HTML code (Ctrl+U), you find for each program appropriate (HTML) comments. These comments give a good overview of how the HTML code came about.
Authors should create source pages from scratch to create their content for a website. To not start completely from a blank page, J1 offers ready-made skeletons for new source pages. In the ~/pages/public/asciidoc_skeletons
folder, three different types support different methods of developing new pages.
Name | Description |
---|---|
| Simple documents are used quite often. If the number of chapters is about or less than three and the document is small in size. This document type use only global Asciidoc include files. |
| Multi-chapter documents are used for more complex articles of a website. If the number of chapters is or exceeds three for an article, it could make sense to split a larger documents chapter-wise into separate files. This document type is based on multiple Asciidoc documents and make use of local and global Asciidoc include files. |
| A document of type documentation (book) typically consists in a large number of chapters and sections. To make this manageable, book-type documents are splitted in multiple files placed in a nested folder structure. Complex AsciiDoc projects of type documentation can be worked on by multiple authors. |
The skeleton of a page based on the template simple-document
is used for all further experiments. This template is used very frequently, as many pages on a website only use a handful of chapters to structure the content.
First, create a superordinate directory ~/pages/public/sandbox
to manage your new pages. Copy the whole simple-document
folder from the ~/pages/public/asciidoc_skeletons
location to your new sandbox folder ~/pages/public/sandbox
.
If you copy existing content folders that contain documents, conflicts will arise because the copy creates pages with identical URLs on the web. After copying, in Front matter of the new file, the permalink parameter must be adjusted. |
After completing the copy, a few things need to be adjusted:
Change the name of the folder simple-document
to simple-sandbox
Open the file simple.adoc
from this directory and write the permalink
parameter to the value /pages/public/sandbox/simple/
around.
After the generation is complete, the new page is available in your web my-site under the URL:
http://localhost:40000/pages/public/sandbox/simple/
To better understand how the templates work, the three skeletons generate the same page content but based on a different source model. The sources are structured completely differently but deliver the same result in the generated website. |
This current content of the template should not play any role for the following tests and can be overwritten by more initial settings. Open the simple.adoc
page and replace the existing content with the following code:
simple.adoc
---
title: Sandbox
tagline: simple sandbox
date: 2022-01-01 00:00:00
description: >
Simple documents are used quite often. If the number
of chapters is about or less than three and the document
is small in size. This document type does not use any
(local) Asciidoc include files or attributes.
categories: [ Knowledge ]
tags: [ Asciidoc, Sandbox, Document ]
robots:
index: true
follow: true
permalink: /pages/public/sandbox/simple/
regenerate: false
resources: [ clipboard, lightbox, rouge ]
resource_options:
- toccer:
collapseDepth: 3
- attic:
padding_top: 400
padding_bottom: 50
opacity: 0.5
slides:
- url: /assets/image/pages/skeleton/antonino-visalli-1920x1280.jpg
alt: Photo by Antonino Visalli on Unsplash
alignY: top
badge:
type: unsplash
author: Antonino Visalli
href: //unsplash.com/@_visalli
---
// 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
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The Asciidoc skeleton *simple-document* a helper for setting up a base file
and folder structure for simple-document AsciiDoc pages based on _Jekyll_ and
_J1 Theme_. You need *both* to use this skeleton creating AsciiDoc
documents from it.
// Include sub-documents (if any)
// -----------------------------------------------------------------------------
== Chapter 1
lorem:sentences[5]
== Chapter 2
lorem:sentences[5]
=== Section 1
lorem:sentences[3]
The builder engine Jekyll differentiates between two different categories of content:
unordered content (pages)
ordered content (posts)
Thus, all pages of type Page are unordered, while all Blog Posts are orderly. The property of order is only of interest to programmers. To make documents accessible to visitors, navigation options are needed. From the perspective of the Jekyll engine, there are no options for (automatic) structuring Pages for programmers. For Posts, this is quite different.
The Template System J1 structures Page and Post type documents in its way. The template provides you with ready-made programs that structure a website’s content and are accessible to visitors via navigation do. Authors have little exposure to the Jekyll builder engine’s elementary delivery methods to visitors.
J1 provides these navigation components :
J1 Navigator, for Page type documents
J1 Blog Navigator, for Post type documents
The Posts Explorer is used for navigating blog posts and is discussed in the subsequent J1 Blog Navigator section. The first thing to look at is how documents of the Page type can be made accessible to your visitors.
The J1 Navigator component is a module in the sense of J1. Modules are dynamic components and use CSS and Javascript elements to provide the necessary functionality for a website. One of the features provided by the module J1 Navigator is the Menu Bar that provides visitors dropdown menus to browse and select content pages.
The J1 Navigator module offers several other functions, but changes to the menu bar are the most common. To manage the menu bar settings more handy, the settings are separated into a configuration file: ~/_data/modules/navigator_menu.yml
.
Open this file in your editor. The first impression conveys that the menu configuration isn’t that easy either. The configuration is simple, but extensive existing settings appear initially complex.
The menu system supports items with and without submenus (dropdowns). The simplest element in the menu bar is an item that does not create any other sub-menus (dropdowns). The configuration for an entry in Level 0 has the following form:
# ------------------------------------------------------------------------------
# TopLevel item FEATURES (commented out)
#
# - item: Features
# href: /#panel_home_intro
# ------------------------------------------------------------------------------
# Menu SANDBOX
#
- item: Sandbox
href: /pages/public/sandbox/simple/
Add the configuration from above to the file ~/_data/modules/navigator_menu.yml
below the entries of the Learn menu. The result should then look like this:
An entry in Level 1 is helpful to enable a little more options in the menu entries for sandbox documents. The submenu allows you to call up different pages as a dropdown. The configuration for an entry in Level 1 has the following form:
# ------------------------------------------------------------------------------
# Menu SANDBOX
#
- item: Sandbox
sublevel:
- title: Simple Sandbox page
href: /pages/public/sandbox/simple/
icon: pencil
Drop-down menus offer other advantages:
All entries can be provided with an icon
All entries have an individual text that can help visitors to classify the content of a page
The presented configuration of the sandbox shows that entries are not particularly complicated. Compare the settings of the menu bar of your site with the menu displayed in the browser. The principle of the menu configuration will certainly become a lot clearer quickly and will also help write more extensive entries.
AsciiDoc macros have already been discussed in the Asciidoc Extensions section. Asciidoc macros, which make J1 Modules usable in websites, are a little more complex. The use of modules requires additional settings in configuration files, but again there are none programming required.
J1 modules are independent Javascript programs integrated into the template system. Modules are listed as Resources (the actual programs) and integrated into the template system with the help of adapters. The adapters, complemental Javascript programs, ensure that no programming is required to use the module. Only suitable settings are necessary for using J1 Modules.
All programs provided and integrated with J1 are Open Sourceprojects and can be used free. |
The task of Ascidoctor Macros for J1 Modules is to generate the necessary HTML markup within a website, which are required by the connected JavaScript programs to provide the dynamic functions of the website in the browser. The settings ensure the desired behavior of a module. The adapters start the respective Javascript programs when the website is displayed in the browser and run customizations if required.
Modules are complex J1 components and are certainly not easy to understand. From the perspective of non-programming authors, only the settings of the modules are important. |
Frequently used Asciidoc Macros for J1 modules used to embed lightboxes or galleries of images are:
.block_title
lightbox::<block_id>[ <images_width>, <images_data_id>, <role="<additional CSS styles>"> ]
If more than a single image is given for a J1 Lightbox block, the images can be grouped to enable a simple sliding functionality through this group of related images. Enabling this function, the group
option needs to be configured for the macro.
.block_title
lightbox::<block_id>[ <images_width>, <images_data_id>, <group_name>, <role="<additional CSS styles>"> ]
.block_title
gallery::<gallery_id>[ <role="<additional CSS styles>"> ]
The role parameter for specifying additional CSS styles is optional in all macros and can be omitted. |
A Lightbox is a quite simple J1 Module to include single images or groups of images via a lightbox macro lightbox::
on a page. In particular, displaying images for high resolutions using the image::
macro cannot be used for original sizes on a page. Lightboxes can help here. The images are displayed in smaller sizes but can be expanded to their original resolution by clicking on the image.
Apply the example Lightbox for single images to your new sandbox document simple.adoc
below the dummy text of the first chapter. The given source include the J1 Lightbox Module with an additional dummy text below:
lightbox::images-lightbox-standalone[ 800, {data-images-lightbox--standalone}, role="mb-4"]
lorem:sentences[3]
The parameters in the Asciidoc markup have the following meaning:
images-lightbox-standalone
All modules require an ID. The Asciidoc macro generates the necessary HTML markup for the module, but the generated HTML block requires a unique identifier. Modules can use the ID to distinguish between elements of the same type (lightbox for example). For the Lightbox module, the ID can be freely selected. However, it is advisable to derive the ID from the attribute’s name to make uniqueness of the identifier sure.
800
Limiting the size (width) of the image displayed on the page to 800 pixels.
data-images-lightbox—standalone
The curly brackets address an Asciidoc attribute. The definition of these variables can be found in the global ascidoc attributes file ~/_includes/attributes.asciidoc
.
role="mb-4"
Specifying mb-4
(Bootstrap style) adds a CSS style for the lightbox that creates an additional border below the Lightbox element.
In a second step, add the example Lightbox displaying groups of images to the sandbox document below the dummy text in the second chapter. The Asciidoc code for embedding the lightbox with an additional blind text is:
lightbox::images-lightbox-group[ 395, {data-images-lightbox--group}, lb_group, role="mb-4 wm-800" ]
lorem:sentences[3]
The parameters in the Asciidoc markup have the following meaning:
lb_group
The Asciidoc attribute data-images-lightbox—group
contains two images. To display both images in the Lightbox, the parameter lb_group
creates a group and you can switch between the images.
role="mb-4 wm-800"
Again, the information supplements CSS styles for the lightbox. The styles apply an additional border below the Lightbox and limit the element’s width on the page to 800 pixels.
The lightbox module is quite simple. Only simple Asciidoc variables are required to configure the images.
:data-images-lightbox--standalone: "modules/gallery/old_times/image_02.jpg, GrandPa's 80th Birthday"
:data-images-lightbox--group: "modules/gallery/old_times/image_03.jpg, GrandPa's annual journey, modules/gallery/old_times/image_04.jpg, GrandPa's annual journey"
The module of the simple lightbox is very well suited for individual images. Still, it becomes more difficult to use it for several images, and it is hardly possible to display more than two or three images as a group in a meaningful way. Galleries are a better solution for displaying of image groups, even in large numbers.
The J1 Theme offers the very powerful Justified Gallery-Module for displaying larger groups of images. The configuration is more extensive since the module offers significantly more functions. The example Image gallery clearly shows the various functions.
A picture gallery combines two J1 modules:
a gallery component (JustifiedGallery)
a powerful lightbox (LightGallery) that adds additional functionality to the full-size image display
Most J1 modules are only required on certain pages. Therefore, loading the required resources only makes sense if the components are used on a page. Which modules will be loaded for a page configured from the Front matter via the resources
parameter of a page. To make use of an image gallery, replace the settings in the Front matter of the simple.adoc
page with the following code:
resources: [ clipboard, lightbox, lightGallery, justifiedGallery, rouge ]
The need to give additional information about a page’s resources (modules) seems cumbersome. Site visitors reject the best pages with good design and excellent content if the page takes too long to be displayed in the browser. In addition to content and design, the performance of a website is essential. Reducing the number of resources for a page will significantly reduce the time required to load a page in a web browser. |
The macro for embedding an image gallery from the example shown macro for image galleries is:
gallery::jg_old_times_2[ role="mb-4 wm-800" ]
lorem:sentences[3]
The parameters in the Asciidoc markup have the following meaning:
jg_old_times_2
Like any module, a unique ID is required to distinguish elements of the same type. In contrast to the markup of the lightbox lightbox::
, this identifier is not freely selectable and must correspond to the ID of the gallery from the configuration of the module.
role="mb-3 wm-800"
As with the lightbox module, the specifications add CSS styles for displaying the element on the page.
It is noticeable that the notation of the markup uses fewer parameters than is the case with the lightbox macro lightbox::
. The reason for this is the outsourcing of the settings to a separate configuration file ~/_data/modules/justifiedGallery.yml
.
jg_old_times_2
# ----------------------------------------------------------------------------
# Old Times 2
#
- gallery:
enabled: true
id: jg_old_times_2
type: image
images_path: /assets/image/modules/gallery/old_times
thumb_path: /assets/image/modules/gallery/old_times
images: [
image_01.jpg, image_02.jpg,
image_03.jpg, image_04.jpg
]
captions_gallery: [
"GrandPa's 80th Birthday",
"GrandPa's 80th Birthday",
"GrandPa's annual journey",
"GrandPa's annual journey"
]
gallery_options:
rowHeight: 200
margins: 5
lightbox_options:
lightbox: lg
mode: lg-fade
cssEasing: cubic-bezier(0.25, 0, 0.25, 1)
As the last step for this section, expand the Asciidoc markup code of the image gallery into the new sandbox document below the dummy text in the second chapter below the Section 1 section.
How do you like the custom sandbox page now?
By adding images, the sandbox page has taken shape. The page has gained some dynamic in the browser but can still be read easily in the source text. The Asciidoc markups remain legible for the author without the website necessarily being called up in the browser. The decisive advantage of the Asciidoc markup language: even complex elements can be written down simple, remain legible, and the meaning stays understood.
Creating content of type post
does not differ from Page type articles. All Asciidoc markup can be used equally for both types without exception. That raises the question: What’s the difference between Post and Pages if it’s not the content?
The difference between the two content types is determined by the methods of generation provided by the Jekyll post-builder engine. The site builder Jekyll describes itself as Blog-Aware. The ability Blog-Aware is intended to describe that the generator offers special procedures for this type of content and offers extended possibilities for processing blog articles.
As already described in the section Content categories, the content type post
is ordered. In other words, unlike articles of type page
, blog posts can be sorted. Things could be sorted by criteria like size, weight, or color. But how do you sort digital content and why?
In the history of the development of web presentations on the Internet, various purposes of use of websites on the World Wide Web (WWW) have emerged. A special group of websites here is news portals. Portals use their methods to make the site’s content, the news, available to the visitors.
A good example of such a news portal is the New York Times. The design of the site is surprisingly simple. The site presents its content, as simple blocks arranged in a sort of arrangement of different sized bricks of a wall. This Mansory Grid layout is particularly suitable if a so-called Portfolio, a collection of content to be presented.
A similar behavior of displaying the collection of blog posts is used by the J1 Theme on the homepage. The appearance of the wall like the stones (blocks) on the side, is completely different for J1 Theme. However, the representations on the NYT portal are comparable to J1.
Another block representation of posts is found in the J1 Blog Navigator on the preview page.
Timeline
Article block
Block header
Block preview
Block footer
An important criterion for arranging messages is the time. An article on the latest James Bond film in cinemas only makes sense if the year the film will be released (timeline) is clear. Each message is displayed in a summary block with a title (header), an excerpt of the respective contribution, and provides additional information in a footer.
The order over time is shown on the homepage in the block Latest News. All articles are shown in reverse order of appearance, so new articles first. The footer shows two additional ordering criteria that are available for blog articles with Jekyll and J1:
Categories — Sorting criterion to group articles by category
Tags — Sorting criterion that provides information about the content of an article
It is also possible to specify categories and tags for pages of the Page type, but the options for automatic evaluation that Jekyll offers for blog articles are missing here.
The practical application of the sorting criteria is explained in more detail in the following section J1 Blog Navigator. |
There are no major differences between posts and pages when it comes to creating the content. However, the organization of content types in a Jekyll project is different. If the items of type page
are placed in the folder pages
, then all items of type post
are created in the directory collections
.
In addition to posts, Jekyll offers the article type collections for ordered content, a kind of content that combines the properties of posts and pages. Collections extends Jekyll’s post and pages publishing functionality, to support other content types that aren’t ordered by date, but have a relationship with one another. Unfortunately, collections are not discussed in this tutorial. You can find a good description to understand collections in the blog of Ben Balter. |
Another major difference to Pages is the structure of the filenames of blog articles. If you were able to assign the names of the articles in Pages freely, a fixed scheme for the names of the source pages must be observed in Posts. To create a post, add the source file to your _posts
directory using the following format for the file name:
YEAR-MONTH-DAY-<title>.adoc
Where the placeholder YEAR
is a four-digit number, the placeholders MONTH
and DAY
are both two-digit numbers. The file extension adoc
represents the content format Ascidoc used in the file. For example, the following are examples of valid post filenames:
2021-01-01-about-cookies.adoc 2021-03-28-welcome-to-j1.adoc
Like like for all pages, blog post files must begin with a Front matter which is typically used to set a layout and other data to control the processing. Note from here, the value for the front matter variable layout
for posts is set to the value post
.
---
layout: post
title: Welcome to Jekyll!
---
== Welcome to Jekyll posts
*Hello world*, this is my first Jekyll blog post.
We hope you like it!
You don’t have to start from a blank page, even with new blog articles. A simple template simple-post
for new blog posts is available in the ~/collections/asciidoc_skeletons
folder.
Name | Description |
---|---|
| Simple documents are used quite often. If the number of chapters is about or less than three and the document is small in size. This document type does not use any (local) Asciidoc include files or attributes. |
By their nature, blog articles are news, which (should) reach a maximum of the size of simple articles of the type pages
in terms of page length. It is conceivable that blog articles on one topic span several articles. A typical use case here is tutorials that are organized as blog articles. You can find out how to group blog articles as a series of posts using the methods of J1 in the Grouping posts section.
Create a new article for the further steps. Like new pages, copy the simple-post
directory to the ~/collections/posts/public
folder and rename the source file. Use for the source of the new blog article in the folder ~/collections/posts/public/simple-post/_posts
the current date, for example:
2022-03-06-new-post.adoc
The template source has the extension .ascidoc , which suppresses the generation of the article because the filename doesn’t match the expected format. All files with a .ascidoc extension are excluded via the site configuration settings in the file ~/_config.yml using the parameter exclude . |
Then customize the front matter of the new post’s source to your liking, for example:
simple-post.adoc
---
layout: post
title: Your first post article
tagline: blog posts from scratch
categories: [ Examples ]
tags: [ Posts, Tutorial ]
---
To start again with an empty structure for the new blog article, overwrite the source’s content with a simple skeleton structure as well.
simple-post.adoc
// Page content
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
// Include sub-documents (if any)
// -----------------------------------------------------------------------------
[[readmore]]
== Chapter 1
lorem:sentences[5]
== Chapter 2
lorem:sentences[5]
As mentioned, the methods of developing Posts content are no different from for Pages. You can make the same adjustments for the new blog article that you already got to know in the Creating pages section for ordinary (article) pages.
Have fun with your experiments with the content of the posts!
Tags and categories are elementary classification criteria for the content type post.
In addition to functions for evaluating the categories, the Jekyll builder engine offers another property: automatic categorization of blog articles. You have already seen the ~collections\posts
directory structure for the post
content-type:
collections
├─ . │ └─ collections (1) │ └─ posts (2) │ └─ private │ └─ protected │ └─ public (3) │ └─ simple-post (3) │ └─ _posts (4)
1 | global content folder collections (ordered content) |
2 | global content folder of the content type post |
3 | category folders |
4 | category content folder _posts |
The folder structure below ~collections\posts
is only used by the template system J1 to organize the articles. However, Jekyll evaluates this folder structure and creates automatic categories, which are assigned to the respective posts. The directory structure that directs the builder engine automatically deducts the following categories:
posts
public
simple post
These automatic categories are automatically assigned to all articles in the respective category content folder. For native Jekyll projects, this is certainly a good way to have categories generated via the builder engine. For the template system, the automatic category mappings are not very helpful. For J1 projects, there are tags on how to explicitly configure categories via the front matter of the articles. The explicit specification is much more flexible and allows the specific assignment of categories according to the authors' ideas, which are independent of the respective storage location of a contribution.
Automatic categories are an integral part of Jekyll and, unfortunately, cannot be switched off. Appropriate settings must be made in the J1 site configuration ~_data/j1_config.yml
to dispense this functionality from Jekyll.
To suppress the evaluation of the layouts via J1, all not desired automatic categories are to be specified manually in the category_blacklist
variable:
category_blacklist
# ==============================================================================
# POST global configuration settings
#
# NOTE: Set global settings for the Jekyll builder-engine to control
# the HTML outputs generated by J1
#
# ------------------------------------------------------------------------------
posts:
# ----------------------------------------------------------------------------
# category_blacklist
# --------------------------------------------------------------------------
# List of categories (automatically) generated by Jekyll to be SKIPPED.
# (Additional) Categories are generated by Jekyl from folder names but
# NOT used for J1 to be displayed in preview boxes or J1 Posts Navigator
# views.
#
# Default: [ posts, public, private, protected, featured, series ]
#
# ----------------------------------------------------------------------------
category_blacklist: [ posts, public, private, protected, featured, series ]
All new blog articles are created using the template system J1 automatically included in all ads for posts. See the J1 Blog Navigator section for details on processing and displaying posts. |
The new blog article was automatically integrated via the Creators Blog preview boxes on the home page:
However, the automatic category simple-post
is evaluated and displayed in the preview box since the entry in the variable category_blacklist
is still missing. Adjust settings in the J1 site configuration ~_data/j1_config.yml
accordingly:
category_blacklist
category_blacklist: [ posts, public, private, protected, featured, series, simple-post ]
You have learned that articles of the content type page
have to be manually integrated via the menu system of the J1 Navigator. The integration of the content of blog articles is fundamentally different. All articles of lead to portfolios, i.e., collections of content managed via the J1 module J1 Blog Navigator. Manual integration is not necessary. The Navigator component manages the content automatically. Available blog articles are automatically adopted and displayed. Comparable to the menu system for simple pages, the J1 Blog Navigator provides views for surfing the content of the generated Portfolios.
The Blog Navigator is accessed via the menu bar via the Blog entry. By opening the entry Blog Explorer in the dropdown menu, you reach the main page of the module with all available portfolio views:
Categories — articles are grouped by category
Date — articles are grouped by date
Archive — all articles available sorted from the youngest to the oldest
portfolio viewers (ordered content)
portfolio preview
The Blog Explorer is very easy to use and intuitive for site visitors. Test the various options that the explorer provides via the portfolio views. The J1 Blog Navigator component can have various parameters be configured as a module. The settings for this are found in the central directory of the module configurations under ~/_data/modules
:
default settings: defaults\blog_navigator.yml
user settings: blog_navigator.yml
In some cases, it may make sense to group blog articles into a group of related articles. The post
layout offers this possibility, controlled via the series
variable in the front matter.
To try out the grouping feature, make a copy of the existing post 2022-03-06-new-post.adoc
in the same directory and give this source file a new name:
2022-03-06-new-post-2.adoc
Then adjust the Front matter of the two articles for the summary as a group. Override the following variables in both articles:
simple-post.adoc
---
layout: post
title: Your first post article
tagline: blog posts from scratch
categories: [ Examples ]
tags: [ Posts, Tutorial ]
image: /assets/image/modules/attics/sigmund-1920x1280.jpg
series: simple-post
regenerate: false
---
simple-post-2.adoc
---
layout: post
title: Your second post article
tagline: blog posts from scratch
categories: [ Examples ]
tags: [ Posts, Tutorial ]
image: /assets/image/modules/attics/sigmund-1920x1280.jpg
series: simple-post
regenerate: false
---
By default, the variable’s value in the front matter of an article is set to false
. Setting the value to false
results that the article does not belong to any group. The articles are grouped by changing the value of the variable series
to simple-post
in the front matter. After the generation is complete, open one of the two articles about the J1 Blog Explorer:
group explorer
menu button
group name
An additional element Group Explorer has been created by processing the J1 templates for the layout post
. Use the menu button to open the Group Selector.
The articles are grouped, and the individual contributions of the group can be selected by clicking on the selector. In principle, any number of articles can be grouped. Nevertheless, limiting a group to 3-6 articles is advisable to not confuse you vistors by huge article groups.
Writing content for the homepage is a bit different in compare to posts and pages. As described in section The Homepage, already existing (or your own) building blocks are used to generate the content of the landing page.
To configure the homepage, the layout data file ~/_data/layouts/home.yml
is used to enable or disable the building blocks used for the landing page. Two examples for custom content are prepared to generate and place them on the homepage:
# ----------------------------------------------------------------------------
# CUSTOM content
#
# Load custom rendered static HTML data files or HTML templates.
#
# NOTE:
#
# For Jekyll, only includes from folder '~/_includes' are accepted
# to load HTML data (include) files from.
#
# ----------------------------------------------------------------------------
#
- lane:
enabled: false
id: custom_content
region: body-main
type: sync
base: _includes/custom
path: static (1)
file: bs5_accordion.html
- lane:
enabled: false
id: custom_content
region: body-main
type: sync
base: _includes/custom
path: templates (2)
file: bs5_accordion.html
1 | already rendered static content based on a HTML file |
2 | configurable (dynamic) content based on a HTML tenplate |
Both examples place the same HTML code. The static version (1) is equivalent to the code generated by the dynamic version (2). That way, it is easy to compare the outcome of configurable (dynamic) content based on a HTML tenplate.
For the development of dynamic content, it is recommended to start by a static version. Developing dynamic content is a iterative process that replaces the static contents by their dynamic conterparts using the Liquid template language. |
If you compare the already existing articles with the pages you created, one thing stands out: The existing pages seem to miss some Front matter variables.
To not repeat frequently used Front matter variables with identical values, it is advised to use default settings. Find the default settings of the Front matter variables with the site configuration /_config.yml
.
Here you define common values and are only overwritten in the sources if necessary. For all articles of content type page
, the variable layout has the default value page
. The default value posts
is set for all articles of content type post
. Default values are configurable for many other variables not to repeat yourselves.
Variable | Description |
---|---|
| The Layout used for a source page. |
| If the builder-engine Jekyll runs in mode incremental, the variable controls if a source is regenerated always ( |
The front matter variable image:
is used to display images. The variable controls the image used in the header-sections for the boxes displayed.
Variable | Description |
---|---|
| Sets the title of a page. Shown in the master header (module attic) and is used for webbrowsers to name the tab or window.. |
| Sets the subtitle of a page. Shown in the master header (module attic) below the title. |
| HTML meta-data key. The data of |
| A list categories used for the source. Categories are displayed in search results for all posts and pages. If the content is of type |
| A list tags used for the source. Tags are displayed in search results for all posts and pages. If the content is of type |
| If the content is of type |
| If set to |
| If set to |
| If the content is of type |
| Enables ( |
| Defines what floating action button should be used fo a page. Valid id’s can be found in the FAB module configuration |
| Enables ( |
The (YAML) Array defaults:
in the site configuration /_config.yml
is responsible for configuring the default values. This array contains (nested) lists scope
and values
consisting of name-value pairs. Sounds difficult at first but is much easier to understand if you look at the configuration.
~/_config.yml
file# ------------------------------------------------------------------------------
# FRONTMATTER defaults
#
# Using the YAML Front Matter is a way the (individual) configuration
# for post and pages can be specified. Very often, a lot of config
# options are repeated on each and every post or page. Setting the
# layout for each file, adding categories to a post, etc. might be
# the same for the majority of your content.
#
# Instead of repeating this configuration each time a page is being
# created, Jekyll provides a way to set these configuration items
# as defaults in this site configuration (_config.yml).
#
defaults:
# ----------------------------------------------------------------------------
# PUBLIC - FEATURED
#
- scope:
path: posts/public/featured
type: posts
values:
layout: post
author: J1 Team
compress: true
# ----------------------------------------------------------------------------
# PUBLIC - SERIES
#
- scope:
type: posts
path: posts/public/series
values:
layout: post
author: J1 Team
compress: true
All configuration files in Jekyll or J1 projects included Data of type YAML . The indentations in the notation of the configuration are not (only) for better readability. Indentation is an integral part of the data structure and must be exactly maintained. |
In the configuration shown, the default values of Posts are declared, with the parameters in the scope
list having the following meaning:
path
— the location (directory) of the content
type
— the corresponding content type (here: post
)
The values
list contains the desired Front matter variables for the default values to be set up. Find a complete list of the configuration for variables and their values for your new blog articles below:
# ----------------------------------------------------------------------------
# PUBLIC - SIMPLE POST
#
- scope:
path: posts/public/simple-post
type: posts
values:
layout: post
author: J1 Team
compress: true
image: /assets/image/modules/attics/joanna-kosinska-1920x1280.jpg
robots:
index: true
follow: true
personalization: false
exclude_from_search: false
series: false
toc: true
fab_menu_id: page_ctrl_simple
scrollbar: false
resource_options:
- toccer:
collapseDepth: 3
Changes to Site configuration settings /_config.yml require a restart of the website. |
Add the settings from above in the configuration file /_config.yml
below the existing settings for posts in the following section:
# ----------------------------------------------------------------------------
# POSTS
#
As a final adjustment to your blog articles, the variables layout
can be deleted from the Front matter settings in the simple-post articles. To activate the changes to the site configuration, the running web must be stopped in the shell (Windows: command prompt) and then restarted afterward.
stopping a running web: (Ctrl+C)
(re)starting a web: j1 site
Knowledge and experience dealing with the front matter will greatly help you on changes for your pages' behavior at runtime quickly and easily. |
By changing more front matter defaults, you can now make further adjustments to the variables in the Front matter. Try out how the changes affect your blog articles!