diff --git a/exampleSite/content/essays/asciidoctor-test/Bit Bit Loop.mp3 b/exampleSite/content/essays/asciidoctor-test/Bit Bit Loop.mp3 new file mode 100644 index 0000000..3d73209 Binary files /dev/null and b/exampleSite/content/essays/asciidoctor-test/Bit Bit Loop.mp3 differ diff --git a/exampleSite/content/essays/asciidoctor-test/customers.csv b/exampleSite/content/essays/asciidoctor-test/customers.csv new file mode 100644 index 0000000..70a2423 --- /dev/null +++ b/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 diff --git a/exampleSite/content/essays/asciidoctor-test/document-b.adoc b/exampleSite/content/essays/asciidoctor-test/document-b.adoc new file mode 100644 index 0000000..cf8fdc8 --- /dev/null +++ b/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[] diff --git a/exampleSite/content/essays/asciidoctor-test/hello-world.sh b/exampleSite/content/essays/asciidoctor-test/hello-world.sh new file mode 100644 index 0000000..476a1a8 --- /dev/null +++ b/exampleSite/content/essays/asciidoctor-test/hello-world.sh @@ -0,0 +1,3 @@ +#!/usr/bin/env bash + +echo "Hello, world!" diff --git a/exampleSite/content/essays/asciidoctor-test/index.adoc b/exampleSite/content/essays/asciidoctor-test/index.adoc index d958825..266c5b2 100644 --- a/exampleSite/content/essays/asciidoctor-test/index.adoc +++ b/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 <> to learn how to write paragraphs. +See <> to learn how to write paragraphs. -Learn how to organize the document into <>. +Learn how to organize the document into <> (with custom text). +Here we can go to <> + +Here we can go to <> + +Here we can go to <> + +=== 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> - "Hello World!" // <3> +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 +---- +<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 + +++++ +

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

+++++ + +=== Customize block subsitutions + +:release-version: 2.4.3 + +[source,xml,subs=attributes+] +---- + + org.asciidoctor + asciidoctorj + {release-version} + +---- == 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\) diff --git a/exampleSite/content/essays/asciidoctor-test/video.mp4 b/exampleSite/content/essays/asciidoctor-test/video.mp4 new file mode 100644 index 0000000..793cadd Binary files /dev/null and b/exampleSite/content/essays/asciidoctor-test/video.mp4 differ