edit: essays asciidoctor-syntax-test, add TODOs

exampleSite/content/essays/asciidoctor-test/customers.csv

@@ -0,0 +1,3 @@
+Name,Date,Spent
+Tom,2000-12-25,5.12
+Jerry,2000-12-25,10.24

exampleSite/content/essays/asciidoctor-test/document-b.adoc

@@ -0,0 +1,32 @@
+=== About AsciiDoc
+
+AsciiDoc is a lightweight and semantic markup language primarily designed
+for writing technical documentation. The language can be used to produce a
+variety of presentation-rich output formats, all from content encoded in a
+concise, human-readable, plain text format.
+
+The AsciiDoc syntax is intuitive because it builds on well-established,
+plain text conventions for marking up and structuring text.
+Someone unfamiliar with AsciiDoc can probably guess the purpose of
+many of its syntax elements just by looking at them.
+That’s because the elements of the syntax were carefully chosen to look
+like what they mean (a practice long employed by the tech industry).
+
+The AsciiDoc language isn’t coupled to the output format it produces.
+An AsciiDoc processor can parse and comprehend an AsciiDoc source document
+and convert the parsed document structure into one or more output formats,
+such as HTML, PDF, EPUB3, man(ual) page, or DocBook. The ability to produce
+multiple output formats is one of the main advantages of AsciiDoc.
+This capability enables it to be used in static site generators,
+IDEs, git tools and services, CI/CD systems, and other software.
+
+AsciiDoc bridges the gap between ease of writing and the rigorous
+requirements of technical authoring and publishing. AsciiDoc only requires
+a text editor to read or write, thereby offering a low bar to getting started.
+
+[[section-b]]
+=== Section B
+
+// tag::section-b[]
+This is section B from document-b.adoc
+// end::section-b[]

exampleSite/content/essays/asciidoctor-test/hello-world.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+
+echo "Hello, world!"

exampleSite/content/essays/asciidoctor-test/index.adoc

@@ -5,15 +5,48 @@ 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.
@@ -53,6 +86,8 @@ This paragraph will not be.
 
 == Text formatting
 
+=== Constrained bold, italic, and monospace
+
 It has *strong* significance to me.
 
 I _cannot_ stress this enough.
@@ -63,6 +98,7 @@ 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)
 
@@ -72,6 +108,7 @@ 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#.
 
@@ -83,11 +120,13 @@ 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`"
 
@@ -105,58 +144,105 @@ 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
+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]
+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]
+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.
 
-[#bookmark-b]#Inline anchors can be applied to a phrase like this one.#
-
 anchor:bookmark-c[]Use a cross reference to link to this location.
 
-[[bookmark-d,last paragraph]]The xreflabel attribute will be used as link text in the cross-reference link.
+[[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.
+See <<Paragraphs>> to learn how to write paragraphs.
 
-Learn how to organize the document into <<section-titles,sections>>.
+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
@@ -164,6 +250,7 @@ include::external.adoc[]
  ** Another nested list item
 * List item
 
+=== Unordered list max level nesting
 
 * Level 1 list item
 ** Level 2 list item
@@ -173,6 +260,7 @@ include::external.adoc[]
 ****** etc.
 * Level 1 list item
 
+=== Ordered list
 
 . Step 1
 . Step 2
@@ -180,6 +268,7 @@ include::external.adoc[]
 .. Step 2b
 . Step 3
 
+=== Ordered list max level nesting
 
 . Level 1 list item
 .. Level 2 list item
@@ -188,12 +277,14 @@ include::external.adoc[]
 ..... 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.
@@ -201,6 +292,7 @@ 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?::
@@ -210,6 +302,7 @@ Are cameras allowed?::
 Are backpacks allowed?::
 No.
 
+=== Mixed
 
 Operating Systems::
   Linux:::
@@ -230,6 +323,7 @@ Cloud Providers::
     . 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.
@@ -252,9 +346,10 @@ list continuation:: a plus sign (`{plus}`) on a line by itself
 |Column 2, Row 1
 |===
 
-
 == Images
 
+=== Block image macro
+
 image::sunset.jpg[]
 
 image::sunset.jpg[Sunset]
@@ -265,11 +360,47 @@ 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
 
@@ -280,12 +411,27 @@ image:sunset.jpg[Sunset,150,150,role=right] What a beautiful sunset!
 |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.
 
@@ -293,6 +439,7 @@ Normal line.
 
 Normal line.
 
+=== Literal block
 
 ....
 error: 1954 Forbidden search
@@ -301,6 +448,7 @@ absolutely fatal: operation lost in the dodecahedron of doom
 Would you like to try again? y/n
 ....
 
+=== Listing block with title
 
 .Gemfile.lock
 ----
@@ -316,6 +464,21 @@ 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]
@@ -327,25 +490,54 @@ get '/hi' do
 end
 ----
 
+=== Source block with callouts
+
+NOTE: callouts are always selectable, don't know why.
 
 [source,ruby]
 ----
-require 'sinatra' // <1>
+require 'sinatra' # <1>
 
-get '/hi' do // <2>
+get '/hi' do # <2>
-  "Hello World!" // <3>
+  "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
 
-NOTE: An admonition draws the reader's attention to auxiliary information.
+=== Admonition paragraph
 
-Here are the other built-in admonition types:
+NOTE: An admonition draws the reader's attention to auxiliary information.
 
 IMPORTANT: Don't forget the children!
 
@@ -357,6 +549,7 @@ WARNING: The software you're about to use is untested.
 
 IMPORTANT: Sign off before stepping away from your computer.
 
+=== Admonition block
 
 [NOTE]
 ====
@@ -373,6 +566,32 @@ 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
@@ -395,9 +614,71 @@ ____
 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"]
 |===
@@ -415,6 +696,7 @@ performance, portability.
 Empowers developers to easily create real, automated tests.
 |===
 
+=== Table with column containing AsciiDoc content
 
 [cols="2,2,5a"]
 |===
@@ -431,6 +713,39 @@ It's designed for:
 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%"]
 |===
@@ -452,6 +767,15 @@ A multi-line comment.
 Notice it's a delimited block.
 ////
 
+== Breaks
+
+=== Thematic break (aka horizontal rule)
+
+before
+
+'''
+
+after
 
 == Footnotes
 
@@ -461,3 +785,17 @@ 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\)