hugo-theme-flat/exampleSite/content/essays/asciidoctor-test/index.adoc

---
title: "AsciiDoctor Syntax Test"
date: 2023-06-07T20:44:48+08:00
tags: []
categories: []
weight: 50
show_comments: true
katex: true
draft: false
---

= AsciiDoctor Syntax Test
:experimental:
// :source-highlighter: rouge

This article is a test for AsciiDoc syntax, and will try to use
as many AsciiDoc features as possible. Most content come from
https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#more-delimited-blocks[
AsciiDoc Syntax Quick Reference].
Now let's go.

== WIP

Here we record TODOs.

* [ ] Lead paragraph not strong.
* [ ] Change highlight color to a fav-color.
* [ ] Underline not shown, syntax `+[.underline]#text#+`.
* [ ] Strikethrough not shown, syntax `+[.linethrough]#text#+`
* [ ] Description list, the term not strong.
* [ ] Image, video, audio, list's caption is too big.
* [ ] Inline image breaks line.
* [ ] Image role `+right+` not go right.
* [ ] Video overflowed.
* [ ] Video not centered.
* [ ] Keyboard no theme.
* [ ] Button no theme.
* [ ] Code callouts always selectable.
* [ ] Code highlight class is working, but without CSS ruler.
* [ ] Code included from other file (code under pre) has too much padding
* [ ] Admonitions too big.
* [ ] Sidebar should be standout.
* [ ] Blockquotes no theme

* CSS class name conflict
** [ ] content: almost everywhere
** [ ] title: caption of list, audio, video, picture


== Paragraphs

Paragraphs don't require special markup in AsciiDoc.
A paragraph is defined by one or more consecutive lines of text.
Line breaks within a paragraph are not displayed.

Leave at least one empty line to begin a new paragraph.

=== Literal paragraph

A normal paragraph.

 A literal paragraph.
 One or more consecutive lines indented by at least one space.

 The text is shown in a fixed-width (typically monospace) font.
 The lines are preformatted (i.e., as formatted in the source).
 Spaces and newlines,
 like the ones in this sentence,
 are preserved.

=== Hard line break

Roses are red, +
violets are blue.

[%hardbreaks]
A ruby is red.
Java is black.

=== Lead paragraph

[.lead]
This text will be styled as a lead paragraph (i.e., larger font).

This paragraph will not be.

== Text formatting

=== Constrained bold, italic, and monospace

It has *strong* significance to me.

I _cannot_ stress this enough.

Type `OK` to accept.

That *_really_* has to go.

Can't pick one? Let's use them `*_all_*`.

=== Unconstrained bold, italic, and monospace

**C**reate, **R**ead, **U**pdate, and **D**elete (CRUD)

That's fan__freakin__tastic!

Don't pass generic ``Object``s to methods that accept ``String``s!

It was Beatle**__mania__**!

=== Highlight, underline, strikethrough, and custom role

Mark my words, #automation is essential#.

##Mark##up refers to text that contains formatting ##mark##s.

Where did all the [.underline]#cores# go?

We need [.line-through]#ten# twenty VMs.

A [.myrole]#custom role# must be fulfilled by the theme.

=== Superscript and subscript

^super^script

~sub~script

=== Smart quotes and apostrophes

"`double curved quotes`"

'`single curved quotes`'

"plain double curved quotes"

Olaf's desk was a mess.

A ``std::vector```'s size is the number of items it contains.

All of the werewolves`' desks were a mess.

