j1-template 2022.4.10 → 2022.5.0.rc0

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

@@ -0,0 +1,719 @@
+---
+title:                                  Roundtrip
+tagline:                                asciidoc extensions
+date:                                   2020-11-07 00:00:00
+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.
+
+categories:                             [ Roundtrip ]
+tags:                                   [ Introduction, Module, Asciidoc, Extension ]
+
+fab_menu_id:                            page_ctrl
+
+permalink:                              /pages/public/learn/roundtrip/asciidoc_extensions/
+regenerate:                             false
+
+resources:                              [ animate, clipboard, lightbox, iconify, twemoji, rouge ]
+resource_options:
+  - attic:
+      slides:
+        - url:                          /assets/images/pages/roundtrip/puzzle-1920x1280-bw.jpg
+          alt:                          puzzle-1920x1280-bw
+---
+
+// Page Initializer
+// =============================================================================
+// Enable the Liquid Preprocessor
+:page-liquid:
+
+// Set (local) page attributes here
+// -----------------------------------------------------------------------------
+// :page--attr:                         <attr-value>
+:images-dir:                            {imagesdir}/pages/roundtrip/100_present_images
+
+//  Load Liquid procedures
+// -----------------------------------------------------------------------------
+{% capture load_attributes %}themes/{{site.template.name}}/procedures/global/attributes_loader.proc{%endcapture%}
+
+// Load page attributes
+// -----------------------------------------------------------------------------
+{% include {{load_attributes}} scope="all" %}
+
+// Page content
+// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+// Include sub-documents (if any)
+// -----------------------------------------------------------------------------
+[role="dropcap"]
+J1 Template implements some incubating Ruby-based extensions for Asciidoctor.
+Most extensions are based on the examples given with the
+link:{url-asciidoctor--extensions-lab}[Asciidoctor Extensions Lab, {browser-window--new}].
+If you simply want to use the extensions from this repository, go ahead to
+link:{url-asciidoctor--extensions-use}[Using an extension, {browser-window--new}].
+To create Asciidoc extensions on your own, it is highly recommended to read the
+link:{url-asciidoctor--extensions-manual}[extensions section, {browser-window--new}] in
+the Asciidoctor user manual.
+
+All already implemented Asciidoctor Extensions you'll find below. Additional
+valuable extensions to the Markup language Asciidoc to the Markup language
+Asciidoc is made especially for documents of the Jekyll content type pages
+(but can be used for posts or collections as well).
+
+== Asciidoc Result Extension
+
+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 listing block 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 helpful for sections discussing
+Asciidoc code and how the resulting (HTML) code would look alike.
+
+.This example place a button `VIEW` top right of the example box
+[source, no_template, role="noclip"]
+----
+* displayed always
+----
+
+[.result]
+====
+ displayed till clicked, but closed on second click (toggle)
+====
+
+== Asciidoc Admonitions
+
+Admonition blocks draw attention to certain statements by taking them out
+of the content’s flow and labeling them as priorities. These types of
+(Asciidoc) blocks are called admonitions. The AsciiDoc language provides
+five admonition types represented by the following labels:
+
+.Admonition labels
+[cols="3a,9a", subs=+macros, options="header", width="100%", role="rtable mt-3"]
+|===
+|Name |Description
+
+|`NOTE`
+|Additional information on the currently discussed topic that may help
+the reader
+
+|`TIP`
+|Additional information on the currently discussed topic that may help the
+reader *to go further* or describe *additional options* available
+
+|`IMPORTANT`
+|Emphasis on what is currently being discussed and facts that should
+be kept in mind
+
+|`CAUTION`
+|Advise the reader to act carefully and point to potential tripping
+
+|`WARNING`
+|inform the reader of danger, harm, or consequences that exist
+
+|===
+
+NOTE: All colors for all default admonition blocks set to the standard
+MD 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 (:).
+
+.Admonition paragraph syntax
+[source, config]
+----
+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.
+
+.Admonition block syntax
+[source, config]
+----
+[NOTE]
+====
+The block text (multiline)
+====
+----
+
+To add an *additional* title element on an admonition, place a dot (.)
+markup directly followed (no spaces) by the text of the title.
+
+.Admonition block syntax and additional title
+[source, config]
+----
+.title text
+[NOTE]
+====
+The block text (multiline)
+====
+----
+
+.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
+
+
+== 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, information]` can be placed directly *above* the
+text.
+
+.Synopsis
+[source, text]
+----
+[quote, attribution, information]
+Quote or excerpt text
+----
+
+After landing the cloaked Klingon bird of prey in Golden Gate park:
+
+[quote, Captain James T. Kirk, Star Trek IV: The Voyage Home]
+Everybody remember where we parked.
+
+A *single* paragraph can be turned into a blockquote by:
+
+. surrounding the quoted paragraph with double-quotes (")
+. adding an (optional) `attribution`, prefixed by two dashes (--)
+  *below* the quoted text
+
+.Synopsis
+[source, text]
+----
+"quoted paragraph"
+-- attribution
+----
+
+"I hold it that a little rebellion now and then is a good thing,
+and as necessary in the political world as storms in the physical."
+-- Thomas Jefferson, Papers of Thomas Jefferson: Volume 11
+
+
+=== 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* (____).
+
+.Synopsis
+
+[source, text]
+----
+[quote, attribution]
+____
+paragraph text (multiline)
+____
+----
+
+[quote, Monty Python and the Holy Grail]
+____
+Dennis: Come and see the violence inherent in the system.
+Help! Help! I'm being repressed!
+
+King Arthur: Bloody peasant!
+
+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
+
+A Lightbox is, in general, a helper which displays enlarged, almost
+screen-filling versions of images (or videos) while dimming the remainder
+of the page. The technique, introduced by Lightbox V2, gained widespread
+popularity thanks to its simple style. The term lightbox has been employed
+since then for Javascript libraries to support such functionality.
+
+To make the use of the built-in lightbox easier, the J1 Template offers an
+Asciidoc extension: the lightBox block macro. The block macro `lightbox::`
+embeds one or more images into the output document and puts the default
+lightbox for J1 automatically on. The images `size` (width) and additional
+`caption text` and additional CSS styles are configurable for all images
+using this macro.
+
+.Lightbox block for single images
+[source, no_template, role="noclip"]
+----
+.block_title
+lightbox::<block_id>[ <images_width>, <images_data_id>, <role="<additional CSS styles>"> ]
+----
+
+.Lightbox block for image groups
+[source, no_template, role="noclip"]
+----
+.block_title
+lightbox::<block_id>[ <images_width>, <images_data_id>, <group_name>, <role="<additional CSS styles>"> ]
+----
+
+[NOTE]
+====
+The `role` parameter to specify additional CSS styles is for all `lightbox::`
+macros *optional* and can be omitted.
+
+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 technique 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 their 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
+[source, no_template, role="noclip"]
+----
+"path/to/image-1, image-caption-1, ..."
+----
+
+.Example of an data attribute for a lightbox block
+[source, no_template, 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)
+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 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 behavior 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, no_template, role="noclip"]
+----
+lightbox::<block_id>[ 400, {<data-images-id>} ]
+----
+
+.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 to enable a simple sliding functionality through this group
+of related images. Enabling this function, the option `group` needs to be
+configured for the block.
+
+.Lightbox block for grouped images
+[source, no_template, role="noclip"]
+----
+lightbox::<block_id>[ 400, {<data-images-group_id>}, <group_name> ]
+----
+
+.Lightbox block for grouped images
+lightbox::images-group[ 400, {data-images-group}, 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
+size (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. Sort of like mason
+fitting stones in a wall.
+
+.Gallerie macro for images and videos
+[source, no_template]
+----
+.block_title
+gallery::<gallery_id>[role="<additional CSS styles>"]
+----
+
+=== Image galleries
+
+lorem:sentences[5]
+
+=== Video galleries
+
+lorem:sentences[5]
+
+
+== 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:
+
+[source, no_template, role="noclip"]
+----
+flag:country[style, size, modifier] <1> <2> <3> <4>
+----
+<1> All `country` flags can be found on the preview page for
+    link:{url-previewer--county-flags}[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
+
+.Click on button `VIEW` to see how it's looks alike
+[source, no_template, role="noclip"]
+----
+flag:de[rectangle, 2x, ml-3 mr-2 mb-2] Germany (rectangle) +
+flag:de[squared, 2x, ml-3 mr-3 mb-2] Germany (square)
+----
+
+[.result]
+====
+flag:de[rectangle, 2x, ml-3 mr-2 mb-2] Germany (rectangle) +
+flag:de[squared, 2x, ml-3 mr-3 mb-2] 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.
+
+.Example flag sizes (responsive)
+[cols="2a,3a,4a,^", options="header", width="100%", role="rtable mt-3"]
+|===
+|Size |Style |Markup |Render
+
+|`xs`
+|rectangle
+|
+.Germany
+[source, adoc, role="noclip"]
+----
+flag:de[rectangle, xs]
+----
+^|flag:de[rectangle, xs]
+
+|`sm`
+|rectangle
+|
+.Germany
+[source, adoc, role="noclip"]
+----
+flag:de[rectangle, sm]
+----
+^|flag:de[rectangle, sm]
+
+|`md`
+|rectangle
+|
+.Belgium
+[source, adoc, role="noclip"]
+----
+flag:be[rectangle, md]
+----
+^|flag:be[rectangle, md]
+
+|`lg`
+|rectangle
+|
+.Denmark
+[source, adoc, role="noclip"]
+----
+flag:dk[rectangle, lg]
+----
+^|flag:dk[rectangle, lg]
+
+|`xl`
+|rectangle
+|
+.Spain
+[source, adoc, role="noclip"]
+----
+flag:es[rectangle, xl]
+----
+^|flag:es[rectangle, xl]
+
+|===
+
+
+== Icon Fonts
+
+The J1 Template comes with full icon support for Asciidoc documents included.
+All icon fonts are supported:
+
+* FA (FontAwesome)
+* MDI (MaterialDesign icons)
+* Iconify
+
+== Material Designs Icons
+
+Material Designs Icons can be used as inline icons by using
+the `mdi:` inline macro:
+
+[source, no_template, role="noclip"]
+----
+mdi:icon_name[icon_size, modifier] <1> <2> <3>
+----
+<1> All `icon_name` can be found on the preview page for
+    link:{url-previewer--mdi-icons}[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 button `VIEW` to see how it's looks alike
+[source, no_template, 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 +
+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)
+====
+
+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, no_template, role="noclip"]
+----
+fas:icon_name[icon_size, modifier] <1> <2> <3>
+----
+<1> All `icon_name` can be found on the preview page at
+    link:{url-fa-icons--previewer}[FA Icons, {browser-window--new}]
+<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 button `VIEW` to see how it's looks alike
+[source, no_template, 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 +
+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, no_template, role="noclip"]
+----
+iconify:icon_name[icon_size, modifier] <1> <2> <3>
+----
+<1> All `icon_name` can be found on the preview page at
+    link:{url-iconify-icons--previewer}[Iconify Icons, {browser-window--new}]
+<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 button `VIEW` to see how it's looks alike
+[source, no_template, 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
+----
+
+[.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:{url-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
+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.
+====
+
+
+== Blind Text (Lorem)
+
+The Ruby Gem Middleman, a Ruby-based 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 use
+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 `macro`. The
+syntax for the `lorem:` inline macro is simple like this:
+
+[source, no_template]
+----
+lorem:macro[]
+lorem:macro[size]
+----
+
+.Example of a lorem sentences macro
+[source, no_template, role="noclip"]
+----
+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="rtable 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::{documentdir}/100_gistblock.asciidoc[]
+
+
+== What next
+
+Asciidoc (Asciidoctor) extensions open up the Markup language to new use cases.
+Using the full power of programming languages to extend what's needed, whether
+Ruby, Java, Groovy, or JavaScript. The number of extensions will grow - to get
+handy and powerful functionality needed for modern web pages based on the
+Asciidoc Markup language generated by Jekyll. For sure!
+
+The next preview is focussing on 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:{url-roundtrip--extended-modals}[BS Modal Extensions]
+feature of J1 Template.