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.
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:
Name | Description |
---|---|
| Additional information on the currently discussed topic that may help the reader |
| Additional information on the currently discussed topic that may help the reader to go further or describe additional options available |
| Emphasis on what is currently being discussed and facts that should be kept in mind |
| Advise the reader to act carefully and point to potential tripping |
| 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 (:).
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.
[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.
.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.
[quote, attribution, information]
Quote or excerpt text
Example of a quoted paragraph:
Everybody remember where we parked.
Star Trek IV: The Voyage Home
A single paragraph can be turned into a blockquote by:
-
surrounding the quoted paragraph with double-quotes (")
-
adding an (optional)
attribution
, prefixed by two dashes (--) below the quoted text
"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.
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 (__).
[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?
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.
.block_title
lightbox::<block_id>[ <images_width>, <images_data_id>, <role="<additional CSS styles>"> ]
.block_title
lightbox::<block_id>[ <images_width>, <images_data_id>, <group_name>, <role="<additional CSS styles>"> ]
The For a |
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:
"path/to/image-1, image-caption-1, ..."
: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_id>[ 800, {<data-images-id>} ]
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_id>[ 400, {<data-images-group_id>}, <group_name> ]
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.
.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 |
VIEW
to see how it’s looks alikeflag: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.
Size | Style | Markup | Render |
---|---|---|---|
| rectangle | Germany
| |
| rectangle | Germany
| |
| rectangle | Belgium
| |
| rectangle | Denmark
| |
| rectangle | Spain
|
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) |
VIEW
to see how it’s looks alikemdi: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 |
VIEW
to see how it’s looks alikefas: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 |
VIEW
to see how it’s looks alikeiconify: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 Not all icon sets support the color settings for the |
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]
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 |
---|---|---|
| text | nulla |
| text | necessitatibus recusandae distinctio dicta nihil |
| text | Ut accusamus sed dolor deserunt veritatis quis laboriosam. |
| 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 | Tue Sep 12, 1989 |
| date | 1966-08-21 |
| text | Alberto West |
| text | inley |
| text | Sutton |
|
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 |
.Guard setup to live preview AsciiDoc output
gist::mojavelinux/5546622[]
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.