edit: essays asciidoctor-syntax-test, add TODOs

This commit is contained in:
leafee98 2024-01-26 22:35:54 +08:00
parent f9e13a1b76
commit 673ea42546
6 changed files with 390 additions and 14 deletions

View file

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

View file

@ -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.
Thats 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 isnt 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[]

View file

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

View file

@ -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>
"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 <!--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\)

Binary file not shown.