toyboot4e some mail
Oct 24, 2020

1. Basics

If you don’t know Asciidoctor, let’s see the features!

1.1. Paragraphs and line breaks

This is the first paragraph.

This is the second paragraph.
This is the second line of the second paragraph.

Source 
This is the first paragraph.

This is the second paragraph.
This is the second line of the second paragraph.

The indents are given by a CSS. You can modify term.css to remove them.
By the way, this block is one of the "admonition blocks".

1.2. Formats

strong, italic, line through, underline, big, small

Source 
*strong*, _italic_, [.line-through]#line through#, [.underline]#underline#, [.big]#big#, [.small]#small#

Not that good syntax actually!

1.3. Unordered list

  • 1

    This paragraph is "joined" to the list item using + symbol.
    This is one of the excellent features of AsciiDoc!

Source 
* 1
+
This paragraph is "joined" to the list item using `+` symbol.
This is one of the excellent features of AsciiDoc!

  • 2

    • 2-a

    • 2-b

Source 
* 2
** 2-a
** 2-b

1.4. Ordered list

  1. 1

    1. 1-a

    2. 1-b

  2. 2

  3. 3

Source 
. 1
.. 1-a
.. 1-b
. 2
. 3

1.5. Table

a b c

a

b

c

a

b

c
Source 
|===
| a | b | c

| a | b | c
| a | b | c
|===

1.6. UI icons (asciidoctor -a experimental)

  • Keyboard macros: cmd+shift+ctrl+opt+X

  • Menu icons: File  Save

  • UI buttons: OK

Source 
* Keyboard macros: kbd:[cmd+shift+ctrl+opt+X]
* Menu icons: menu:File[Save]
* UI buttons: btn:[OK]

1.7. Admonition blocks

One line admonition blocks
TIP: one line text
NOTE: one line text
WARNING: one line text
IMPORTANT: one line text
CAUTION: one line text
Another admonition block syntax 
[NOTE]
====
This is good when we want to write a big admonotion block!
====

2. Rich features

2.1. Footnotes

Footnote here: [1]

Footnote here: footnote:[It's nice if you can see this text with mouse hover. Such Asciidoctor extension _should_ exist and I would consider using it.]

2.2. Sidenotes

あああああああ

2.3. Mathjax

Use inline/non-inline stem block:

\[m \frac {\mathrm{d}^2 \mathbb{x}} {\mathrm{d} t^2} = \mathbb{F} \\ \int m \frac {\mathrm{d}^2 \mathbb{x}} {\mathrm{d} t^2} \mathrm{d}t = \int \mathbb{F} \mathrm{d}t \\ \left[ m \frac {\mathrm{d} \mathbb{x}} {\mathrm{d} t} \right]_{t_1}^{t_2} = \left[ \mathbb{F} t \right]_{t_1}^{t_2} \\\]
Source 
[stem]
++++
m \frac {\mathrm{d}^2 \mathbb{x}} {\mathrm{d} t^2} = \mathbb{F} \\
\int m \frac {\mathrm{d}^2 \mathbb{x}} {\mathrm{d} t^2} \mathrm{d}t = \int \mathbb{F} \mathrm{d}t \\
\left[ m \frac {\mathrm{d} \mathbb{x}} {\mathrm{d} t} \right]_{t_1}^{t_2} = \left[ \mathbb{F} t \right]_{t_1}^{t_2} \\
++++

2.4. Source code block

Code block with "callouts":

Here! We! (1)
Come!!! (2)
1 First callout
2 Second callout
Source 
[source]
----
Here! We! (1)
Come!!! (2)
----
<1> First callout
<2> Second callout

2.5. Advanced source code blocks

Prism.js extensions:

Keep Markup extension

This is mainly for keeping Asciidoctor callouts after processing Prism.js to highlight code:

fn main() { (1)
    println!("Hello, world!");
}
1 callout style is kept!
Source 
[source,rust]
----
fn main() { (1)
    println!("Hello, world!");
}
----
<1> callout style is kept!

Line Numbers extension

fn main() {
    println!("Hello, world!");
}
Source 
[.line-numbers]
[source,rust]
----
fn main() {
    println!("Hello, world!");
}
----
Unfortunatelly, [source%number] doesn’t work when using Prism.js.

Diff Highlight extension

fn main() {
+     println!("Hello, world!"); (1)
}
1 diff highlight!
Source 
[source,diff-rust diff-highlight]
----
fn main() {
+     println!("Hello, world!"); (1)
}
----
<1> diff highlight!

Match braces extension

We need the rainbow parentheses for no reason. However, it’s not working. Help me out with it!

((((hello world) world) wolrd) world)

3. Tricks

3.1. Using attributes to create links

adbook adbook adbook. By the way.. isn’t it nice if we don’t have to write URL every time we write adbook? That’s possible! We can use AsciiDoc document attributes with such syntax: {ad_book}.

Source 
{adbook} {adbook} {adbook}. By the way.. isn't it nice if we don't have to write URL every time we write {adbook}? That's possible! We can use AsciiDoc _document attributes_ with such syntax: `{ad_book}`.

Document attributes can be set in each .adoc file:

:adoc: link:https://github.com/toyboot4e/adbook[adbook]
// consider defining document attributes globally. options:
// 1. `include:path/to/file/that/lists/links/as/attributes[]`
// 2. `book.ron` (see below)

Or in book.ron:

book.ron content 
// RON format (with or without outermost parentheses)

// toyboot4e.github.io/adbook
base_url: "/adbook",
src_dir: "src",
site_dir: "docs",

authors: ["adbook"],
title: "adbook demo site",

// don't generate `all.html`
generate_all: false,

use_default_theme: true,
includes: [
    "static/img",
],

converts: [
    // "404.adoc",
],

// `asciidoctor` command line options
adoc_opts: [
    ("-a", [
        // default Handlebars template file, relative to the source directroy
        "hbs@=theme/hbs/article.hbs",

        // css
        "linkcss",
        "stylesdir@={base_url}/theme/css",
        "stylesheet@=article.css",

        // image
        "imagesdir@={base_url}/static/img",
        "imagesoutdir@={src_dir}/static/img",

        // preferences
        "hardbreaks",
        "sectnums",
        "sectnumlevels@=2",
        "tabside@=4",

        // features
        "experimental",
        "stem@=latexmath",
        "icons@=font",

        // links (available with `{name}` syntax in AsciiDoc files)
        "adbook=https://github.com/toyboot4e/adbook[adbook]",
        "rust=https://www.rust-lang.org/[Rust]",
        "asciidoctor=https://asciidoctor.org/[Asciidoctor]",
        "mdbook=https://github.com/rust-lang/mdBook[mdBook]",
        "handlebars=https://handlebarsjs.com/[Handlebars]",
        "prismjs=https://prismjs.com/[Prism.js]",

        "adoc=https://asciidoctor.org/[Asciidoctor]",
        "prism=https://prismjs.com/[Prism.js]",
    ]),
]

book.ron is embedded to this file with: include::../book.ron[].

The path is relative to the source directory. For more information, see the corresponding page of the manual.
1. It’s nice if you can see this text with mouse hover. Such Asciidoctor extension should exist and I would consider using it.