To create the`.gems` folder on Windows, the environment variables %HOMEDRIVE% and %HOMEPATH% can be used to specify your home directory on Windows.

To Create the`.gems` folder on Unix or Linux,

For a simple change, duplicate the paragraph:

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.

In the webbrowser, the page should has been automatically reloaded and shown like so:

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.

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.

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 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:

Asciidoc attributes (variables) defines:

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.

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.

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.

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:

J1 Theme divides the sections (3) and (4) into more specific parts:

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):

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.

The builder engine Jekyll differentiates between two different categories of content:

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 :

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:

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:

Drop-down menus offer other advantages:

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.

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.

Frequently used Asciidoc Macros for J1 modules used to embed lightboxes or galleries of images are:

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.

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:

The parameters in the Asciidoc markup have the following meaning:

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:

The parameters in the Asciidoc markup have the following meaning:

The lightbox module is quite simple. Only simple Asciidoc variables are required to configure the images.

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:

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:

The macro for embedding an image gallery from the example shown macro for image galleries is:

The parameters in the Asciidoc markup have the following meaning:

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.

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.

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.

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.

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.

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:

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:

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.

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.

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:

Then customize the front matter of the new post’s source to your liking, for example:

To start again with an empty structure for the new blog article, overwrite the source’s content with a simple skeleton structure as well.

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:

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:

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:

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:

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:

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:

Then adjust the Front matter of the two articles for the summary as a group. Override the following variables in both articles:

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:

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.