Asciidocの始め方

2025-03-10 · 13 分で読了 · asciidoc

Asciidoc の始めかた

v.1.0, 2024.9.9

マークアップ方式でテキスト記述。htmlやpdfに変換できる。

md(マークダウン)より方言が少なく、表(table)の表現能力は高いらしい。

1環境 bookwarm (debian 12.6)

1$ asciidoctor -v
2Asciidoctor 2.0.18 [https://asciidoctor.org]
3Runtime Environment (ruby 3.1.2p20 (2022-04-12 revision 4491bb740a) [x86_64-linux-gnu]) (lc:UTF-8 fs:UTF-8 in:UTF-8 ex:UTF-8)

Emacsで書いてます。
拡張子はadocが標準みたい
- elisp : package-list-packgeからadoc-modeとmarkup-faces(関連)をinstall
- 以下をinits/ (init-loader管理)においた

 1;; asciidoc mode from https://github.com/sensorflo/adoc-mode
 2;;https://qiita.com/YasuhiroABE/items/76d4f17792aded97ea94
 3;(load "~/lib/elisp/markup-faces.el")
 4;(load "~/.emacs.d/elpa/markup-faces-2024218.1085/adoc-mode.el")
 5;(load "~/lib/elisp/adoc-mode.el")
 6;(load "~/.emacs.d/elpa/adoc-mode-2024218.1085/adoc-mode.el")
 7(autoload 'adoc-mode "adoc-mode" nil t)
 8(add-to-list 'auto-mode-alist '("\\.adoc\\'" . adoc-mode))
 9;; update timestamp for adoc-mode
10(add-hook 'adoc-mode-hook (lambda()
11                (require 'time-stamp)
12                (add-hook 'before-save-hook 'time-stamp)
13                (custom-set-variables
14                 '(time-stamp-active t)
15                 '(time-stamp-start "date: ")
16                 '(time-stamp-format "%Y-%02m-%02dT%02H:%02M:%02S%:z")
17                 '(time-stamp-end "$"))))

1.Asciidoc形式で書く

紹介,参考サイトいろいろ

Asciidoc Language Documentation

Asciidoctor Documentation site,上記のroot

Asciidoctor 文法クイックリファレンス(日本語訳)

asciidoc memo

Asciidocチートシート

AsciiDoc vs Markdown 比較チートシート

簡単な文法

1.0 セクションヘッド
イコール(=)がレベル0のセクションヘッド。レベル5まであるそうです。
1.1　テキストフォーマット
#や*で挟んだ範囲がマークアップ対象。
マークアップ箇所前後の半角空白1文字分が大事です
[の前と#の後ろに空白入れるのが大事
- 原稿
```
 1**bold太字**
 2_いたりっく_
 3
 4いろつけ #しなもん# マーカー
 5[red]#色指定# 空白大事
 6
 7[yellow-background]#背景色#
 8[red yellow-background big]#文字色　背景色　サイズ#
 9
10とと [.big]#おおきく# なったら　
11とと [big]#おおきく# bigの前のドットがなくてもok!bigより大きい字は不明
12とと [small]#小文字# こもじ
13
14免許 [line-through]#とりけし# なったら
15かせん [underline]#下線# ひいて
16うえせん [overline]#上線# ひいて
17
18ととと ^上付き^ 文字と
19ほげ ~下付き~ 文字
20
21////
22以下はrightのみ効いた
23[center]#まんなか#
24[left]#左#
25[right]#右#
26[justify]#ちょうど#
27////
```
- 出力結果
bold太字 いたりっく
いろつけしなもんマーカー色指定空白大事
背景色文字色　背景色　サイズ
ととおおきくなったら　ととおおきく bigの前のドットがなくてもok!bigより大きい字は不明とと小文字こもじ
免許とりけしなったらかせん下線ひいてうえせん上線ひいて
ととと ^上付き文字とほげ _下付き文字
asciidocをpandoc/hugoで処理した時、文字色表示がうまくできていません。sorry! そのうち解決します。
```
1行頭1文字スペースはリテラル(1行)
```
- 改行は +
- コメントは //
- 改ページは =<<<=　これは未確認。pdfで効くのかな?
- 水平罫線　'''　これはバッククォートではなくクォート(アポストロフィ)です。 3つ以上続けても変化はないようです。
- エスケープ +3つで挟む {esc} \{esc} 変換されなくなるみたい。
- バックスラッシュもエスケープするみたい。csvファイル読み込みの。
- バッククオート　`で挟むとコマンド表示
- クオートで挟むとパス表示 'hoge/fuga/as.adoc' でも hoge/fuga/as.adoc と違いがわからず。
- 特殊文字 (C) (R) (TM) – … -> <- > < ¶ 左の文字は右になります © ® ™ — … → ← ⇒ ⇐ ¶
- 脚注とアイコン
  - 原稿
```
1* ほげとはfootnote:[ここの内容が脚注になります]
2* icon:twitter[role=aqua] 他のアイコンは不明???
```
- 出力
  - ほげとは^[1]
  - // 他のアイコンは不明???

1.2 リスト形式

 1* レベル1
 2** れれれ2
 3*** レベル3
 4
 5-[*] check +
 6-[x] check2 +
 7-[ ] noch3 +
 8- checkboxは改行マーク要 +
 9
10. 手順1
11. 手順2
12.. 手順2-2
13
141から始めるためには、ここに何か文字を入れる。
15
16. 手順1
17. 手順2
18[arabic]
19.. 手順2-2 オプションとしてarabicと書けばaが数字になります。
20
21[square]
22* item 1 オプションでsquare 指定しました。
23* item 2

レベル1
- れれれ2
  - レベル3

-[*] check
-[x] check2
-[ ] noch3

checkboxは改行マーク要
手順1
手順2
1. 手順2-2

1から始めるためには、ここに何か文字を入れる。

手順1
手順2
1. 手順2-2 オプションとしてarabicと書けばaが数字になります。
item 1 オプションでsquare 指定しました。
item 2

1.3 囲んでブロックにする。
Summary of structural containers
Summary of built-in blocks
(1) ====で囲む。Example Blocks. example type. compound.
Example 1. st
- =4つで囲んだ例
  - =の上の.がタイトル
    - Exampleというのがつく [caption="Hoge: "]としら変更できる
[example]と同じ,ただし上記のように内部ブロック書けず、単純標記だけ
```
1[example]
2ほげ
3ふが
```
ほげふが
(2) —-で囲む。Listing Blocks, listing type. verbatim.
title
```
1* ハイフン(-)4つで囲んだ例, pre
2** ハイフン(-)の上の行に.titleとすると、左上に見られるようにtitleが表示されるが、なくてもよい
3*** ソースコード書くときはこの方法。言語指定はハイフン前の上の行に[source, octave]などと書く
```
(3) ** で囲む。 Sidebars, sidebar type. compound.
hoge
- アスタリスク4つで囲むと、タイトルを中央表示したブロックになる
- *の直前の.hogeがタイトルになる
  フレームで囲まれている
  リスト形式にしない場合、改行記号(+)必要
(4) ++ で囲む。Passthrough blocks, pass type, raw
改行されないので注意。

1 ** 2 * 3

htmlのタグをかける!

h2タグでこんなふうHOGE

(5) ピリオド4つで囲む。 Literal Blocks, literal type. verbatim.

1period
2eeeee

-ハイフンと出力見た目同じ。改行不要

(6) // で囲むと、ブロックコメント。Comment Blocks, comment type

1////
2ブロックコメント
3ととと
4////

(7) _ _ _ _ アンダーバー4つで囲むとquote

quote

または、[quote] 宣言

1[quote]
2quote block +
3quoteとオプション

quote block
quoteとオプション

(8) ハイフン2つ。 open type. compound.

ハイフン2つはオープンブロック,出力??

(9)ラベルをつけたいときはコロン::で区切る

原稿

1くら::
2ssss
3すし::
4xad

変換出力
くら
ssss
すし
xad

(10) インラインはバッククオート｀#｀

1.4 リンク、イメージ、インクルード

(1) URLは直書き

https://takumon.github.io/asciidoc-syntax-quick-reference-japanese-translation/

後ろにかっこ[]つけたら、URL見えず、名前だけ

https://takumon.github.io/asciidoc-syntax-quick-reference-japanese-translation/%5BAsciidoc　クイックリファレンス]

Asciidoc　クイックリファレンス

(2) 文書内外参照:　linkとanchor

他文書へのリンク

1link:文書名[表記文字]
2link:a.adoc[参考文献]

参考文献(a.adocがあれば開きます)

html文書限定リンク

ファイル名には拡張子不要。この場合はa.htmlを意味。

1<<ファイル名#タグ, 表記文字>>
2<<a#aam,a.htmlへのリンク>>

a.htmlへのリンク(a.htmlがあれば開きます)

同一文書内link,anchorが必要です

1<<アンカー名,表示名>>
2
3<<anc1,anc1へのリンク>>
4
5<<ancc,anccへのリンク>>

アンカーをつける必要があります。ただし、asciidocで作成したhtmlファイルのセクション名には idタグが付与されているので、anchorの設定は不要。ただし、anchorとなったセクション名のピリオドや英大文字が変換されているので注意。下記のanchor説明を参照。

anchorをつける

1[[anc1]]
2
3[#anc2]
4
5<<ancc>>
6
7anchor:ancc[]

asciidocで作成したhtmlファイルのセクション名には idタグが付与されているので、anchorの設定は不要。

引用元ではセクション名を書くだけ。ただし、最初にアンダーバーを付与することが必須!。

また、ピリオドや英大文字が変換されているので注意

adocを他のmarkup形式に変換するとき、このアンダーバーのリンクが引き継がれない場合があるので注意。

1<<_1_asciidoc形式で書く,Asciidoc形式で書く>>
2
3<<_1_5_admonotions_パラグラフをアイコン標記,アイコン標記>>
4
5<<_2_1_環境構築,変換出力環境構築>>

こんなふうになります。

Asciidoc形式で書く

アイコン標記

変換出力環境構築

(3) 画像

(3-1)インライン表示

原稿

1インライン表示 image:./fig/sp.png[]

変換出力

インライン表示

(3-2)ブロック表示

コロン2つ

原稿

1image::./fig/sp.png[]

変換出力

(4) include　他ファイルを取り込む

include::./hoge.adoc[]

[]のなかに[3-5]などとして、引用する行を指定できる

1.5 Admonotions:: パラグラフをアイコン標記

IMPORTANT, NOTE, TIP, WARNING, CAUTIONをブロック表示

ヘッダ部(プリアンブル)に以下を記述する

:icons: font

宣言なければ、アイコン無しで文字で表示

改行しないと反映しない場合があるので注意!!

原稿

 1[IMPORTANT] 重要事項 改行しないと反映されない
 2
 3[IMPORTANT]
 4重要事項
 5改行するとok
 6
 7IMPORTANT: 重要事項 改行しない場合はコロン:で区切る
 8
 9[NOTE]
10のーと
11
12[TIP]
13ちっぷす
14
15WARNING: 警告
16
17
18CAUTION: 注意

変換出力

asciidocをpandoc/hugoで処理する時、以下のアイコン表示がうまくできていません。sorry! そのうち解決します。

[IMPORTANT] 重要事項改行しないと反映されない


//	重要事項改行するとok


//	重要事項改行しない場合はコロン:で区切る


//	のーと


//	ちっぷす


//	警告


//	注意

1.6 式を書く

式は :stem:を宣言

原稿

 1インライン形式の式表示
 2
 3インラインの式 stem:[ \int f(x)] 記述
 4
 5:stem: latexmath
 6としたらLatex記法
 7
 8改行形式にしたいときは
 9
10[stem]
11++++
12\sum_0^\infty f(z) \\
13\int_0^\infty \sqrt{2}\dfrac{d}{dt}f(t)\sin{\theta(\tau)}d\tau
14++++

変換出力

インライン形式の式表示

インラインの式 \$ ∫ f(x)\$ 記述

としたらLatex記法

改行形式にしたいときは

$$\sum_0^\infty f(z) \\ \int_0^\infty \sqrt{2}\dfrac{d}{dt}f(t)\sin{\theta(\tau)}d\tau$$

1.7 表をつくる

基本
1. 1行の始まりは|とし、行終わりには|をつけない。
2. 最初の1行は改行を含めずに記述。

1|===
2| hoge | fuga | pon
3
4|a
5|v
6|c
7|===

hoge	fuga	pon
a	v	c

cols属性が未指定のときは、最初の1行目のカラム数がテーブル列数
最初の行の後が空行のときは、最初の行はヘッダ行とみなされる。
以下の設定を|===の前に指定する
- [cols="2*", options="header"]
  cols属性の*は繰り返しを表す演算子である。この場合4つのカラム全てにデフォルトのフォーマットが適用されます。ヘッダー行が１行で定義されていない場合は、cols属性でカラム数を指定し、options属性を指定する必要があります。
- [cols="1,1,2", options="header"]
  colsでこのように指定すると、カラム数は３で、それぞれの列幅が1:1:2になるように表示されます。
CSVデータを使う

1[format="csv", options="header"]
2|===
3アーティスト,トラック,ジャンル
4Baauer,Harlem Shake,Hip Hop
5The Lumineers,Ho Hey,Folk Rock
6|===

アーティスト	トラック	ジャンル
Baauer	Harlem Shake	Hip Hop
The Lumineers	Ho Hey	Folk Rock

CSVデータ読み込み

1[format="csv"]
2|===
3include::./hoge.csv[]
4|===


a	b	c
s	d	e

揃え記号
- < ^ >で、横方向の　左寄せ、中央、右寄せ
- dot(.)を前につける(.< .^ .>)と、縦方向の揃え
- n+でセル結合
まとめて設定するときは、option部で指定

1[cols="^,<,>"]
2|===
3|中央 |左 |右
4
5|center
6|left
7|right
8|===

中央	左	右
center	left	right

|の前に、揃え記号を記述すると、セルごとの揃え指定

1|===
2<|左寄せ ^|中央 >|右
3
42+^|2セル結合、中央寄せ
5<|ひだり
6|===

左寄せ	中央	右
2セル結合、中央寄せ		ひだり

こんなこともできます

クイックリファレンス日本語訳,整形,セル結合から引用,一部改変

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

e:emphasis=italicized, s:strong=bold, m:monospace,


1	2	3	4
5	`6`		`7`
8
9	`10`
z	a	`bbc`	A

1.8 ヘッダ, frontmatter

 1:icons: font
 2:Author: who am i
 3:Email: who@hoge
 4:Date: 2024.9.1
 5:Revision: 0.01
 6:lang: ja
 7:toc: 目次
 8:imagesdir: hoge/images
 9:homepage: http://hohe.org
10:myname: HHH

lang指定がないとlang=enになるので、jaと指定したほうが平和かもしれません。

ヘッダ直後の1行が、メタタグのauthorに設定されるようです。

hugoで処理するなら、mdと同じ形式のfrontmatterが必要です。

 1---
 2title: "hoge"
 3data: 2025-09-09
 4draft: true
 5categories:
 6 - hoge
 7tags:
 8 - fuga
 9series:
10 - gaoo
11description: "GAOOO"
12---

1.9 その他

アトリビュート
ヘッダ部で宣言した名前:hoge:と中括弧{hoge}を置き換えしてくれるようです。
リビジョン{Revision}0.01
マイネーム{myname}HHH
ヘッダ直後の1行が、メタタグのauthorに設定されるようです。
スタイルにarticle(デフォルト)や bookがあるそうです
プリアンブルに :doctype: book 指定?
または変換オプション`-d book`指定

2.変換出力

2.1 環境構築

asciidoc形式で書いた文書をhtmlに変換するために、asciidoctorをapt(synaptic)でinstall
asciidoctor: adocで書かれたコンテンツをHTML5,DocBook,PDFなどに変換
asciidoc形式で書いた文書をpdfに変換するために、asciidoctor-pdfをgem(aptにはないので注意)で install
asciidoctor-pdfはasciidoctorとpawnを用いてpdfに変換します
gemはrubyのライブラリ

1#apt install asciidoctor
2#gem install asciidoctor-pdf

2.2 htmlに変換出力

1$asciidoctor hoge.adoc

数式もきれいに展開できます。

2.3 pdfに変換出力

オプションがないと、日本語文字が豆腐になります。

1$asciidoctor-pdf  -a pdf-theme=default-with-fallback-font hoge.adoc

オプションは -a scripts=cjk という紹介も有りましたが、私の環境では上記でした。

また、-a scripts=cjkと併用する紹介もありますが、効果はよくわかりません (fontは同じでした)。少なくとも、pdfサイズがかなり大きく(2倍近く)なりました。

asciidoctor-pdfで日本語を含むPDFの出力を行う

このオプションについての情報はここのスレッドを参考にしてください。下の方にいろいろな設定も書いてあって遊べるかもしれません。

日本語フォントしょぼいという評判? ipaではない。

pdf日本語font設定 thread
- docker-asciidoctorを使う方法
  default-thema.ymlを編集してhoge.ymlで保存
  asciidoctor-pdf hoge.adoc -a pdf-style=hoge.yml
  docker-asciidoctorとはまた別??
- asciidoctor-pdfで日本語を含むPDFの出力を行う,2021年の情報
- 備忘録: asciidoctorでpdf作成を行うメモ(Ubuntu18)

pdfに数式を出力したい時

1$asciidoctor-pdf  -a pdf-theme=default-with-fallback-font -r asciidoctor-mathematical hoge.adoc


//	式をpdf上に出力するにはasciidoctor-mathematicalが必要です。

数式出力環境構築:package install

1apt install cmake
2apt install ruby-dev
3gem install asciidoctor-mathematical


//	asciidoctor-mathematicalをgemしたら良いそうですが、私の環境ではinstallエラーになりました。 include pathを修正したら良さそうなのですが、ソースの修正が必要? かもしれないので、pendingです。

HUGO

Hugoで管理すると、githubでの公開展開が楽になるそうです。

Hugoをaptしたら、gitも入りました。

Hugo + AsciidocでGitHub Pages上にブログを公開するまでその1

以下のことが現状です。

frontmatterは、mdと同じ形式で記述することが必要です。書かないtitleなどが表示されません。
文字の色つけができていません。
cautionなどをアイコン表示することができていません。
github-actionsを用いてhtmlを自動生成する際は、いろいろ知識が必要となるようです。

その他

bundlerとはgemを管理するためのツールで複数のgemの依存関係を保ちながらgemの管理ができます。

gem install bundler

感想

org-modeとAsciidocの比較感想です

Asciidocは凝った html出力を簡単に作成できる。html出力を主眼。
org-modeはスケジュールやTodo管理、文章構成検討(foldして章ごと移動できる)が簡単。とにかく書くことが目的ならorg。
TeX出力ならorg-modeの方が扱いやすそう
include文が使えるので、とっても見やすく文書が作成できる。
Asciidocの文書をhugo/github-actionsで処理して公開する場合は、もう少し知識が必要なようです。 include使うときは特に…

1. ここの内容が脚注になり一番下に表示されます