1. はじめに

AsciiDocの記述方法でよくつかうものを記載します。さらに多くの記述を使いたい場合は以下を参照してください。

2. コメント類

コメント部分は、最終出力から除外されます

 // 			:行頭でその行はコメントになる
 ////から////	:ブロック内がすべてコメント

3. 文字飾り

基本

`*_`でサンドイッチすることで表現。空白含む場合は **単語A 単語B** の様に２個ずつつけるとよい

結果	記述
太字の語句イタリック *太字のイタリック* `モノスペース`	太字の語句 _イタリック_ _太字のイタリック_ `モノスペース`

少し拡張(アンダーラインなど)
結果	記述
アンダーライン通常文字 vs 小さい文字 vs 大きい文字取り消し線	[.underline]#アンダーライン# 通常文字 vs [.small]#小さい文字# vs [.big]#大きい文字# [.line-through]#取り消し線#

4. 見た目(ボタンとアイコン)

記述	説明
kbd:[Ctrl+C]	`Ctrl`+`C`, `Ctrl`+`Shift`+`V`
btn:[ボタン]	ボタン,OK,CANCELなど
{cboxOn}/{cboxOff}	`[✔]`/`[ ]` 以下の事前マクロ定義必要 :cboxOn: pass:normal[``{startsb}✔{endsb}``] :cboxOff: pass:normal[``{startsb}{nbsp}{endsb}``]
{cboxgOn}/{cboxgOff}	`✔`/ 以下の事前マクロ定義必要 `:cboxgOn: kbd:[✔]` `:cboxgOff: kbd:[{nbsp}]`
menu:ファイル[保存]	ファイル保存階層化:`>`でサブメニュー化 menu:ファイル[保存 > Sub > A] → ファイル保存 Sub A
{OK}	事前に定義 `:OK: pass:[<span style="font-family: monospace">😀</span> ]` 😀 アイコンはユニコードで色々定義,Unicodeの絵文字 😍(`😍`)、🙅(`🙅`)、🌈(`🌈`) などなど

5. セクション（章節）

=␣<セクション>で始める行がセクションになる。セクションの区切りには空白行が必要。=の数でセクションレベルが決まる

= ドキュメントのタイトル
== 章最初のタイトル
=== 節のタイトル
==== 文節のタイトル
===== さらにその下タイトル
====== さらにさらにタイトル
== 章次のタイトル

6. 箇条書き

*␣<項目>、-␣<項目>で始める。異なる記号を使えば、階層的に表現できる
形状変更は[square],[circle],[disc]を指定
チェックボックスは*␣[ ]␣ <項目> で []の中に[x]or[*]or[ ]

箇条書き(項目)
結果	記述
項目1 サブ項目1 サブ項目2 サブ項目の中に複数行に渡る大きな大きなブロックを記述できる項目2 形状変更 square circle disc チェックボックス checked also checked not checked	- 項目1 * サブ項目1 * サブ項目2 + -- サブ項目の中に複数行に渡る大きな大きな大きなブロックを記述できる -- - 項目2 形状変更 [square] * square [circle] * circle [disc] * disc チェックボックス * [] checked [x] also checked * [ ] not checked

箇条書き(項目)

結果

記述

項目1
- サブ項目1
- サブ項目2
  
  サブ項目の中に複数行に渡る大きな大きなブロックを記述できる
項目2

形状変更

square

circle

disc

チェックボックス

checked
also checked
not checked

- 項目1
	* サブ項目1
	* サブ項目2
+
--
サブ項目の中に複数行に渡る大きな大きな大きな
ブロックを記述できる
--
- 項目2
形状変更
[square]
* square
[circle]
* circle
[disc]
* disc
チェックボックス
* [*] checked
* [x] also checked
* [ ] not checked

7. 箇条書き（数字）

.␣<項目>（ピリオド）で始める。階層構造は…␣と連ねる。
番号は[arabic]/[decimal]/[loweralpha]/[upperroman]などで階層ごとに指定

