j1-template 2020.0.18 → 2020.0.24

data/lib/starter_web/pages/public/learn/roundtrip/400_asciidoc_extensions.adoc

@@ -1,16 +1,23 @@
 ---
 title:                                  Roundtrip
 tagline:                                asciidoc extensions
-description:                            Asciidoc Extensions (asciidoctor)
-
-tags:                                   [ Page, Roundtrip ]
-index:                                  [ Template, Roundtrip, Asciidoc, Asciidoctor, Extensions ]
-categories:                             [ pages ]
+description: >
+                                        J1 Template implements some incubating Ruby-based extensions
+                                        for Asciidoctor. Most extensions are based on the examples
+                                        given with the Asciidoctor Extensions Lab.
+                                        All implemented Asciidoctor Extensions can be found in this article.
+                                        A set of 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.
+
+date:                                   2020-11-07 12:00:00
+tags:                                   [ Roundtrip, Introduction ]
+categories:                             [ Asciidoc, Extension ]
 
 permalink:                              /pages/public/learn/roundtrip/asciidoc_extensions/
 regenerate:                             false
 
-resources:                              [ lightbox, iconify, twemoji ]
+resources:                              [ lightbox, iconify, twemoji, rouge ]
 resource_options:
   - attic:
       padding_top:                      400
@@ -25,64 +32,50 @@ resource_options:
 #           href:                       https://unsplash.com/@aquatium
 ---
 
+// Page Initializer
+// =============================================================================
 // Enable the Liquid Preprocessor
-// -----------------------------------------------------------------------------
 :page-liquid:
 
-// Set other global page attributes here
+// Set page (local) attributes here
 // -----------------------------------------------------------------------------
-//:my-asciidoc-attribute:
+// :page--attr:                         <attr-value>
+:images-dir:                            {imagesdir}/pages/roundtrip/100_present_images
 
 //  Load Liquid procedures
 // -----------------------------------------------------------------------------
-{% capture set_env_entry_document %}themes/{{site.template.name}}/procedures/global/set_env_entry_document.proc{%endcapture%}
-
+{% capture load_attributes %}themes/{{site.template.name}}/procedures/global/attributes_loader.proc{%endcapture%}
 
-// Initialize entry document environmental attributes
+// Load page 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
+{% include {{load_attributes}} scope="all" %}
 
 
 // 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}].
+{asciidoctor-extensions-lab}[Asciidoctor Extensions Lab, {browser-window--new}].
 If you simply want to use the extensions from this repository, go ahead to
-{asciidoctor-extensions-use-extension}[Using an extension, {window}].
+{asciidoctor-extensions-use-extension}[Using an extension, {browser-window--new}].
 
 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.
-
+{asciidoctor-user-manual-extensions}[extensions section, {browser-window--new}] 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
+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
+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`.
@@ -90,39 +83,20 @@ clicking the toggle button `VIEW` displays (or hide) the content given by the
 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
+.This example place a button `VIEW` top right of the example box
+[source, prometheus, role="noclip"]
 ----
 * displayed always
 ----
 
 [.result]
 ====
-* displayed till clicked, but closed automatically after *5 seconds*
+ displayed till clicked, but closed on second click
 ====
 
-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
+All colors for all default admonition blocks set to the standard MD color
 set. Find available block types an their colors below.
 
 .NOTE block
@@ -143,18 +117,18 @@ CAUTION: Icon background-color: red
 
 == Q&A Blocks
 
-*Q&A sections* are used quite often to answer popular questions. To make
+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.
+extensions.
 
 === Question block
 
-The admonition *Question block* is an extention to the Asciidoc admonition
-block types that introduce an admonition of type *question*.
+The admonition Question block is an extension to the Asciidoc admonition
+block types that introduce an admonition of type question.
 
 .Example of a question block
-[source, adoc, role="noclip"]
+[source, prometheus, role="noclip"]
 ----
 [QUESTION]
 What's the main tool for selecting colors?
@@ -169,12 +143,12 @@ 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*.
+The Admonition Answer block is an extension 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"]
+[source, prometheus, role="noclip"]
 ----
 [ANSWER]
 For J1 Template, go for for the Core documentation section. You'll
@@ -186,63 +160,65 @@ find the full color scheme for Material Design.
 .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*.
+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
+more images into the output document and puts the default Lightbox (lightbox)
+for J1 automatically on. For all images, the `size` (width) and individual
 `caption text` can be configured.
 
 .Lightbox Block
-[source, adoc, role="noclip"]
+[source, prometheus, 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.
+without any other scaling than in width - they are placed using simple
+HTML `img` tags. This is fine for images that are even in size. For images in
+different sizes, a gallery should be used as a J1 Gallery Apps to rearrange
+images and 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*:
+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
+[source, prometheus, role="noclip"]
 ----
-  "path/to/image-1, image-caption-1, ..."
+"path/to/image-1, image-caption-1, ..."
 ----
 
-.Example of an data *attribute* for a lightbox block
+.Example of an data attribute for a lightbox block
+[source, prometheus, role="noclip"]
 ----
 :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)
+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
+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`.
 
