--- title: Roundtrip tagline: asciidoc extensions description: Asciidoc Extensions (asciidoctor) tags: [ Page, Roundtrip ] index: [ Template, Roundtrip, Asciidoc, Asciidoctor, Extensions ] categories: [ pages ] permalink: /pages/public/learn/roundtrip/asciidoc_extensions/ regenerate: false resources: [ lightbox, iconify, twemoji ] resource_options: - attic: padding_top: 400 padding_bottom: 50 opacity: 0.5 slides: - url: /assets/images/pages/roundtrip/puzzle-1920x1280-bw.jpg alt: puzzle-1920x1280-bw # badge: # type: unsplash # author: Harpal Singh # href: https://unsplash.com/@aquatium --- // Enable the Liquid Preprocessor // ----------------------------------------------------------------------------- :page-liquid: // Set other global page attributes here // ----------------------------------------------------------------------------- //:my-asciidoc-attribute: // 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}} %} // Load tag, url and data attributes // ----------------------------------------------------------------------------- include::{includedir}/attributes.asciidoc[tag=tags] include::{includedir}/attributes.asciidoc[tag=urls] include::{includedir}/attributes.asciidoc[tag=data] // Set local page attributes // ----------------------------------------------------------------------------- // :images-dir: {imagesdir}/path/to/page/images // Page content // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ // Include sub-documents // ----------------------------------------------------------------------------- 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}]. If you simply want to use the extensions from this repository, go ahead to {asciidoctor-extensions-use-extension}[Using an extension, {window}]. To create extensions on your own, it is highly recommended to read first the {asciidoctor-user-manual-extensions}[extensions section, {window}] in the *Asciidoctor* user manual. == Asciidoc Extensions 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 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) 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} ] === 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 J1 Template comes with full icon support for Asciidoc documents included. All icon fonts are supported: * FA (FontAwesome) * MDI (MaterialDesign icons) * Iconify * Twitter Emoji == Material Designs Icons *Material Designs Icons* can be used as *inline* icons by using the `mdi:` inline macro: [source, adoc, role="noclip"] ---- 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 ---- mdi: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) ---- [.result] ==== mdi: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) ==== Find all MDI Icons on page link:{previewer-mdi}[MDI Icon Previewer, {window}]. 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 *Font Awesome Icons* can be used as *inline* icons by using the `fas:` (solid icons) or `fab` (brand icons) inline macro: [source, adoc, role="noclip"] ---- 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 e.g the color (md-blue), an animation (fa-pulsed) or the orientation (fa-rotate-45) of an icon .Click on _view result_ to see how it's looks alike ---- fas: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) ---- [.result] ==== fas: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) ==== 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. == Iconify Icons *Iconify Icons* can be used as *inline* icons by using the `iconify:` inline macro: [source, adoc, role="noclip"] ---- iconify: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 e.g the color (md-blue) or additional positioning classes for margings and padding .Click on _view result_ to see how it's looks alike ---- iconify: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* ---- [.result] ==== iconify:logos:opensource[2x, ml-4 mb-2] Brand icon *OpenSource* + iconify:logos:netlify[2x, ml-4 mb-2] Brand icon *Netlify* + iconify:simple-icons:netlify[2x, md-red ml-4] Brand icon *Netlify*, colored ==== Find all Iconify Icons available on page link:{iconify-icon-sets}[Iconify Icon Sets, {window}]. [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. Not *all* icon sets support the color settings for the `modifier`. If applied, the color settings will have *no* effect. ==== == Twitter Emoji Icons Twitter Emoji's can be used as *inline* icons by using the `emoji:` inline macro: [source, adoc] ---- emoji:icon_name[icon_size] <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 ---- This is an example of how you can emoji:heart[2x, pulsed mt-1] Asciidoctor and Twitter Emoji emoji:smile[]. ---- [.result] ==== This is an example of how you can emoji:heart[2x, pulsed mt-1] Asciidoctor and Twitter Emoji emoji:smile[]. ==== Find all Twitter Emoji's build-in with J1 Template on page link:{previewer-emoji}[Emoji Icon Previewer, {window}]. == 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[size] ---- .Example of a lorem *sentences* macro ---- lorem:sentences[5] ---- [.result] ==== lorem:sentences[5] ==== === 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-stacked-lg mb-2"] |=============================================================================== |Macro | Type |Example |`word[]` |text | lorem:word[] |`words[5]` |text | lorem:words[5] |`sentence[]` |text | lorem:sentence[] |`sentences[5]` |text | lorem:sentences[5] |`date[]` |date | lorem:date[] |`date[strftime]` e.g. `date[%Y-%m-%d]`` |date | lorem:date[%Y-%m-%d] |`name[]` |text | lorem:name[] |`first_name[]` |text | lorem:first_name[] |`last_name[]` |text | lorem:last_name[] |`email[]` |email | lorem:email[] |=============================================================================== // Include documents // ----------------------------------------------------------------------------- include::{documentsdir}/100_gistblock.asciidoc[] == Whats 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 advanced 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 link:{roundtrip-extended-modals}[BS modal extensions] feature of J1 Template.