Jekyll One

QuickSearch

J1 Template implements some handy enhancements for the markup language Asciidoc. Providing extensions for a Jekyll theme is a unique feature of Jekyll One template system compared to other Jekyll themes and templates.

All already implemented Asciidoctor extensions you’ll find below.

Most extensions are based on well-documented examples from the Asciidoctor Extensions Lab. To create Asciidoc extensions on your own, it is highly recommended to read the Extensions Section in the Asciidoctor user manual.

Extensions for the markup language Asciidoc were made especially for documents of the Jekyll content type page, but can be used for posts or collections as well.

5-10 Minutes to read

Asciidoc Result Extension

J1 Template adds a simple Javascript based functionality for the View Result Extension to any listing block element listingblock. The extension adds an interactive toggle button VIEW to the output of a listing block placed to the top right of the example box.

If a result block [.result] is placed under a listing block, clicking the toggle button view VIEW displays or hide the content given by the result block.

The View Result Extension is quite helpful for sections discussing code elements.

This example place a button VIEW top right of the example box.

VIEW extension
* displayed always
displayed till clicked, but closed on second click (toggle)

Asciidoc Admonitions

Admonition blocks draw the reader to certain statements by labeling them as priorities displayed in separate blocks. These types of information blocks are called admonitions. The AsciiDoc markuplanguage provides five block types shown by the following examples.

Table 1. Admonition labels
Name Description

NOTE

Additional details on the currently discussed topic that may help the reader to understand the following content better.

TIP

Provides facts that may help the reader to go further or points to additional options available that can be used.

IMPORTANT

Emphasis on what is currently being discussed and provide facts that should be remembered.

WARNING

instructs readers of potential danger, harm, or consequences for the wrong usage.

CAUTION

Advise the reader to act carefully and point to potential risks or trippings.

All colors for all default admonition blocks set to the standard color set. Find available block types and their colors below.

When you want to call attention to a single paragraph, start the first line of the paragraph with the label you want to use. The label must be uppercase and followed by a colon :.

Admonition paragraph syntax
NOTE: Followed by the paragraph text

Set the label as a style attribute on a block when you want to apply an admonition to complex content. The next example shows that admonition labels are commonly set on example blocks. The label must be uppercase when set as an attribute on a block.

Admonition block syntax
[NOTE]
====
The block text (multiline)
====

To add an additional title element on an admonition, place a dot . directly followed by the text of the title.

Admonition block syntax + title
.title text
[NOTE]
====
The block text (multiline)
====
NOTE block

Icon background-color: indigo

TIP block

Icon background-color: green

IMPORTANT block

Icon background-color: orange

WARNING block

Icon background-color: yellow

CAUTION block

Icon background-color: red

Asciidoc Quote elements

Quote elements cite a passage or phrase from a book, speech, or the like, such as authority, illustration, etc. the quote elements are controlled by the following attributes:

attribution

The attribute attribution specifies the name of who the content is attributed to.

information

The attribute information is optional and specifies the general or bibliographical information of the book, speech, play, poem, etc., where the content was drawn from.

Quoted paragraph

If the text element to be quoted is a single line or paragraph, the attribute list quote, attribution, and information [quote, attribution, information] can be placed directly above the text.

Synopsis
[quote, attribution, information]
Quote or excerpt text

A single paragraph can be turned into a blockquote by:

  1. surrounding the quoted paragraph with double-quotes "

  2. adding an optional attribution attribution, prefixed by two dashes -- below the quoted text

Synopsis
"quoted paragraph"
-- attribution
Don’t do stupid things twice. The selection is too big for that.
— Jean-Paul Sartre

Quote block

If the text element, or excerpt, to be quoted is more than one paragraph, place the multine text between delimiter lines consisting of four underscores __.

Synopsis
[quote, attribution]
____
paragraph text (multiline)
____

Example of a quoted block.

Dennis: Oh, what a giveaway! Did you hear that? Did you hear that, eh?
That’s what I’m on about! Did you see him repressing me?

You saw him, Didn’t you?

— Monty Python and the Holy Grail

Lightboxes

To make the use of the built-in lightbox easier, the J1 Template offers an Asciidoc extension: the lightBox block macro. The lightbox block macro lightbox:: embeds one or more images into the output document and puts the default lightbox for J1 automatically on.

The images width and additional a addtional caption text caption text and CSS styles are configurable for all images using this macro.

Lightbox block for single images
.Block title
lightbox::<block_id>[ <images_width>, <images_data_id>, <role="CSS styles"> ]
Lightbox block for image groups
.Block title
lightbox::<block_id>[ <images_width>, <images_data_id>, <group_name>, <role="CSS styles"> ]

The role parameter role to specify additional CSS styles is for all lightbox macros lightbox:: optional and can be omitted.

For a lightbox block, images are placed in the output document without any other scaling than in width - they are placed using simple HTML img tags <img>. This technique is fine for images that are even in size. For images in different sizes, a gallery should be used as a J1 Gallery to rearrange images and make them fit at their best for the available space.

