title: Roundtrip tagline: Asciidoctor Extensions description: Asciidoctor Extensions

tags: [ Template, Roundtrip, Asciidoc, Extensions ] index: [] categories: [ pages ]

permalink: /pages/public/start/roundtrip/asciidoc_extensions/ regenerate: true

resources: [ lightbox ] resource_options:

- masthead:
    opacity:                          0.5
    slides:
      - url:                          /assets/images/pages/roundtrip/puzzle-1280x600.jpg
        alt:                          puzzle-1280x600

// Enable the Liquid Preprocessor // —————————————————————————– :page-liquid:

// Set other global page attributes here // —————————————————————————–

// Load Liquid procedures // —————————————————————————– {% capture set_env_entry_document %}themes/{{site.template.name}}/procedures/global/set_env_entry_document.proc{%endcapture%}

// Initialize entry document environmental attributes // —————————————————————————– {% include {{set_env_entry_document}} init_folders=all %}

// Load tag, url and data attributes // —————————————————————————– include::{includedir}/attributes.asciidoc include::{includedir}/attributes.asciidoc include::{includedir}/attributes.asciidoc

// Set local page attributes // —————————————————————————–

// MAIN // =============================================================================

J1 Template implements some incubating Ruby-based extensions for Asciidoctor. Most extensions are based on the examples given with the {asciidoctor-extensions-lab}[Asciidoctor Extensions Lab, window=“_blank”]. If you simply want to use the extensions from this repository, go ahead to {asciidoctor-extensions-use-extension}[Using an extension, window=“_blank”].

To create extensions on your own, it is highly recommended to read first the {asciidoctor-user-manual-extensions}[extensions section, window=“_blank”] in the Asciidoctor user manual.

All *already implemented* Asciidoctor Extensions can be found below. A set of additional useful extensions to the Markup language Asciidoc are made especially for documents of the Jekyll content type pages (but can be used for post or collections as well).

Asciidoc Extensions

lorem:sentences

lorem:sentences

Asciidoc Code

J1 Template 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 *listingblock 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 useful for example sections discussing Asciidoc code and how the resulting (HTML) code would look alike.

source, adoc

.This will have a button `VIEW` placed to the right top of the example box
----
* displayed always
* displayed always 2
----

[.result]
====
* displayed till clicked
* displayed till clicked 2
====

.This example will have a button `VIEW` placed to the top right of the example box


  • displayed always


.result

  • displayed till clicked, but closed automatically after *5 seconds*

NOTE: The result block closes automatically after the result was shown for *5 seconds*. If the button `VIEW` is clicked, the result box toggles between open and close (the result gets hidden). That way, you can *open and close* the result box *at any time*.

Asciidoc Admonitions

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

.NOTE block NOTE: Icon background-color: indigo

.TIP block TIP: Icon background-color: green

.IMPORTANT block IMPORTANT: Icon background-color: orange

.WARNING block WARNING: Icon background-color: yellow

.CAUTION block CAUTION: Icon background-color: red

lorem:sentences

Q&A Blocks

*Q&A sections* are used quite often to answer popular questions. To make such a Q&A section more eye-minded, the additional Admonition Blocks `[QUESTION]` and `[ANSWER]` are available for J1 Template as Asciidoctor extentions.

Question block

The admonition *Question block* is an extention to the Asciidoc admonition block types that introduce an admonition of type question.

.Example of a question block

source, adoc, role=“noclip”

QUESTION

What's the main tool for selecting colors?


.result

.QUESTION

QUESTION

What's the main tool for selecting colors used for J1 Template?

lorem:sentences

Answer block

The Admonition *Answer block* is an extention to the Asciidoc admonition block types that introduce an admonition type of answer in conjunction to the admonition of type question.

.Example of a answer block

source, adoc, role=“noclip”

ANSWER

For J1 Template, go for for the Core documentation section. You'll find the full color scheme for Material Design.


.result

.ANSWER

ANSWER

For J1 Template, go for the {jekyll-one-core-doc-color-scheme}[Core documentation, window=“blank”] section. You'll find the full color scheme for *Material Design*.

lorem:sentences

Lightboxes

To make the use of the built-in Lightbox easier, J1 Template offers an Asciidoc extension: the LightBox block macro. The `lightbox::` block macro embeds one or more images into the output document and puts automatically the default Lightbox (lightbox) for J1 on. For all images, the `size` (width) and individual `caption text` can be configured.

.Lightbox Block

source, adoc, role=“noclip”

.block_title lightbox::block_id[ images_width, images_data [, group_name] ]


NOTE: 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 is fine for images *even in size*. For images in different sizes, a gallery should be used as gallery (apps) rearrange images to make them fit at its 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 relativ path needs to be given for `path/to/image`.

WARNING: If an absolute path is configured, like `/path/to/image`, the base path gets ignored - this is the default behaviour 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

source, adoc, role=“noclip”

lightbox::images-standalone[ 400, {data-images-standalone} ]


.Lightbox block for standalone images lightbox::images-standalone[ 400, {data-images-standalone} ]

lorem:sentences

Grouped Images

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

.Lightbox block for grouped images

source, adoc, role=“noclip”

lightbox::images-group[ 400, {data-images-group}, group_name ]


.Lightbox block for grouped images lightbox::images-group[ 400, {data-images-group}, group_name ]

lorem:sentences

Icon Fonts

lorem:sentences

Material Designs Icons

J1 Template comes with MDI icon support for Asciidoc documents included. *Material Designs Icons* can be used as inline icons by using the `mdi:` inline macro like so:

source, adoc, role=“noclip”

Your text 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 _view result_ to see how it's looks alike


