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.
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.
* 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.
Name | Description |
---|---|
| Additional details on the currently discussed topic that may help the reader to understand the following content better. |
| Provides facts that may help the reader to go further or points to additional options available that can be used. |
| Emphasis on what is currently being discussed and provide facts that should be remembered. |
| instructs readers of potential danger, harm, or consequences for the wrong usage. |
| 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 :
.
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 .
directly followed 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, and information [quote, attribution, information]
can be placed directly above the text.
[quote, attribution, information]
Quote or excerpt text
A single paragraph can be turned into a blockquote by:
-
surrounding the quoted paragraph with double-quotes
"
-
adding an optional attribution
attribution
, prefixed by two dashes--
below the quoted text
"quoted paragraph"
-- attribution
Don’t do stupid things twice. The selection is too big for that.
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: 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
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.
.Block title
lightbox::<block_id>[ <images_width>, <images_data_id>, <role="CSS styles"> ]
.Block title
lightbox::<block_id>[ <images_width>, <images_data_id>, <group_name>, <role="CSS styles"> ]
The role parameter 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 |
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 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 |
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_id>[ 800, {<data-images-id>} ]
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_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 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 title
gallery::<gallery_id>[role="<additional CSS styles>"]
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 |
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 Template comes with full icon support for Asciidoc based documents included. All icon fonts are supported of type:
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) |
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 for icon size |
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 |
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 for icon size |
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
iconify:logos:opensource[2x, mr-3 mb-3 ml-4] Brand Icon Open Source
Brand Icon Open Source
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 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]
lorem:sentences[5]
Autem repellat est et ut qui qui quo. Ea modi molestiae qui. Rerum expedita aut est dolore sint voluptas. Nostrum consequatur minus officia qui aut aut ut aut est. Deleniti pariatur quibusdam fugit quia autem reprehenderit ut est dolores itaque dolor quis.
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.
Macro | Type | Example |
---|---|---|
| text | enim |
| text | nemo repudiandae aperiam laborum voluptatem |
| text | Earum aut nisi aliquam aliquam id suscipit in velit enim illum est repellendus. |
| text | Ipsa nam porro at consequatur voluptate id sit doloribus a voluptatem vel sunt non. Aut animi est eos facere provident ea in provident non magni sit vitae qui fugit. Nesciunt delectus ullam expedita provident magni eos voluptas. Velit sunt aperiam repellat odio est pariatur. Aut in debitis necessitatibus minus similique doloribus libero aliquam minus est ut minus. |
| date | Tue Aug 05, 2008 |
| date | 2008-11-01 |
| text | Kerry Davis |
| text | Xena |
| text | Marsh |
|
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[]
.Guard setup to live preview AsciiDoc output
gist::mojavelinux/5546622[]
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.