J1 Theme implements some handy Ruby-based extensions 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 alwaysdisplayed 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 textSet 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
attributionspecifies the name of who the content is attributed to - information
-
The attribute
informationis 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 textExample 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"
-- attributionI 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
Voluptatem enim vel et eius nulla quos. Ullam in incidunt voluptatem fugit tenetur quas quas doloribus. Voluptas voluptatem velit ab veniam animi est iure unde illo fugit et quo. Quia possimus vel ut veritatis ea. Ullam maiores eius necessitatibus nihil sit omnis dolorem vel rem deleniti reprehenderit distinctio cum placeat.
Video galleries
Impedit sed fugiat quo culpa tenetur ad voluptatibus facere voluptas non et beatae nam eos. Quo animi et magnam porro unde sequi. Fuga nisi officia numquam aut mollitia quas est qui similique eum dolorem rem occaecati voluptatem. Et minima aliquam qui dolores ex et facere blanditiis placeat esse. Molestiae illum accusantium vero.
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]Consequatur officia debitis minima quia inventore. Fuga et sunt nihil non et quos qui id non error. Voluptatem nesciunt iure iste inventore eos odio aut magnam necessitatibus blanditiis in. Necessitatibus quis sed dolorem ut. Eaque eos ex aut cum ut dolorum sed fugiat qui voluptatem sit nemo reprehenderit nesciunt.
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 | natus |
| text | et illo fuga ea natus |
| text | Impedit natus quibusdam incidunt quidem quia. |
| text | Amet eaque culpa suscipit ea enim iste sunt suscipit et enim. Laborum molestiae nam suscipit reiciendis culpa cupiditate qui quia. Libero sapiente voluptatem quaerat et. Quo neque nisi ad quas et consequuntur sit non fugiat necessitatibus recusandae voluptatem consequatur consequatur. Pariatur omnis error iusto impedit neque eum id vitae minima tenetur necessitatibus. |
| date | Thu Dec 26, 1991 |
| date | 1984-07-07 |
| text | George Chen |
| text | Kerry |
| text | Chen |
|
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!
The next preview is focussing on advanced Bootstrap Modals. The modals feature is currently in beta status, but it is a great option to customize your user dialogues using them!
Have a look for the Modal Extensions feature of J1 Theme.