Macro mdi: mdi:account[2x, md-blue mdi-pulsed ml-3] Macro mdi: mdi:font-awesome[2x, md-indigo ml-3] Macro mdi: mdi:font-awesome[3x, md-indigo ml-3]


.result

Macro mdi: mdi:account[2x, md-blue mdi-pulsed ml-3]

Macro mdi: mdi:font-awesome[2x, md-indigo ml-3]

Macro mdi: mdi:font-awesome[3x, md-indigo ml-3]

Find all MDI Icons on page {previewer-mdi}[MDI Icon Previewer, window=“_blank”].

NOTE: 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

J1 Template comes with FA icon support for Asciidoc documents included. *Font Awesome Icons* can be used as inline icons by using the `fas:` (solid icons) or `fab` (brand icons) inline macro like so:

source, adoc, role=“noclip”

Your text fas:icon_name[icon_size, modifier] <1> <2> <3>


<1> All `icon_name` can be found on the Preview page for *FA 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 _view result_ to see how it's looks alike


Solid icon: fas:account[2x, md-blue fa-pulsed ml-3]

Brand icon: fab:font-awesome[2x, md-indigo ml-3]

Brand icon: fab:font-awesome[3x, md-indigo ml-3]


.result

Solid icon: fas:user[2x, md-blue fa-pulsed ml-3]

Brand icon: fab:font-awesome[2x, md-indigo ml-3]

Brand icon: fab:font-awesome[3x, md-indigo ml-3]

NOTE: 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.

Twitter Emoji Icons

J1 Template comes with *Twitter Emoji* V1 support for Asciidoc documents included. Twitter Emoji's can be used as inline icons by using the `emoji:` inline macro like this:

source, adoc

Your text emoji:icon_name <1> <2>


<1> All `icon_name` can be found on the Preview page for *Twitter Emoji's* <2> The `icon_size` attribute can be one of: `xs`, `sm`, `lg` and `1x` to `5x`

.Click on _view result_ to see how it's look alike


Faster than a emoji:turtle!

This is an example of how you can emoji:heart[2x, pulsed] Asciidoctor and Twitter Emoji emoji:smile[].


.result

Faster than a emoji:turtle!

This is an example of how you can emoji:heart[2x, pulsed] Asciidoctor and Twitter Emoji emoji:smile[].

Find all Twitter Emoji's build-in with J1 Template on page {previewer-emoji}[Emoji Icon Previewer, window=“_blank”].

Blind Text (Lorem)

The Ruby gem Middleman, a Ruby-gem based static site generator, provides a set of powerful helpers for generating *random text* content. The Lorem inline macro `lorem:` adapted this functionality from Middleman for the use of Asciidoc-based documents processed by Jekyll.

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

Placeholders for *blind text* comes in several flavours given by `macro`. The syntax for the `lorem:` inline macro is simple like this:

source, adoc

lorem:macro[] lorem:macro


.Example of a lorem sentences macro


lorem:sentences


.result

lorem:sentences

Lorem Types

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

//.Tabelle

cols=“5,2,5a”, options=“header”, role=“table-responsive mb-2”

|=============================================================================== |Macro | Type |Example

|`word[]` |text | lorem:word[]

|`words` |text | lorem:words

|`sentence[]` |text | lorem:sentence[]

|`sentences` |text | lorem:sentences

|`date[]` |date | lorem:date[]

|`date` e.g. `date“ |date | lorem:date

|`name[]` |text | lorem:name[]

|`first_name[]` |text | lorem:first_name[]

|`last_name[]` |text | lorem:last_name[]

|`email[]` |email | lorem:email[]

|===============================================================================

NOTE: The Lorem extention is currently available as inline macros only. With the upcoming versions of J1 Template, the functionality will be extended.

//////////

Image Blocks

image

lorem:image

image::asciidoctor.org/images/octocat.jpg[GitHub mascot]

Like *blind text*, placeholder images might be useful for unfinished documents. If images are used for the content but not available, blind images can help to organize a page without the final image data.

.All block types available to be used for blind images

cols=“5,2,5a”, options=“header”, role=“table-responsive mb-3”

|=============================================================================== |Block | Type |Example

|`image` |image | lorem:image

|`image['300x400', :background_color => '333', :color => 'fff']` |image | lorem:image['300x400', :background_color => '333', :color => 'fff']

|`image['300x400', :random_color => true]` |image | lorem:image['300x400', :random_color => true]

|`image['300x400', :text => 'new text']` |image | lorem:image['300x400', :text => 'new text']

|===============================================================================

NOTE: Not all formats are available for the image macro. With the upcoming versions of J1 Template, the functionality will be extended.

.Example of an Lorem image block


lorem:image


.result

lorem:image

//////////

// Include documents // —————————————————————————–

include::{documentsdir}/100_gistblock.asciidoc[]

//////////

Chrome Inline Macro Extension

lorem:sentences

Unnamed link to Chrome Extensions

lorem:sentences

chrome://extensions/[]

Named link to Chrome Extensions

lorem:sentences

chrome://extensions/ //////////

What's next?

Asciidoc, respectively Asciidoctor, extensions open up the Markup language to new use cases; using the full power of programming languages to extend what's needed whether it be Ruby, Java, Groovy or JavaScript.

The number of extensions will grow - to get handy and powerful functionality that is needed for modern Web pages based on the Asciidoc Markup language generated by Jekyll. For sure!

The next preview is focussing extended Bootstrap Modals. The modals feature is currently in beta status, but it is a great option to customize your user dialogs using them!

Have a look for the {roundtrip-extended-modals}[Extended BS Modals feature of J1 Template].