Standalone Images

For your convenience and better readability, the image data should be defined as Asciidoc attributes. The image data is given as a string of data pairs:

Paired attributes
"path/to/image-1, image-caption-1, ..."
Example of an data attribute for a lightbox block
:data-images: "pages/image-1.jpg, Description 1, "pages/image-2.jpg, Description 2"

The base path for all image-related data is a configuration placed in the side-wide project configuration _config.yml and points per default to images path /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 like path-to-image path/to/image.

If an absolute path /path/to/image is configured, the base path gets ignored. This is the default behavior of the Asciidoc Markup processor. If an absolute path is given, the full path to the images used has to be configured.

The group parameter group for the lightbox block lightbox:: is optional. If no group parameter is given for a block, the related images are treated as standalone.

Lightbox block for standalone images
lightbox::<block_id>[ 800, {<data-images-id>} ]
Lightbox block for standalone images
Lightbox block for standalone images

Grouped Images

If more than a single image is given for a lightbox lightbox::, images can be grouped to enable a simple sliding functionality through related images. Enabling this function, the group option group needs to be configured for the block.

Lightbox block for grouped images
lightbox::<block_id>[ 400, {<data-images-group_id>}, <group_name> ]
Lightbox block for grouped images
Lightbox block for grouped images Lightbox block for grouped images

Galleries

JustifiedGallery, the default gallery for J1, is a great jQuery plugin to create responsive, infinite, and high-quality justified image galleries. J1 Template combines the Gallery with the lightboxes supported to enlarge the images of a gallery.

Pictures you’ve made are typically not even in size. Images may have the same resolution, but some are orientated landscapes, or others may be portrait. For that reason, a more powerful gallery is needed to create a so-called masonry grid layout. It works by placing elements in an optimal position based on available horizontal and vertical space.

Gallery macro for images and videos
.Gallery title
gallery::<gallery_id>[role="<additional CSS styles>"]
Image Gallery
Video Gallery

Country flags

Country flags are often used in the context of language-specific selections or for content related to a specific country. The use of country flags can make language selections or country indicators more visual to support your visitors by making a more meaningful presentation.

The J1 Template comes with full support of country flags for Asciidoc documents included.

Country flags can be used as inline icons by using the flag inline macro flag::

flag:country[style, size, modifier]    (1) (2) (3) (4)
1 All country flags can be found on the preview page for country flags
2 The style attribute can be one of: rectangle or squared
3 The size attribute can be one of: xs, sm, md, lg, xl (responsive) and 1x to 10x (proportional)
4 The modifier can be used to add individual CSS classes e.g. for BS styles for margin setting and other
Click on button VIEW to see how it’s looks alike
flag:de[rectangle, 2x, ml-3 mr-2 mb-2] Germany (rectangle) +
flag:de[squared, 2x, ml-3 mr-3 mb-2] Germany (square)

Germany (rectangle)
Germany (square)

Flag Icons is a collection of all country flags in the SVG vector format. All icons can be automatically resized with no loss in display quality.

Table 2. Example of responsive flag sizes
Size Style Markup Render

xs

rectangle

Germany
flag:de[rectangle, xs]

sm

rectangle

Germany
flag:de[rectangle, sm]

md

rectangle

Belgium
flag:be[rectangle, md]

lg

rectangle

Denmark
flag:dk[rectangle, lg]

xl

rectangle

Spain
flag:es[rectangle, xl]

Icon Fonts

The J1 Template comes with full icon support for Asciidoc based documents included. All icon fonts are supported of type:

  • Material Design Icons (MDI)

  • FontAwesome Icons V5 (FA)

  • Iconify-Framework Icons (IF)

Material Designs Icons

Material Designs Icons can be used as inline icons by using the MDI inline macro mdi::

mdi:icon_name[icon_size, modifier]   (1) (2) (3)
1 All icon_name can be found on the preview page for MDI Icon Previewer
2 The icon_size attribute can be one of: xs, sm, lg and 1x to 10x
3 The modifier can be used to set the e.g the color (md-blue), an animation (fa-pulsed) or the orientation (fa-rotate-45)
Click on the VIEW button VIEW to see how it’s looks alike
mdi:home[2x, mdi-pulsed ml-3 mr-2 mb-2] Symbol icon (pulsed) +
mdi:font-awesome[2x, ml-3 mr-2 mb-2] Brand icon +
mdi:apple[2x, md-indigo ml-3 mr-2] Brand icon (colored)

Symbol icon (pulsed)
Brand icon
Brand icon (colored)

Parameters for icon size icon_size and modifiers modifier are optional. If not given, the icons size size is set to default 1x, the color to black and no settings for modifiers modifier are applied.

FontAwesome Icons V5

Font Awesome Icons can be used as inline icons by using the macro fas fas: for standard icons or the macro fab fab for brand icons.

