Jekyll One

J1 Theme implements some handy Ruby-based enhancements for Asciidoctor. Providing extensions for a Jekyll theme is a unique feature of JekyllOne compared to other Jekyll themes and templates. All already implemented Asciidoctor extensions you’ll find below. Additional valuable extensions to the markup language Asciidoc is made especially for documents of the Jekyll content type pages, but can be used for posts or collections as well.

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.

Asciidoc Result Extension

J1 Theme adds a simple Javascript based on the View Result Extension to any listingblock. The extension adds an interactive toggle button VIEW to the output of an Asciidoc listing block box placed to the top right of the example box. If a result block [.result] is placed under a listingblock, clicking the toggle button VIEW displays (or hide) the content given by the result block.

The View Result Extension is quite helpful for sections discussing Asciidoc code and how the resulting (HTML) code would look alike.

This example place a button VIEW top right of the example box
* displayed always
displayed till clicked, but closed on second click (toggle)

Asciidoc Admonitions

Admonition blocks draw attention to certain statements by taking them out of the content’s flow and labeling them as priorities. These types of (Asciidoc) blocks are called admonitions. The AsciiDoc language provides five admonition types represented by the following labels:

Table 1. Admonition labels
Name Description

NOTE

Additional information on the currently discussed topic that may help the reader

TIP

Additional information on the currently discussed topic that may help the reader to go further or describe additional options available

IMPORTANT

Emphasis on what is currently being discussed and facts that should be kept in mind

CAUTION

Advise the reader to act carefully and point to potential tripping

WARNING

inform the reader of danger, harm, or consequences that exist

All colors for all default admonition blocks set to the standard MD 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 (.) markup directly followed (no spaces) by the text of the title.

Admonition block syntax and additional 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, information] can be placed directly above the text.

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

Example of a quoted paragraph:

Everybody remember where we parked.
— Captain James T. Kirk
Star Trek IV: The Voyage Home

A single paragraph can be turned into a blockquote by:

  1. surrounding the quoted paragraph with double-quotes (")

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

Synopsis
"quoted paragraph"
-- attribution
I hold it that a little rebellion now and then is a good thing, and as necessary in the political world as storms in the physical.
— Thomas Jefferson
Papers of Thomas Jefferson: Volume 11

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: Come and see the violence inherent in the system. Help! Help! I’m being repressed!

King Arthur: Bloody peasant!

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

A Lightbox is, in general, a helper which displays enlarged, almost screen-filling versions of images (or videos) while dimming the remainder of the page. The technique, introduced by Lightbox V2, gained widespread popularity thanks to its simple style. The term lightbox has been employed since then for Javascript libraries to support such functionality.

To make the use of the built-in lightbox easier, the J1 Theme offers an Asciidoc extension: the lightBox block macro. The block macro lightbox:: embeds one or more images into the output document and puts the default lightbox for J1 automatically on. The images size (width) and additional caption text and additional 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="<additional CSS styles>"> ]
Lightbox block for image groups
.block_title
lightbox::<block_id>[ <images_width>, <images_data_id>, <group_name>, <role="<additional CSS styles>"> ]

The role parameter to specify additional CSS styles is for all lightbox:: macros 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. 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 Apps 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 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.

