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¶ ↑
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
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?¶ ↑
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*.¶ ↑
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) forJ1
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} ]
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 ]
Icon Fonts¶ ↑
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
- .result
-
¶ ↑
¶ ↑
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
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
- .result
-
¶ ↑
¶ ↑
//////////
// Include documents // —————————————————————————–
include::{documentsdir}/100_gistblock.asciidoc[]
//////////
Chrome Inline Macro Extension¶ ↑
Unnamed link to Chrome Extensions¶ ↑
chrome://extensions/[]
Named link to Chrome Extensions¶ ↑
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].
-
-