fas:icon_name[icon_size, modifier]   (1) (2) (3)
1 All icon_name can be found on the preview page at FA Icons
2 The icon_size attribute can be one of: xs, sm, lg and 1x to 10x
3 The modifier can be used to set e.g the color (md-blue), an animation (fa-pulsed) or the orientation (fa-rotate-45) of an icon
Click on button VIEW to see how it’s looks alike
fas:home[2x, fa-pulsed ml-2 mr-2 mb-2] Solid icon (pulsed) +
fab:font-awesome[2x, ml-3 mr-2 mb-2] Brand icon +
fab:apple[2x, md-indigo ml-3 mr-2] Brand icon (colored)

Solid icon (pulsed)
Brand icon
Brand icon (colored)

Parameters for icon size icon_size and modifiers modifier are optional. If not given, the icons size is set to default 1x, the color to black and no settings for modifiers modifier are applied.

Iconify-Framework Icons

Iconify-Framework Icons can be used as inline icons by using the inline macro iconify:.

iconify:icon_name[icon_size, modifier]   (1) (2) (3)
1 All icon_name can be found on the preview page at Iconify Icons
2 The icon_size attribute can be one of: xs, sm, lg and 1x to 10x
3 The modifier can be used to set e.g the color (md-blue) or additional positioning classes for margings and padding

Click on the VIEW button VIEW to see how it’s looks alike

Brand Icon Open Source
iconify:logos:opensource[2x, mr-3 mb-3 ml-4] Brand Icon Open Source

Brand Icon Open Source

Brand Icon Netlifyy
iconify:logos:netlify[2x, mr-3 mb-3 ml-4] Brand Icon Netlify

Brand Icon Netlify

Find all Iconify-Framework Icons available on page Iconify-Framework Icons.

Parameters for icon size icon_size and modifiers modifier are optional. If not given, the icons size is set to default 1x, the color to black and no settings for modifiers modifier are applied.

Note that not all icon sets support the color settings for modifiers — if applied, the color settings will have no effect.

Blind Text

The Ruby GEM Middleman, a very simple and light-weight static site generator, provides a set of great helpers for generating random text content. The lorem inline macro lorem: adapted this functionality from Middleman to be used for Asciidoc-based documents processed by Jekyll.

If you start writing larger documents with several chapters, not all of the content is available initially. It is quite useful to place blind text first to get a better impression of how a page will look-alike that is not finished yet.

Placeholders for blind text comes in several flavors given by their name macro. The syntax for the lorem inline macro lorem: is simple like this:

lorem:macro[]
lorem:macro[size]
Example of a lorem sentences macro
lorem:sentences[5]

Aperiam molestias accusantium ut delectus saepe quam modi. Minus est inventore perspiciatis et est nesciunt dolorem sunt aliquid vel. Non ea est cum nemo nihil dignissimos. Et iste deserunt eveniet. Nesciunt doloribus cum iste officiis nobis suscipit.

Lorem Types

All macro types available for the lorem macro lorem: to be used for blind text can be found with the following table below.

Table 3. Macros available
Macro Type Example

word[]

text

vel

words[5]

text

et dicta dolore expedita aut

sentence[]

text

Voluptatibus nihil reprehenderit sint non laborum ex.

sentences[5]

text

Libero voluptas voluptas quia non est et cum dicta. Officiis recusandae quia non iste laudantium. Est mollitia quas atque qui. Qui voluptate quisquam velit quaerat. Molestias nisi quibusdam maxime eos nihil reprehenderit labore.

date[]

date

Tue Mar 09, 1965

date[strftime] e.g. date[%Y-%m-%d]

date

1992-03-24

name[]

text

Clinton Chung

first_name[]

text

Earl

last_name[]

text

Heath

email[]

email

caraallen@gmail.com

Github Gist

Code snippets may helpful to support your readers for existing code examples. An excellent place for code snippets is at Github. To embed an existing gist into your documents, the Asciidoc Extention Gist block provides the block macro gist:: to do so.

The following Gist snippet is taken from this example:

.Gist title
gist::git_address[]
Example of a gist block
.Guard setup to live preview AsciiDoc output
gist::mojavelinux/5546622[]
Guard setup to live preview AsciiDoc output

What next

Asciidoc extensions open up advanced possibilities for placing specific content elements on a page. The number of available extensions will grow. Extensions for Asciidoc gives handy and powerful functionality needed for modern web pages.

Asciidoc extensions are available for all content pages based on the Markup Language Asciidoc created for J1 Template. For content pages based on Markdown, extensions are not supported.

J1 Template supports a rich set of advanced Bootstrap Modals that add dialogs to your web pages for user notifications. The advanced Modals highlight important information to your visitors. The dialogs are positioned over everything else in the document so that messages get the full user’s attention.

Have a look at the preview page Advanced Bootstrap Modals to explore the possibilities of the extended Bootstrap features provided by J1 Template for your new website.