j1-template 2022.5.0.rc3 → 2022.5.1.rc0

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

@@ -1,718 +0,0 @@
----
-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>
-
-//  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.