If an absolute path is configured, like /path/to/image, 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 parameter group for the lightbox:: block is an option. 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:: block, the images can be grouped to enable a simple sliding functionality through this group of related images. Enabling this function, the 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 Theme 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 size (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. Sort of like mason fitting stones in a wall.

Gallerie macro for images and videos
.block_title
gallery::<gallery_id>[role="<additional CSS styles>"]

Image galleries

Accusantium dolore nisi sint est occaecati et animi quidem iure corrupti consequuntur quidem. Ex perferendis in impedit corrupti adipisci quaerat dignissimos ut. Consequatur ut eos illo eum deserunt facilis ut sit. Unde quia dignissimos optio magnam aliquid fuga. Consequatur magnam consequuntur sint repellat eos neque in non quibusdam.

Video galleries

Et at eum eos iusto. Aut cumque facilis cupiditate ut est et a. Sint quisquam et quis iure doloremque saepe asperiores. Omnis amet incidunt placeat ab consequatur facere sunt et excepturi. In eum sint officiis voluptate minima atque consequatur corporis.

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 Theme 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: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 flag sizes (responsive)
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 Theme comes with full icon support for Asciidoc documents included. All icon fonts are supported:

  • FA (FontAwesome)

  • MDI (MaterialDesign icons)

  • Iconify

Material Designs Icons

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

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 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 icon_size and modifier are optional. If not given, the icons size is set to default (1x), the color to black and no settings for the modifier are applied.

Font Awesome Icons

Font Awesome Icons can be used as inline icons by using the fas: (solid icons) or fab (brand icons) inline macro:

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 icon_size and modifier are optional. If not given, the icons size is set to default (1x), the color to black and no settings for the modifier are applied.

Iconify Icons

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

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 button VIEW to see how it’s looks alike
iconify:logos:opensource[2x, ml-4 mr-2 mb-2] Brand icon OpenSource  +
iconify:logos:netlify[2x, ml-4 mr-2 mb-2] Brand icon Netlify +
iconify:simple-icons:netlify[2x, md-red ml-4 mr-2] Brand icon Netlify

Brand icon OpenSource
Brand icon Netlify
Brand icon Netlify, colored

Find all Iconify Icons available on page Iconify Icon Sets.

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

Not all icon sets support the color settings for the modifier. If applied, the color settings will have no effect.

Blind Text (Lorem)

The Ruby Gem Middleman, a Ruby-based 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 use 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 macro. The syntax for the lorem: inline macro is simple like this:

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

Accusamus reiciendis aut rerum ratione perferendis rerum voluptatum possimus asperiores odit in provident. Perferendis officiis ducimus adipisci tempora voluptas velit tempore eius ullam. Maiores aut enim labore modi quia accusantium voluptas enim distinctio inventore. Nihil est distinctio neque temporibus alias velit aliquam perferendis. Maiores laborum necessitatibus voluptatem quam doloremque voluptates aut perspiciatis.

Lorem Types

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

Macro Type Example

word[]

text

nulla

words[5]

text

necessitatibus recusandae distinctio dicta nihil

sentence[]

text

Ut accusamus sed dolor deserunt veritatis quis laboriosam.

sentences[5]

text

Recusandae aut quos voluptatibus sequi maxime similique amet quam facilis sit velit repellat vel. Earum neque voluptatibus ut consectetur cumque a magnam ad ad inventore harum et voluptatem. Voluptate id nisi esse quia commodi aut dolorum sed odit esse minima accusamus sapiente itaque. Quo eos aut necessitatibus deleniti deserunt. Dolorem illo ex suscipit repellendus qui in ut eius.

date[]

date

Tue Sep 12, 1989

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

date

1966-08-21

name[]

text

Alberto West

first_name[]

text

inley

last_name[]

text

Sutton

email[]

email

ana-chung@fastmail.com

Github Gist

Code snippets may helpful to support your readers for existing code examples. An excellent place for code snippets is Gist 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 {asciidoc-extensions-gist-example}[this example, window="_blank"]:

.Gist title
gist::git_address[] (1)
1 For git_address, {github-gist-home}[, window="_blank"] is prepended automatically
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 (Asciidoctor) extensions open up the Markup language to new use cases. Using the full power of programming languages to extend what’s needed, whether Ruby, Java, Groovy, or JavaScript. The number of extensions will grow - to get handy and powerful functionality needed for modern web pages based on the Asciidoc Markup language generated by Jekyll. For sure.

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

The next preview is focussing on advanced Bootstrap Modals, a great option to customize your user dialogues using them!

Have a look for the Modal Extensions feature of J1 Theme.