GitHub - Asciidoc Adventure

AsciidocAdventure1.adoc

AsciiDoc Adventure #1

Table of Contents

• 1. Cool formatting
• 2. Lists
• 3. Description Lists
• 4. A new perspective on tables
• 5. How to add an image to a gist

:tip-caption: :bulb:
:note-caption: :information_source:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:

Examples taken from: AsciiDoc Writer’s Guide

1. Cool formatting

bold constrained & unconstrained
italic constrained & unconstrained
bold italic constrained & unconstrained

monospace constrained & unconstrained
monospace bold constrained & unconstrained
monospace italic constrained & unconstrained
monospace bold italic constrained & unconstrained

Cool tips

• By default lines are wrapped into a paragraph. To preserve hard linebreaks, either add [%hardbreaks] at the beginning of the pragraph or end the line by "space plus"  +. As explained here

• To place emphasis outside of a word boundaries (eg. in_theMIDDLEof_a_word), you need to double up the punctuation.

• To prevent punctuation from being interpreted as formatting markup, precede it with a backslash (\). If the formatting punctuation begins with two characters (e.g., __), you need to precede it with two backslashes (\\)

• In particular, writing "space{plus}" in monospace is particularly difficult. The meaning of backtick (`) and plus () changed in Asciidoctor 1.5.0. Backticks only make the text monospaced, whereas pluses passthrough text without applying formatting. See the migration page for details. There are several wyas to write "space" in monospace:

  • Use {nbsp} instead of space:  + or  +

  • Use ` delimiter as passthrough: ` ++

bold *constrained* & **un**constrained +
italic _constrained_ & __un__constrained +
bold italic *_constrained_* & **__un__**constrained +
monospace `constrained` & ``un``constrained +
monospace bold `*constrained*` & ``**un**``constrained +
monospace italic `_constrained_` & ``__un__``constrained +
monospace bold italic `*_constrained_*` & ``**__un__**``constrained +

Uhhoo, GitHub doesn’t render the "Marks and Custom Styling" below as show in Formatted Text

This text must have a YELLOW HIGHLIGHT.
Did the werewolves read the small print?
Here is an underline This text must be underlined Do you see it on GitHub?
Emphasize a deleted text by a strike through while still leave the text visible.
OOOHHHnce upon an infinite loop.

2. Lists

Unordered list

• level 1

  • level 2

    • level 3

      • level 4

        • level 5

• back to level 1

Arbitrary starting number for ordered list

7. Writing your own custom Layout

8. PatternLayout

9. Format modifiers

Align paragraph with item a specific level

• Item1, bottom paragraph must align with this item

  • Item 1.1

  • Item 1.2

  The technique to align a paragraph with a parent item is called Attaching to an ancestor list. The paragraphe must be sparated by blank line and a the symbol + which means "list continuation". The number of blank line that precedes the list continuation signals a move up one level of nesting. eg. 2 blank lines means align the paragraph with the grand parent item. The syntax for list above is

* Item1, bottom paragraph must align with this item
** Item 1.1
** Item 1.2

+
The technique to align a paragraph ...

3. Description Lists

Excerpt from A Glossary of Functional Programming

Category Theory

Category theory is a branch of mathematics that defines mathematical structure using directed labeled graphs (categories). An alternative to algebraically-defined structure, category theory is a powerful and precise pattern language for mathematics, computer science, and functional programming. Knowledge of category theory is helpful but not necessary for mastery of applied functional programming.

F-Algebra

An F-algebra is a generalization of algebraic structure that comes from category theory, which makes it possible to represent algebraic laws without universal quantification, using only morphisms. In functional programming, F-algebras appear more directly as interpreters for both tagless-final and free monadic programs (natural transformations), and as algebras and coalgebras in recursion schemes.

Use [horizontal] to right-align the description

Higher-Kinded Types

Higher-kinded types, more precisely called higher-kinded generics, is a language feature in which type parameters may have a kind higher than *. The two most mainstream languages with higher-kinded types are Scala and Haskell.

Monad

A Monad is an Applicative Functor that allows combining a first functional effect, together with a function that takes the success value of the first effect and returns a second effect (continuation). Monads represent the essence of imperative programming: do a first thing, and then do this second thing, which depends on the value computed by the first thing. Under the view of functors as DSLs, Monad adds sequential “statements”, where subsequent statements depend on previous ones.

Combine Description list + unordered list

Buil Tools

• SBT

• Mill

Stream Processing

• Akka Stream

• ZIO

gRPC

• ScalaPB

• Akka-gRPC

4. A new perspective on tables

Firefox	Web Browser
Ruby	Programming Language
TorqueBox	Application Server

Name	Group	Description
Firefox	Web Browser	Mozilla Firefox is an open-source web browser. It’s designed for standards compliance, performance and portability.
Scala	Programming Language	A Functional Progamming on JVM, can use Java libs
Cassandra	noSQL database	KV database inspired fromGoogle BigTable

5. How to add an image to a gist

The instructions below is inspired from this blog

gist has some limitations:

• External URL for image is not possible (the image will appears as broken image)

• The image must be located within the gist repo

• Sub-directory is not allowed in a gist repo. The image must be stored at the same location than the gist document.

Upload image to your gist like a normal repo

1. Create a gist if you haven’t already.

   ℹ️	this is a complex ordered list (having quote). Need to use a technique called List Continuation

2. Clone your gist:

   # the hash is taken from the top right box in the gist page
   git clone git@gist.github.com:git clone git@gist.github.com:8b5e0133f91dc199f1270d623fab7e2e.git

3. Add your image to your gist’s repository:

   # NOTE: gist doesn't accept subdirectory, all files must be at root level
   $ git add your-image.jpg
   $ git commit -m "Add image"
   $ git push origin master

4. Get the URL of the image

   • Using browser, navigate to the gist URL

   • The image which has been committed appears in the bottom, and is rendered as an image

   • right-click on that image, select "Copy image address"

   • use that image URL in the image tag. See Asciidoc documentation

   • NOTE: this is hybrid list (nest unordered list within ordered list)

5. Edit the Asciidoc to use the image:

   # simple version: link + alternate text + optional resize
   image::https://gist.github.com/tringuyen-yw/8b5e0133f91dc199f1270d623fab7e2e/raw/fa0b108217d62d3e3817592cafddd9af443d804f/BridgeInTheForest_356.jpg[Bridge in the forest,267,150]
   
   # complex version: clickable image + id + title
   [#img-bridge]
   .A bridge in the forest
   [link=https://gist.github.com/tringuyen-yw/8b5e0133f91dc199f1270d623fab7e2e/raw/fa0b108217d62d3e3817592cafddd9af443d804f/BridgeInTheForest_356.jpg]
   image::https://gist.github.com/tringuyen-yw/8b5e0133f91dc199f1270d623fab7e2e/raw/fa0b108217d62d3e3817592cafddd9af443d804f/BridgeInTheForest_356.jpg[Bridge in the forest,267,150]

And here is the result (must see a resized image below this text)

Figure 1. A bridge in the forest

AsciiDocAdventure2.adoc

AsciiDoc Adventure #2

Table of Contents

• 1. Links
  • 1.1. External links
  • 1.2. Links to relative files
  • 1.3. Cross references
  • 1.4. Inline Anchors

1. Links

1.1. External links

• Links documentation

• Link to AsciiDoc Syntax Quick Reference

• Email is automatically linked (no need to define uri-scheme mailto): abcd@blabla.net

• Using attribute to add a role (ie. CSS class) to the link + This link must be bold and green: Target window and role attributes for links

1.2. Links to relative files

If you want to link to an external file relative to the current document, use the link macro in front of the file name.

link:AsciiDocAdventure1.adoc[AsciiDoc Adventure #1]

Result: AsciiDoc Adventure #1

1.3. Cross references

A link to another location within an AsciiDoc document or between AsciiDoc documents is called a cross reference (also referred to as an xref)

• XRef to section Inline Anchors (anchor id = the text of the section)

• XRef to section Links RelativeFiles (anchor id = explicit id added to the section)

1.4. Inline Anchors

sectanchors

When this document attribute is set, a section icon anchor appears in front of the section title.

sectlinks

When this document attribute is set, the section titles become self-links. This enables a reader to bookmark the section.

Link to sectanchors
Link to [bookmark-a]
Link to [bookmark-b]
Link to [bookmark-c]
Link to last paragraph (notice the text of the link is substituted by thge anchor custom text)

My bookmark-a	Inline anchors make arbitrary content referenceable.
Another bookmark-b	Inline anchors can be applied to a phrase like this one.
Oh oh bookmark-c	Use a cross reference to link to this location.
Wow stile another bookmark-d	The xreflabel attribute will be used as link text in the cross-reference link.

BridgeInTheForest_356.jpg

GitHub-Flavored-Asciidoc.adoc

GitHub Flavored Asciidoc (GFA)

Table of Contents

• 1. Admonitions
• 2. Source code with Callouts

Source: GitHub Flavored Asciidoc (GFA)

1. Admonitions

There are 4 types of Admonitions: NOTE TIP IMPORTANT CAUTION WARNING

ℹ️	A sample note admonition. We can use gemoji icons in the Asciidoctor markup. We assign an icon name to the document attributes tip-caption, note-caption and important-caption.

ℹ️	this is Note #2 using inline Asciidoc markup syntax

💡	Oh wow it’s possible to have color text. The color brings contrast to the text, making it easier to read. The highlighting also confirms when you’ve entered the correct syntax for an inline or block element.

❗	Some text with bold and italic

⚠️	bold italic constrained & unconstrained monospace bold constrained & unconstrained

🔥	Before taking the easy route of exposing your service with NodePort type, Read Think Before you NodePort in Kubernetes

2. Source code with Callouts

Callouts are a great way to explain code segment and are, in fact, the one of the two main reasons I even looked into asciidoc (the other being the admonition blocks). Asciidoctor will place numbers in the code listing, which you can uses as references following the code listing.

\ifdef::env-github[] (1)
:imagesdir: https://gist.githubusercontent.com/path/to/gist/revision/dir/with/all/images
\ifndef::env-github[] (2)
:imagesdir: ./

1. Use the ifdef to customize for online rendering

2. Use the ifndef to customize for offline

import java.time.{Duration, LocalDateTime}

/**
 * Calculate elapsed time in seconds between 2 LocalDateTime
 * If `start` is later than `end` the duration will be negative
 */
def computeDurationSeconds(
  start: LocalDateTime,
  end: LocalDateTime = LocalDateTime.now() // scalastyle:ignore (1)
): Double = {
  val elapsedDuration = Duration.between(start, end)
  elapsedDuration.getSeconds + elapsedDuration.getNano / 1e9 // (2)
}

1. scalastyle will reject the code because of now() which is not stable (different value at each call)

2. getSeconds gives the integer part, getNano gives the decimal part

Code block with non-selectable callouts

Source: AsciiDoc Syntax Quick Reference, Source Code

line of code  // (1)
line of code  # (2)
line of code  ;; (3)
line of code  <!--(4)-->

1. A callout behind a line comment for C-style languages.

2. A callout behind a line comment for Ruby, Python, Perl, etc.

3. A callout behind a line comment for Clojure.

4. A callout behind a line comment for XML or SGML languages like HTML.