Olaf had been with the company since the `'00s.

== Links

=== Autolinks, URL macro, and mailto macro

https://asciidoctor.org - automatic!

https://asciidoctor.org[Asciidoctor]

devel@discuss.example.org - also automatic!

mailto:devel@discuss.example.org[Discuss]

mailto:join@discuss.example.org[Subscribe,Subscribe me,I want to join!]

=== URL macros with attributes

https://chat.asciidoc.org[Discuss AsciiDoc,role=external,window=_blank]

https://chat.asciidoc.org[Discuss AsciiDoc^]

=== URLs with spaces and special characters

link:++https://example.org/?q=[a b]++[URL with special characters (Using ``++`` to quote)]

https://example.org/?q=%5Ba%20b%5D[URL with special characters (URLencoded)]

=== Link to relative file

link:index.html[Docs]

=== Link using a Windows UNC path

link:\\server\share\whitepaper.pdf[Whitepaper]

=== Inline anchors

[[bookmark-a]]Inline anchors make arbitrary content referenceable.

anchor:bookmark-c[]Use a cross reference to link to this location.

[[bookmark-d,last paragraph of section Inline archors]]The xreflabel attribute will be used as link text in the cross-reference link.

=== Cross references

See <<Paragraphs>> to learn how to write paragraphs.

Learn how to organize the document into <<Paragraphs,paragraphs>> (with custom text).

Here we can go to <<bookmark-a>>

Here we can go to <<bookmark-c>>

Here we can go to <<bookmark-d>>

=== Inter-document cross references

NOTE: Inter-document cross reference is hardly working.

Refer to xref:document-b.adoc#section-b[Section B of Document B] for more information.

If you never return from xref:document-b.adoc[Document B], we'll send help.

== Document header

NOTE: It doesn't show in hugo, but the attributes defined nearby header is work,
maybe the reason is using `--no-header-footer` argument when
proceessing with asciidoctor.

== Automatic TOC

NOTE: TOC not work, don't know why.

:toc:

== Includes

=== Include document parts

include::external.adoc[]

=== Include content by tagged regions or lines

==== By tag

include::document-b.adoc[tag=section-b]

==== By line

include::document-b.adoc[lines=30..32]

=== Include content from a URL

NOTE: asciidoctor without `+allow-uri-read+` will not render URL content, which is
the default behaviour.

include::https://raw.githubusercontent.com/asciidoctor/asciidoctor/main/README.adoc[]

== Lists

=== Unordered list

* List item
** Nested list item
*** Deeper nested list item
* List item
 ** Another nested list item
* List item

=== Unordered list max level nesting

* Level 1 list item
** Level 2 list item
*** Level 3 list item
**** Level 4 list item
***** Level 5 list item
****** etc.
* Level 1 list item

=== Ordered list

. Step 1
. Step 2
.. Step 2a
.. Step 2b
. Step 3

=== Ordered list max level nesting

. Level 1 list item
.. Level 2 list item
... Level 3 list item
.... Level 4 list item
..... Level 5 list item
. Level 1 list item

=== Checklist

* [*] checked
* [x] also checked
* [ ] not checked
* normal list item

=== Description list

First term:: The description can be placed on the same line
as the term.
Second term::
Description of the second term.
The description can also start on its own line.

=== Question and answer list

[qanda]
What is the answer?::
This is the answer.

Are cameras allowed?::
Are backpacks allowed?::
No.

=== Mixed

Operating Systems::
  Linux:::
    . Fedora
      * Desktop
    . Ubuntu
      * Desktop
      * Server
  BSD:::
    . FreeBSD
    . NetBSD

Cloud Providers::
  PaaS:::
    . OpenShift
    . CloudBees
  IaaS:::
    . Amazon EC2
    . Rackspace

=== Complex content in outline lists

* Every list item has at least one paragraph of content,
  which may be wrapped, even using a hanging indent.
+
Additional paragraphs or blocks are adjoined by putting
a list continuation on a line adjacent to both blocks.
+
list continuation:: a plus sign (`{plus}`) on a line by itself

* A literal paragraph does not require a list continuation.

 $ cd projects/my-book

* AsciiDoc lists may contain any complex content.
+
|===
|Column 1, Header Row |Column 2, Header Row

|Column 1, Row 1
|Column 2, Row 1
|===

== Images

=== Block image macro

image::sunset.jpg[]

image::sunset.jpg[Sunset]

.A mountain sunset
[#img-sunset,caption="Figure 1: ",link=/essays/asciidoctor-test/sunset.jpg]
image::sunset.jpg[Sunset,200,100]

image::https://asciidoctor.org/images/octocat.jpg[GitHub mascot]

=== Inline image macro

Click image:sunset.jpg[] to get the party started.

Click image:sunset.jpg[title=Pause] when you need a break.

=== Inline image macro with positioning role

image:sunset.jpg[Sunset,150,150,role=right] What a beautiful sunset!

== Audio

=== Block audio macro

.Bit Bit Loop
audio::Bit Bit Loop.mp3[]

.Bit Bit Loop
audio::Bit Bit Loop.mp3[start=60,opts=autoplay]

Written by link:++https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=QL4T5W3SDDBZA++[Kevin MacLeod]. Hardcore party for the 8bit generation. This music is available for commercial and non-commercial purposes.

The audio above is download from https://freepd.com/electronic.php

== Videos

.Video by Nicki Vlachou
video::video.mp4[]

.Video by Nicki Vlachou
video::video.mp4[width=640,start=60,opts=autoplay]

Both videos above are downloaded from https://www.pexels.com/video/a-red-ferris-wheel-3509314/

== Keyboard, button, and menu macros

IMPORTANT: You must set the `+experimental+` attribute in the document header to enable
these macros. As did in this article.

=== Keyboard macro

|===
|Shortcut |Purpose

|kbd:[F11]
|Toggle fullscreen

|kbd:[Ctrl+T]
|Open a new tab
|===

=== Menu macro

To save the file, select menu:File[Save].

Select menu:View[Zoom > Reset] to reset the zoom level to the default setting.

=== Button macro

Press the btn:[OK] button when you are finished.

Select a file in the file navigator and click btn:[Open].

== Literals and source code

=== Inline literal monospace

Output literal monospace text, such as `+{backtick}+` or `+http://localhost:8080+`,
by enclosing the text in a pair of pluses surrounded by a pair backticks. Another way
to monospace text is use single `backtick`.