-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
+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*
+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*.
+standalone.
 
 .Lightbox block for standalone images
-[source, adoc, role="noclip"]
+[source, prometheus, role="noclip"]
 ----
 lightbox::images-standalone[ 400, {data-images-standalone} ]
 ----
@@ -254,11 +230,11 @@ lightbox::images-standalone[ 400, {data-images-standalone} ]
 
 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
+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"]
+[source, prometheus, role="noclip"]
 ----
 lightbox::images-group[ 400, {data-images-group}, group_name ]
 ----
@@ -277,22 +253,22 @@ All icon fonts are supported:
 * Iconify
 * Twitter Emoji
 
-
 == Material Designs Icons
 
-*Material Designs Icons* can be used as *inline* icons by using
+Material Designs Icons can be used as inline icons by using
 the `mdi:` inline macro:
 
-[source, adoc, role="noclip"]
+[source, prometheus, 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*
+<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
+[source, prometheus, role="noclip"]
 ----
 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 +
@@ -307,27 +283,28 @@ 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}].
+link:{previewer-mdi}[MDI Icon Previewer, {browser-window--new}].
 
-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*
+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
+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"]
+[source, prometheus, 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*
+<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
+[source, prometheus, role="noclip"]
 ----
 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 +
@@ -341,66 +318,68 @@ 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*
+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:`
+Iconify Icons can be used as inline icons by using the `iconify:`
 inline macro:
 
-[source, adoc, role="noclip"]
+[source, prometheus, 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*
+<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
+[source, prometheus, role="noclip"]
 ----
-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*
+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
+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}].
+link:{iconify-icon-sets}[Iconify Icon Sets, {browser-window--new}].
 
 [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*
+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.
+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:`
+Twitter Emoji's can be used as inline icons by using the `emoji:`
 inline macro:
 
-[source, adoc]
+[source, prometheus]
 ----
 emoji:icon_name[icon_size] <1> <2>
 ----
-<1> All `icon_name` can be found on the Preview page for *Twitter Emoji's*
+<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
+[source, prometheus, role="noclip"]
 ----
 This is an example of how you can emoji:heart[2x, pulsed mt-1] Asciidoctor
 and Twitter Emoji emoji:smile[].
@@ -413,31 +392,32 @@ and Twitter Emoji emoji:smile[].
 ====
 
 Find all Twitter Emoji's build-in with J1 Template on page
-link:{previewer-emoji}[Emoji Icon Previewer, {window}].
+link:{previewer-emoji}[Emoji Icon Previewer, {browser-window--new}].
 
 
 == 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*
+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
+content is available at the beginning. It is quite useful to place blind text
+first to get a better impression how a page will look-alike that is not
 finished yet.
 
-Placeholders for *blind text* comes in several flavours given by `macro`. The
+Placeholders for blind text comes in several flavours given by `macro`. The
 syntax for the `lorem:` inline macro is simple like this:
 
-[source, adoc]
+[source, prometheus]
 ----
 lorem:macro[]
 lorem:macro[size]
 ----
 
-.Example of a lorem *sentences* macro
+.Example of a lorem sentences macro
+[source, prometheus, role="noclip"]
 ----
 lorem:sentences[5]
 ----
@@ -449,11 +429,11 @@ lorem:sentences[5]
 
 === Lorem Types
 
-All *macro* types available for `lorem:` to be used for blind *text* can be
+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"]
+[cols="5,2,5a", options="header", role="rtable mb-2"]
 |===============================================================================
 |Macro | Type |Example
 
@@ -512,12 +492,12 @@ lorem:email[]
 // Include documents
 // -----------------------------------------------------------------------------
 
-include::{documentsdir}/100_gistblock.asciidoc[]
+include::{documentdir}/100_gistblock.asciidoc[]
 
 
 == Whats next
 
-Asciidoc, respectively Asciidoctor, *extensions* open up the Markup language to
+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.
 
@@ -525,9 +505,9 @@ 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!
+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 dialogues using them!
 
 Have a look for the link:{roundtrip-extended-modals}[BS modal extensions]
 feature of J1 Template.