箇条書き(数字)
結果	記述
項目1 項目1のタイトルサブ項目の中にブロックを記述できるサブ項目1 サブ項目2 サブサブ1 サブサブ2 サブ項目の中にブロックを記述できる項目2	. 項目1 + -- サブ項目の中にブロックを記述できる -- .. サブ項目1 .. サブ項目2 [decimal] ... サブサブ1 ... サブサブ2 + -- サブ項目の中にブロックを記述できる --

8. ラベル

<ラベル名>::(後ろのコロン２つ）でラベルをつける。コロンを増やせば階層化できる。
[horizontal]指定で一行目から、行が開始される

ラベル
結果	記述
第一項第一項の定義さらにそのサブサブの内容	第一項:: 第一項の定義さらにそのサブ::: サブの内容

9. ブロックラベル

.ブロックラベル(ドット）でラベルをつける。スペースは不要。箇条書き（数字）になってしまう。

10. ブロック

以下の記号４文字のキーワード行で囲む。それぞれ動作、意味が異なる
$$～ $$で囲むとパスされる →　エスケープ方法

1	`--`	(ハイフンx2)	オープンブロック。汎用ブロック。オープンブロックはpassとtableを除き、他のブロックとして機能できます。
2	`----`	(ハイフンx4)	コードブロック。コードもしくはファイルの表示(リスティング)
3	`....`	(ドット)	リテラルブロック。書いたままに表示させたいとき。
4	`====`	(イコール)	サンプルブロック。通常で枠ができるフォーマット。[caption="キャプション名"]で制御。`=` のみで、ナンバリングもキャプションも除去される様子
5	`++++`	(プラス)	インラインブロック。変換せずにHTML出力,パススルー/インライン,バックエンドのマークアップの書式を記述する
6	`****`	(アスタ)	サイドバーブロック
7	`____`	(アンダーバー)	ブロッククウォート（引用かな?）

コードブロックに指定できる言語: C,C++,HTML,Python,Ruby,JavaScript,JSON,Java,XML,YAML ,Clojure,CSS,Delphi,diff,ERB,Go,Groovy,HAML,Lua ,PHP,Sass,SQL,Taskpaper

結果	記述
JavaScript例（タイトル） `var a = "test"; echo(a,b);`	[source,JavaScript] .JavaScript例（タイトル） ---- var a = "test"; echo(a,b); ----

11. 警告、重要、情報などのアイコン

適用するには属性 :icons: fontが必要

結果

記述

ノート(NOTE)

警告(WARNING)

重要(IMPORTANT)

チップス(TIP)

注意(CAUTION)

NOTE,WARNING,IMPORTANT,TIP,CAUTION

単行の場合:

NOTE: <内容>

ブロックの場合: (サンプルブロックを使う)

[NOTE]
====
<内容>
====

■カスタムアイコンの利用方法

PNGもしくはSVGデータとしてこれらのアイコンを変更することができます。iconsフォルダにファイル名"NOTE,WARNING,IMPORTANT,TIP,CAUTION"で、拡張子を.svgもしくは.pngのファイルを配置すればよい。

アイコンの属性を変更
:icons: image	アイコンのタイプをイメージに変更
:iconsdir: ./icons	アイコンの配置場所をiconsに変更（未設定だと{imagesdir}/icons)
:icontype: svg	画像の種類を指定 svg or png

属性変更はファイルの先頭がよい。途中で切り換えるとうまくいかない場合があった。

※その他方法: 以下でも一時的に変更することも可能。拡張子は:icontype: xxxと同じなら拡張子を省略可能です

[NOTE, icon=NoteCustom.svg ]
====
カスタムNOTEアイコン
====

12. 区切り線

---（ハイフン）3個のみ。

区切り線
結果	記述
	`---`

13. 改行

␣+で繋ぐ。
もしくは[%hardbreaks]で段落全体で改行を有効にする（段落毎にリセットされる）。ドキュメント全体で設定するなら:hardbreaks:属性をつけるとよい。個別の解除は {set:hardbreaks!} 。
New! {NoWrap}… hoge hoge …{End}で自動改行を抑制
config.adocで以下を事前定義してカスタマイズしている。+ 表のセル幅が狭く改行される場合に、ヘッダ行に指定することでヘッダ行の幅でセル幅を抑制できる。(結構有効)。
```
	// Macro
	:NoWrap: pass:[<span style="display:inline-block;white-space:nowrap;">]
	:Wrap: pass:[<span style="display:inline;white-space:wrap;">]
	:End: pass:[</span>]
```

改行
結果	記述
１行目２行目	１行目 + ２行目

14. 段落揃え

[.text-left],[.text-right],[.text-center]で調整する
[.text-justify]はよくわからない
[align=xxxx]、 xxxx=left,center,right,…でもよい

結果	記述
右寄せセンター左行内で部分的右 [右]	[.text-right] 右寄せ [.text-center] センター [.text-left] 左行内で部分的右 [.right]##[右]##

This paragraph is aligned right

This paragraph is aligned center

This paragraph is aligned left. This paragraph is aligned left. This paragraph is aligned left. This paragraph is aligned left. This paragraph is aligned left. This paragraph is aligned left. This paragraph is aligned left.

This paragraph is justified, which is the default.This paragraph is justified, which is the default.This paragraph is justified, which is the default.This paragraph is justified, which is the default.

15. コメント

// コメント行

////
	コメントブロック
////

16. エスケープ方法

記述	表現
$$ ～ $$で囲む	通常文字になる
+++～+++で囲む	HTML制御になる(インライン要素)
pass:[～]で囲む	HTML制御になる(インライン要素、同上）
\(backslash)	次の文字の制御のみキャンセル。\boldや\{lt}など
※ その他は特殊記号で記載すること。

17. 特殊記号

特殊記号は{}を使う。もしくは&#<10進数>; or &#x<10進数>;など。

特殊記号の一覧
記号 * ({}で囲む)	表現
dollar	$(ドル): $ or $ ※これは存在しないので、自身で`:dollar: $`を定義すること
sp	スペース１文字
nbsp	ノンブランクスペース文字
zwsp	幅無スペース
quot	`"` (ダブルクウォート)
apos	`'` (アポストロフィー}
backtick	` (バッククウォート)
lsquo	`‘`(開始シングルクウォート)
rsquo	`’`(終了シングルクウォート)
ldquo	`“`(開始ダブルクウォート)
rdquo	`”`(終了ダブルクウォート)
deg	`°`(角度)
plus	`+`(プラス)
brvbar	`¦`
vbar	`\|`(論理和)
amp	`&` (アンパサンド)
lt	`<` (smaller than)
gt	`>` (gretar than)
startsb	`[` (開始カギカッコ）
endsb	`]` (終了カギカッコ)
caret	`^` (キャレット)
asterisk	`*` (アスタリスク)
tilde	`~` (チルダ)
backslash	`\` (バックスラッシュ)
two-colons	`::` (2つのコロン)
two-semicolons	`;;` (2つのセミコロン)
cpp	``C`` (C?)
wj
blank
empty

18. 色

[色色-background]#コンテンツ#で指定する

赤いコンテンツ、黄色の背景 ← [red yellow-background]## 赤いコンテンツ、黄色の背景 ##

色名の一覧はwikiのWebColor一覧から取れる

HTML color names
この内の基本の16種の色のみ定義されている

asciidoctor-pdfは以下の定義みたい(rubyの中)

c:\Ruby24\lib\ruby\gems\2.4.0\gems\asciidoctor-2.0.10\data\stylesheets
asciidoctor-default.css

vs-codeプラグインは以下

%USERPROFILE%\.vscode\extensions\asciidoctor.asciidoctor-vscode-2.8.3\media\
asciidoctor-default.css

一覧

■■■■■■■ aqua `([aqua]##■...■## aqua )`	■■■■■■■ black	■■■■■■■ white
■■■■■■■ fuchsia	■■■■■■■ green	■■■■■■■ lime
■■■■■■■ maroon	■■■■■■■ navy	■■■■■■■ olive
■■■■■■■ purple	■■■■■■■ red	■■■■■■■ silver
■■■■■■■ teal	■■■■■■■ yellow	■■■■■■■ yellow

※色を拡張したければインラインで定義するか、CSSを拡張するかです。

インラインで拡張

:SpanRed: pass:[<span style="color:#FF00FF;background-color:#00FFFF">]
// Spanの終了は共通{SpanEnd}
:SpanEnd: pass:[</span>]

このように定義しておいて
{SpanRed} 適当な文字列 {SpanEnd} → 適当な文字列

CSSで拡張

未記載

The application is called MyApp².

example-caption=
figure-caption=Figure

Red `sum_(i=1)\^n i=(n(n+1))/2`$ ←AsciiMathML formula

pass_attribute=the '' ※ passすると[%hardbreaks]などリセットされちゃう

lang={lang}
menu=File Save
keyboad=F11
docdate=2021-04-23
user-home=C:\Users\AA004035

19. 独自のマクロみたいなの

HTML文法における id / class 指定の対応

<div id="baz" class="foo bar">

idは要素そのもののユニークなID、classはCSSの指定でスタイルを指定可能。
これは以下の２通りで表現可能
[#<ID>.<CLASSList1>.<CLASSList1>] ⇐ これでよいと思う
もしくは
[[<ID>]]
[role="<CLASSList1> <CLASSList1>]

	[#baz.foo.bar]
	----
	block
	----
もしくは
	[[baz]]
	[role="foo bar"]
	----
	block
	----

xabc

{ZZ} abc

独自のasciidocマクロを定義する方法

{set:cellbgcolor:gray}
[grid=none, frame=none]
|===
| X >| Y
|===
{set:cellbgcolor!}

X	Y

{

a #FF0000
Cell data

20. リンク

WebページなののURLへのリンク。<url>[リンク表示]
Windowsファイルパスの場合は、link:<path>[リンク表示]

santanaのCMM

タイトル例
結果	記述
チートシート英語	https://asciidoctor.org/docs/user-manual/[チートシート英語]

21. イメージリンク

通常

image::im.JPG[代替テキスト,x,y,.... align="right/left/center"]

x,yは表示ピクセル数を指定するか
もしくは%を用いて実際の表示幅からの割合表示が可能
image::im.JPG[代替テキスト,"50%"]
また明示的に記載も可能(width,height)
image::im.JPG[代替テキスト,width="50%"]

インライン（行内)
```
		image:im.JPG[代替テキスト]
```

行で　代替テキスト　をいれる

22. テーブル

テーブルの表現 .タイトル例

結果記述

data1

data2

[cols="1a,2a",options="header"]
|===
|c1        |c2
|data1     |data2
|===

その他の細かい記述方法

*まだ*

cols=

番号で列の幅比率
a:adoc書式、l(エル):リテラル書式

テーブル内でテーブルを使う場合(Nested Table)は、|の代わりに!(ビックリマーク)を使う。それでも完全で無い。

寄せの設定

[cols="<,>,^"]

1列目: 左寄せ	2列目: 右寄せ	3列目: 中央寄せ

寄せの設定2

[cols="{左右}.{上下}, {左右}.{上下}, {左右}.{上下}, ..."]
[cols="{左右}.{上下}, {左右}.{上下}, {左右}.{上下}, ..."]

[cols="<.<,"]は 1列目: 左寄せ + 上寄せ	2列目1 2列目2

[cols=">.>,"]は 1列目: 右寄せ + 下寄せ	2列目1 2列目2

[cols="^.^,"]は 1列目: 中央(左右) + 中央寄せ(上下）	2列目1 2列目2

寄せの設定3

行定義|の左側に<,>,^を記述する方法もある。1列ごとに改行して定義する。
※ヘッダ行とデータ行の間に改行が必要
|item
<|item
>|item
<.^|item

列幅の設定

以下の自動幅autowidth:OK,様々指定方法がある。どれか一つ。
[options="header,autowidth"]
[options="autowidth"]
[%autowidth]
[%header%autowidth]
["%autowidth",cols="a,a",options="header"]
※ a,100aはadoc2pdf変換で失敗 1:40で失敗,最大39でいけた

23. テーブルを段組に使う技

「イメージを左、その説明を右」ぐらいの用途。テーブルにテーブルをいれるのが難しいなど、全表現をいれるのに苦労するのでやめたほうがいい。

テーブルを段組みに使う（2分割）

画像タイトル名

テーブルにテーブルを入れている
head a	head b
a	BBBBBB

これが二つ目のブロックになる

ラベル
ラベル

表現は以下のとおり

	[title="ｘｘｘ",caption="",cols="a,a",frame="none",grid="all"]
	|================================
	|
	// 左段落
	[caption="",title="画像タイトル名",grid="all"]
	image::im.JPG[代替テキスト,100,align="center"]

	[caption=""]
	.テーブルにテーブルを入れている
	[cols="1a,2a", options="header"]
	// [frame="none",grid="none"]
	!=========
	!head a	! head b
	!a		! BBBBBB
	!=========

	|
	// 右段落
	--
	.これが二つ目のブロックになる
	. ラベル
	. ラベル
	--
	|================================

24. テキストの折り畳み

[%collapsible]で記述する

.タイトル
[%collapsible]
====
～ ※[%collapsiblee%open]と指定すると初期状態で展開される
====

折り畳みテキスト

折り畳み内容

25. インクルード

include::../../hoge.adoc[]で別のAsciiDocファイル指定する。 []内にオプションを指定できる

include::path[leveloffset=offset,lines=ranges,tag(s)=name(s),indent=depth,opts=optional]

leveloffset= +n: セクション階層を変更する。＋の数値を指定することで、階層を下げる。マージしたadocのセクション階層と、include先のadocも単独で参照するようなケースに有効です

26. アンカー(内部参照)

内部参照へのリンクを表現する。 [[アンカー名 ]]で設定し、<<アンカー名 >>で参照する。設定された直後の章名がアンカー表示名になる。
アンカー参照時の表示名を別名にしたいときは、設定箇所で[[アンカー名,表示名]]とする。
デフォルトで、章は、アンカーが設定されており,<<_章名>>(先頭にアンダーバー)で参照できる。vscodeプレビューは日本語でリンクに飛べなかった？

例.

イメージリンク

27. 属性設定のサンプル

その他

(済)アンカー(内部参照)
色名
本

1. オリジナル先のリンクをしっかりしておこう

トップページ_Asciidoctor Documentation

macro defineがあるんですけどね

Nested Tables

Nested tables

1. Nested tables

To nest a table in a table we must use ! as table separator instead of |. Also the type of the column or cell must be set to a so Asciidoc markup is processed.

Col 1

Col 2

Cell 1.1

Cell 1.2

Cell 2.1

Cell 2.2

Col1

Col2

C11

C12

MyAp²

MyApp²

CPUここが長くなってしまうとどうする	The brain of the computer. a b
Hard drive	Permanent storage for operating system and/or user files.
RAM	Temporarily stores information the CPU uses during operation.

+ .Q and A

アスキードックとは？

ルビーで実装されたドキュメントフォーマットである。
What is the answer to the Ultimate Question?

42 +

It’s possible to use Unicode glyphs as admonition icons. WARNING: It’s possible to use Unicode glyphs as admonition icons.

ruby, asciidocto

\$sqrt(4) = 2\$

\$sqrt(4)\$

latexmath:[C = \alpha + \beta Y^{\gamma} + \epsilon

An open block can be an anonymous container, or it can masquerade as any other block. pass:[dfsa]

An open block can be an anonymous container, or it can masquerade as any other block. dfsa

まとめ

1. タイトル

。。。（。。。）

タイトル例
結果	記述
<左列のレンダリング結果>	<右側列のAsciiDocの記述>

属性関係の設定

脱Word、脱Markdown、asciidocでドキュメント作成する際のアレコレ

HTMLのスタイル(CSS)を設定する

// :stylesdir:   // どこでも有効になる様子
//:stylesdir:でCSSのフォルダを:stylesheet:でCSSファイルを指定可能

// html-style.adoc
// :stylesdir: stylesheets/
// :stylesheet: asciidoctor-default.css

// pdf-style.adoc
// :pdf-style: themes/default-theme.yml

stylesdir=.
stylesheet=
pdf-style={pdf-style}

以下のパスを書き換えた：1.2emに。 1.0が今の表示の様子。 C:\Users\AA004035\.vscode\extensions\joaompinto.asciidoctor-vscode-2.7.6\media\asciidoctor-editor.css

	.literalblock pre,
	.listingblock>.content>pre:not(.highlight),
	.listingblock>.content>pre[class="highlight"],
	.listingblock>.content>pre[class^="highlight "] {
		font-size: 1.2em;	/*　松尾2em;200%でも変更できる*/
		/* background: #f7f7f8 これ消したら消えた*/
	}

1. テストコード

[IMPORTANT]
====
本文の記載
====

単行記述は以下：

IMPORTANT: 本文の記載

結局これが一番わかり易いかも .AsciiDocのチートシート AsciiDocのチートシート

2. テストコードの終わり

付録

1. 属性パラメータ

:Keywords:␣ で内部パラメータ定義。キャンセルは:Keywords!: or :!Keywords:。
その他ビルドインアトリビュートの一覧

記述	説明
:toc: left	left,right,macro(別途 toc::[]で場所指示）
:imagesdir: ./	イメージDIR
:lang: ja	言語指定
:doctype: book	article/book/manpage/inline(不明)
:toc-title: 目次	目次のタイトル
:toclevels: 3	目次の番号レベル
:sectnums:	セクションに番号をつけるか?
:sectnumlevels: 4	セクションの番号レベル
:sectlinks:
:icons: font
:example-caption: 例	例ブロック($$====$$)のキャプション
:table-caption: 表	テーブルブロック($$====$$)のキャプション
:experimental:	*マクロを有効するにる

完全な例
// 属性定義 :experimental: // :module: モジュール名 :Author: 著者名 :Email: メールアドレス :Date: 日付(2020/01/20) :Revision: Rev.1 :lang: ja :doctype: book :description: :docname: ドキュメント名 // 見出し設定 :sectnums: :chapter-label: // 目次作成 :toc: left :toclevels: 3 // ラベルの日本語設定 :toc-title: 目次 :preface-title: はじめに/まえがき :appendix-caption: 付録 :caution-caption: 注意 :example-caption: 例 :figure-caption: 図 :important-caption: 重要 :last-update-label: 最終更新 :listing-caption: リスト :manname-title: 名前 :note-caption: 注記 :table-caption: 表 :tip-caption: ヒント :toc-title: 目次 :untitled-label: 無題 :version-label: バージョン :warning-caption: 警告

完全な例

 // 属性定義
:experimental:
 // :module:    モジュール名
:Author:    著者名
:Email:     メールアドレス
:Date:      日付(2020/01/20)
:Revision:  Rev.1
:lang: ja
:doctype: book
:description:
:docname: ドキュメント名

 // 見出し設定
:sectnums:
:chapter-label:
 // 目次作成
:toc: left
:toclevels: 3
 // ラベルの日本語設定
:toc-title: 目次
:preface-title: はじめに/まえがき
:appendix-caption: 付録
:caution-caption: 注意
:example-caption: 例
:figure-caption: 図
:important-caption: 重要
:last-update-label: 最終更新
:listing-caption: リスト
:manname-title: 名前
:note-caption: 注記
:table-caption: 表
:tip-caption: ヒント
:toc-title: 目次
:untitled-label: 無題
:version-label: バージョン
:warning-caption: 警告

Adoc使用説明書簡易 (Asciidocの表現を試す)

Adoc使用説明書簡易　(Asciidocの表現を試す)