=== Literal paragraph

Normal line.

 Indent line by one space to create a literal line.

Normal line.

=== Literal block

....
error: 1954 Forbidden search
absolutely fatal: operation lost in the dodecahedron of doom

Would you like to try again? y/n
....

=== Listing block with title

.Gemfile.lock
----
GEM
  remote: https://rubygems.org/
  specs:
    asciidoctor (2.0.15)

PLATFORMS
  ruby

DEPENDENCIES
  asciidoctor (~> 2.0.15)
----

=== Source block with title and syntax highlighting

[IMPORTANT]
====
You must enable source highlighting by setting the source-highlighter
attribute in the document header, CLI or API.

 :source-highlighter: rouge

See https://docs.asciidoctor.org/asciidoctor/latest/syntax-highlighting/[Syntax Highlighting] to learn which values are accepted when using Asciidoctor.
====

IMPORTANT: Using rouge with enlonger the time to generate the site, on this example site
with only this article as asciidoc, the build time is 147ms. When enable rouge as syntax
highlight, the build time is 340ms.

.Some Ruby code
[source,ruby]
----
require 'sinatra'

get '/hi' do
  "Hello World!"
end
----

=== Source block with callouts

NOTE: callouts are always selectable, don't know why.

[source,ruby]
----
require 'sinatra' # <1>

get '/hi' do # <2>
  "Hello World!" # <3>
end
----
<1> Library import
<2> URL mapping
<3> HTTP response body

=== Make callouts non-selectable

----
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.

=== Source block content included from a file

[,bash]
----
include::hello-world.sh[]
----

=== Source add leading indentation from partial file content

[source, bash]
----
include::hello-world.sh[indent=4]
----

== Admonitions

=== Admonition paragraph

NOTE: An admonition draws the reader's attention to auxiliary information.

IMPORTANT: Don't forget the children!

TIP: Look for the warp zone under the bridge.

CAUTION: Slippery when wet.

WARNING: The software you're about to use is untested.

IMPORTANT: Sign off before stepping away from your computer.

=== Admonition block

[NOTE]
====
An admonition block may contain complex content.

.A list
- one
- two
- three

Another paragraph.
====


== More delimited blocks

=== Sidebar block

.Optional Title
****
Sidebars are used to visually separate auxiliary bits of content
that supplement the main text.
****

=== Example block

====
Here's a sample AsciiDoc document:

----
= Title of Document
Doc Writer
:toc:

This guide provides...
----

The document header is useful, but not required.
====

=== Blockquotes

[quote,Abraham Lincoln,Address delivered at the dedication of the Cemetery at Gettysburg]
____
Four score and seven years ago our fathers brought forth
on this continent a new nation...
____

[quote,Albert Einstein]
A person who never made a mistake never tried anything new.

____
A person who never made a mistake never tried anything new.
____

[quote,Charles Lutwidge Dodgson,'Mathematician and author, also known as https://en.wikipedia.org/wiki/Lewis_Carroll[Lewis Carroll]']
____
If you don't know where you are going, any road will get you there.
____

"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

=== Open blocks

--
An open block can be an anonymous container,
or it can masquerade as any other block.
--

[source]
--
puts "I'm a source block!"
--

=== Passthrough block

++++
<p>
Content in a passthrough block is passed to the output unprocessed.
That means you can include raw HTML.
</p>
++++

=== Customize block subsitutions

:release-version: 2.4.3

[source,xml,subs=attributes+]
----
<dependency>
  <groupId>org.asciidoctor</groupId>
  <artifactId>asciidoctorj</artifactId>
  <version>{release-version}</version>
</dependency>
----

== Tables

=== Table with a title, two columns, a header row, and two rows of content

.Table Title
|===
|Column 1, Header Row |Column 2, Header Row

|Cell in column 1, row 1
|Cell in column 2, row 1

|Cell in column 1, row 2
|Cell in column 2, row 2
|===

=== Table with two columns, a header row, and two rows of content

[%header,cols=2*]
|===
|Name of Column 1
|Name of Column 2

|Cell in column 1, row 1
|Cell in column 2, row 1

|Cell in column 1, row 2
|Cell in column 2, row 2
|===

=== Table with three columns, a header row, and two rows of content

.Applications
[cols="1,1,2"]
|===
|Name |Category |Description

|Firefox
|Browser
|Mozilla Firefox is an open source web browser.
It's designed for standards compliance,
performance, portability.

|Arquillian
|Testing
|An innovative and highly extensible testing platform.
Empowers developers to easily create real, automated tests.
|===

=== Table with column containing AsciiDoc content

[cols="2,2,5a"]
|===
|Firefox
|Browser
|Mozilla Firefox is an open source web browser.

It's designed for:

* standards compliance
* performance
* portability

https://getfirefox.com[Get Firefox]!
|===

=== Table from CSV data using shorthand

,===
Artist,Track,Genre

Baauer,Harlem Shake,Hip Hop
,===

=== Table from CSV data

[%header,format=csv]
|===
Artist,Track,Genre
Baauer,Harlem Shake,Hip Hop
The Lumineers,Ho Hey,Folk Rock
|===

=== Table from CSV data included from file

[opts=header]
,===
include::customers.csv[]
,===

=== Table from DSV data using shorthand

:===
Artist:Track:Genre

Robyn:Indestructible:Dance
:===

=== Table with formatted, aligned and merged cells

[cols="e,m,^,>s",width="25%"]
|===
|1 >s|2 |3 |4
^|5 2.2+^.^|6 .3+<.>m|7
^|8
|9 2+>|10
|===

== Comments

There will show no other content, because comments are not shown.

// A single-line comment

////
A multi-line comment.

Notice it's a delimited block.
////

== Breaks

=== Thematic break (aka horizontal rule)

before

'''

after

== Footnotes

A statement.footnote:[Clarification about this statement.]

A bold statement!footnote:disclaimer[Opinions are my own.]

Another bold statement.footnote:disclaimer[]

== Others

=== LaTeX

Here we are trying to render LaTeX with \(\KaTeX\), and there following a
formula block rendered by KaTeX.

++++
$$
\pi=\int_{-\infty}^\infty\frac{dx}{1+x^2}
$$
++++

In LaTeX, pi is described as \(\pi\)