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


# asciidocとは

* asciidocはMarkdownなどのような軽量マークアップ言語の一つで、Webページなどをプレーンテキストで記述することができる(拡張子は.adoc)

# asciidocを使うようになった経緯

* これまではWordで機能仕様書とか書いていたが、Wordは重い、変更場所が分からない、複数人同時に修正とか面倒で、いい加減Wordを使うのは止めたくなった
* なので軽量マークアップ言語にしよう、一番メジャー？なMarkdownにしたら、以下の制約とかでいくらなんでもイマイチ。。
  * 表でセルの結合ができない
  * 表のセル内で箇条書きができない
  * 目次が作れない
  * 文字に色がつけられない
  * 上記に対応しようとすると、プラグインやらMarkdown亜種がいろいろ。。
* そこで、Markdownより表現方法が豊富なasciidocを使用し、実際に使って、特徴・課題を挙げてみた。

# asciidoctor, asciidoctor-pdfとは

* asciidoctor・・・asciidocファイルをHTMLファイルに変換するruby製ツール
* asciidoctor-pdf・・・asciidocファイルをPDFファイルに変換するruby製ツール

# asciidoctorで作成したHTML例

```adoc:sample.adoc
:lang: ja
:doctype: book
:toc: left
:toclevels: 3
:toc-title: 目次
:sectnums:
:sectnumlevels: 4
:sectlinks:
:imagesdir: ./_images
:icons: font
:source-highlighter: coderay
:example-caption: 例
:table-caption: 表
:figure-caption: 図
:docname: = asciidocの使い方
:author: asciidoc事業部 開発１グループ
:revnumber: 0.1
:revdate: 2017/10/25

= asciidocの使い方

== asciidocとは？

asciidocとは [blue]#軽量マークアップ言語# です

詳しくは<<can_asciidoc,asciidocでできること>>を参照

[[can_asciidoc]]
== asciidocでできること

.コードハイライト
[source, json]
{
  "hoge" : "fuga",
  "foo" : [1,2,3]
}

.結合＋箇条書例
[cols="1,2a,3a"]
|====
|列1|列2|列3
3+|3列結合
.2+|2行縦結合|b-1|c-2
|b-2|
* c-3
* c-4
|====

[NOTE]
====
* format="csv"ではできません
====

=== asciidoctorだとPlantUMLでシーケンス図作成

[plantuml]
----
actor ユーザー as user
user -> ログイン : ログインする
ログイン --> user:
----
```

![image.png](https://qiita-image-store.s3.amazonaws.com/0/10862/9ecdd249-b71a-c011-3b40-f94db172e323.png)


# 環境構築(Windows)

## asciidoctor, asciidoctor-pdfのインストール

1. ruby(2.2以上)をインストール
  * https://rubyinstaller.org/downloads/
2. コマンドプロンプトで以下を実行

```
gem install asciidoctor             # asciidoctorのインストール
gem install --pre asciidoctor-pdf   # asciidoctor-pdfのインストール
gem install coderay                 # コードのシンタックスハイライト用
gem install asciidoctor-pdf-cjk     # PDF変換のレイアウト崩れ対応
gem install asciidoctor-diagram     # PlantUMLなどの図を使用
```

## asciidocファイルをHTML, PDF変換

* HTMLファイル変換

```
asciidoctor test.adoc
=> test.htmlが作成される
```

* PDFファイル変換

```
asciidoctor-pdf test.adoc
=> test.pdfが作成される
```

* 複数ファイルまとめて変換

```
asciidoctor *.adoc
asciidoctor-pdf *.adoc
```


* asciidoctor-pdf-cjk や asciidoctor-diagramを使う場合(-rをつける)

```
asciidoctor     -r asciidoctor-pdf-cjk -r asciidoctor-diagram test.adoc
asciidoctor-pdf -r asciidoctor-pdf-cjk -r asciidoctor-diagram test.adoc
```   

## asciidocファイルをブラウザで表示

Firefoxとかchromeでもプラグインを入れることでレンダリング可能

* Firefox plugin
  * https://addons.mozilla.org/ja/firefox/addon/asciidoctorjs-live-preview/
* chrome plugin
  * https://chrome.google.com/webstore/detail/asciidoctorjs-live-previe/iaalpfgpbocpdfblpnhhgllgbdbchmia

## asciidocファイルをプレビューできるエディタ

以下のエディタを使用すると、リアルタイムでプレビューできるので便利

* Asciidoc FX
  * http://asciidocfx.com/
* Atom
  * https://atom.io/
  * インストール後にプラグインを入れることで、プレビュー(`Ctrl + Shfit + A`)が可能

  ```
  apm install language-asciidoc
  apm install asciidoc-preview
  ```

## Word(docx)をasciidocファイルに変換する

`pandoc`というツールを使うと変換できる
そこそこいい感じに変換してくれる

1. pandocインストール
  * リンク先にWindowsのインストーラダウンロードページがある
  * http://pandoc.org/installing.html
2. コマンドプロンプトで実行

```
pandoc --from=docx --to=asciidoc --wrap=none --atx-headers --normalize --extract-media=extracted-media input.docx > output.adoc
```

## PlantUMLなどの図を表示するための環境構築

PlantUMLなどの図を記述するにはasciidoctor-diagramが必要だが、
それ以外にもJava + Graphvizのインストールが必要（`gem install Graphviz`ではダメだった）

* asciidoctor-diagramのインストール

```
gem install asciidoctor-diagram
```

* Javaのインストール
* Graphvizのインストール 
  * https://graphviz.gitlab.io/_pages/Download/Download_windows.html

# TIPS

## 文字の色を変える（変わらない）
色を変える場合、`[color]#文字#`とかになるが、#が１つの場合は前後にスペースが無いと色が変わらない
スペースが無い場合は**##を2つ入れないといけない**

```adoc:color.adoc
// 前後にスペースがあるので#１つでOK
asciidocとは [blue]#軽量マークアップ言語# です

// 前後にスペースが無いので#１つだと色は変わらない
asciidocとは[blue]#軽量マークアップ言語#です

// 前後にスペースが無い場合、##だとOK
asciidocとは[blue]##軽量マークアップ言語##です

```

* HTML
![color_html.jpg](https://qiita-image-store.s3.amazonaws.com/0/10862/6e94c16b-55f8-10e8-7030-2cb99f783856.jpeg)

* PDF
![color_pdf.jpg](https://qiita-image-store.s3.amazonaws.com/0/10862/5d901954-b799-f4e8-d3cd-8923002a370c.jpeg)

* PDFはasciidoctor-pdfのバグなのか変わらない。。。
  * http://gozuk16.hatenablog.com/entry/2016/08/01/180402


## 目次を使う・設定する

* `:toc:`で目次を使用することが可能(HTML/PDF)
  * `top`, `left`, `right`等で表示する箇所の指定も可能（個人的には常に表示される`left(right)`がオススメ）
* `:toc: left`を付けた結果

```adoc:toc.adoc
:toc: left

= asciidocの使い方

== asciidocとは？

=== asciidoctorとは？

==== asciidoctorのメリット

==== asciidoctorのデメリット

=== asciidoctor-pdfとは？

== asciidoc記法
```
![toc_left.jpg](https://qiita-image-store.s3.amazonaws.com/0/10862/66338990-a600-6827-19fb-127f6e9cdd36.jpeg)


* `:sectnums:`を付けると、セクションが自動的にナンバリングされるのでつけたほうが良い
  * PDF変換だと「Chapter」という文字が勝手に入るので、HTMLとセクション名を合わせる場合は`:chapter-label:`を入れると消える
* 目次名はデフォルトで「Table of Contents」なので、`:toc-title:`で「目次」とか指定したほうが良い
* `:sectnums:`と`:toc-title: 目次`を追加した結果

```adoc:sectnums.adoc 
:toc: left
:sectnums:
:toc-title: 目次
:chapter-label:

= asciidocの使い方

== asciidocとは？

=== asciidoctorとは？

==== asciidoctorのメリット

==== asciidoctorのデメリット

=== asciidoctor-pdfとは？

== asciidoc記法
```
![toc_sectnum.jpg](https://qiita-image-store.s3.amazonaws.com/0/10862/b2b5d053-871f-074b-4df6-9981d7968f5f.jpeg)

* `:toclevels:`で表示する階層を指定可能（デフォルト2,最大5）
* `:toclevels: 3`にした結果

```:toclevels.adoc
:toc: left
:sectnums:
:toc-title: 目次
:toclevels: 3

= asciidocの使い方

== asciidocとは？

=== asciidoctorとは？

==== asciidoctorのメリット

==== asciidoctorのデメリット

=== asciidoctor-pdfとは？

== asciidoc記法
```
![image.png](https://qiita-image-store.s3.amazonaws.com/0/10862/f69f4efd-825d-00d7-7afc-e7d0350000bb.png)


## コードをシンタックスハイライトする

例えば、jsonをシンタックスハイライトしたい場合
単純に`[source, json]`と記述してもハイライトしてくれない
「coderay」などのライブラリ＆定義が必要

* coderayのインストール

```
gem install coderay
```

* adocファイルに定義＆記述

```adoc:source-highlighter.adoc
:source-highlighter: coderay

[source, json]
{
  "hoge" : "fuga",
  "foo" : [1,2,3]
}
```

* 対策後

```json
{
  "hoge" : "fuga",
  "foo" : [1,2,3]
}
```


## 自動でセクションにアンカーを付ける

目次には自動的にアンカーが付くが、本文には付かないので、`:sectlinks:`をつけることで自動的にアンカーが付与される。

## 内部のセクションをリンクする

`[[<アンカー名>]]`という形でアンカー名を指定することが可能。
そのアンカーにリンクを貼るには`<<<アンカー名>,<リンク名>>>`で指定可能

```adoc:internal_link.adoc
asciidoctorは、asciidocファイルをHTMLファイルに変換するruby製ツールです。

詳しくは<<what_is_asciidoctor,asciidoctorとは？>>を参照

[[what_is_asciidoctor]]
== asciidoctorとは？
```

![image.png](https://qiita-image-store.s3.amazonaws.com/0/10862/aaea9266-3315-33ec-e1cf-bee7a376d1b0.png)


## 表のセルを結合する

数値のあとに`+`を入れると結合になる。数値の前に`.`があれば縦方向への結合で、なければ横方向の結合となる。

```adoc:cellspan.adoc
|====
|列1|列2|列3
3+|3列結合
.2+|2行縦結合|b-1|c-2
|b-2|c-2
.2+|2行縦+2列結合の組み合わせ 2+|b-3
|b-4|c-4
|====
```

![image.png](https://qiita-image-store.s3.amazonaws.com/0/10862/4d50fd66-0443-959e-24a5-61ac378853e4.png)


## 表のセル内で箇条書きにする
 `cols`に`a`を付けると、asciidoc形式になるので、箇条書きとかができる。

```adoc:list.adoc
[cols="1,5a"]
|====
|No|項目
|1|対応ブラウザ

* Firefox
* Chrome
* edge
|2| 対応OS

. Windows
. Linux
. Mac
|====
```

![image.png](https://qiita-image-store.s3.amazonaws.com/0/10862/f893f431-e2e4-c86d-ba5c-f5e0ab925446.png)


補足：`format="csv"`ではできない模様

## 表の列幅を自動調整する
 `options`に`autowidth`を付けると列幅が自動調整される

```adoc:autowidth.adoc
.autowidthあり
[options="autowidth"]
|====
|No|OS
|1|Windows
|2|Linux
|====

.列幅指定なし
|====
|No|OS
|1|Windows
|2|Linux
|====

.列幅を比率で指定
[cols="1,5"]
|====
|No|OS
|1|Windows
|2|Linux
|====
```

![image.png](https://qiita-image-store.s3.amazonaws.com/0/10862/607a7c97-cf64-6625-e541-53ede8b97876.png)

## 属性を定数のように指定する

asciidocではたくさんの設定済みの属性(attribute)があり、それとは別に属性を設定することができる。
属性は、`:属性名:`で宣言し、`{属性名}`で参照することができる。
例えば、他のリンク先など定数的に使いたい場合に、独自に設定すると便利。

```adoc:attribute.adoc
// 他チームのアプリ名
:other-app-name: ほげツール
// 他チームのAPI仕様書
:other-app-api-doc-path: ../../other_app/api/index.html

{other-app-name}のlink:{other-app-api-doc-path}[API仕様書]
```

![image.png](https://qiita-image-store.s3.amazonaws.com/0/10862/eea4dfc6-4091-e297-04c8-aecfe409f773.png)

## 条件によって表示・非表示にする

`ifdef ～ endif`を使うことで可能
これにより、チーム用・お客様提出用という感じに分けることが可能

* 表示させない場合(属性`env-external`が無い)
 * `env-external`は例で、値は何でもよい

```adoc:invisible.adoc
ifdef::env-external[]
  この文章はお客様用です
endif::[]
```

* 表示させる場合(属性`env-external`がある)

```adoc:visible.adoc
:env-external:

ifdef::env-external[]
  この文章はお客様用です
endif::[]
```

## コマンドラインで属性を渡す

先ほどの`env-external`ように、adoc内に記述せず、条件によって値を変えたい場合、コマンドラインで属性を渡すことも可能

```
asciidoctor -a env-external test.adoc
```

属性名だけでなく、値を渡したい場合、`属性名=値`で指定する
既にadocファイルに同一の属性が記述されている場合、コマンドラインで渡した値が優先される

```
asciidoctor -a toc-title=mokuji test.adoc
```


## 脚注のアイコンを出す

adocファイル上だとアイコンが出るのに、HTML/PDFだと出ない

```adoc:icon.adoc
[NOTE]
====
* デフォルトでは[NOTE]が出ません
====

[CAUTION]
====
* デフォルトでは[CAUTION]が出ません
====
```

![image.png](https://qiita-image-store.s3.amazonaws.com/0/10862/7c33b707-6923-def4-40e4-3ca01eaaf2b5.png)

`:icons: font`を記述すると表示される

```adoc:icon-font.adoc

:icons: font

[NOTE]
====
* デフォルトでは[NOTE]が出ません
====

[CAUTION]
====
* デフォルトでは[CAUTION]が出ません
====
```

![image.png](https://qiita-image-store.s3.amazonaws.com/0/10862/eabc4eb8-2d14-77e1-de68-254f35da7e83.png)


## バージョン、最終更新日などを表示する

`:author:`, `:revnumber:`, `:revdate:`を定義する。

```adoc:revnumber.adoc
:author: asciidoc事業部 開発１グループ
:revnumber: 0.1
:revdate: 2017/10/25

= asciidocの使い方
```

* HTMLの場合（一番上に表示）

![image.png](https://qiita-image-store.s3.amazonaws.com/0/10862/3414eaed-66fe-056d-5a99-5a4bcc84962e.png)


* PDFの場合（表紙に表示）

![image.png](https://qiita-image-store.s3.amazonaws.com/0/10862/41e0dd66-bb0b-1e75-9ffd-888a18c49843.png)


## PlantUMLなどを記述する

PlantUML(テキストでUMLを記述できるツール）を埋め込むことが可能

```adoc:plantuml.adoc
.シーケンス図
[plantuml]
----
actor ユーザー as user
user -> ログイン : ログインする
ログイン --> user:
----

.クラス図
[plantuml]
----
class Animal {
  int age
  run()
}

class Cat extends Animal {
}

class Dog extends Animal {
}
----
```

![image.png](https://qiita-image-store.s3.amazonaws.com/0/10862/a6f50c7a-4fac-ad28-fd2b-83c82fe45636.png)

* `asciidoc-diagram`を使っているので、PDF/HTML変換時は指定しないと表示されない

```
asciidoctor -r asciidoctor-diagram sample.asoc
```

* PlantUML以外にも`ditaa`、`graphviz`などにも対応

## 例・表・画像に説明文（キャプション）を付ける

example, table, imageなどにはその上に`.<文字>`をつけることで、説明文をつけることができる（ナンバリングもされる）
`:example-caption:`、`:table-caption:`で、`:figure-caption:`、プレフィックスも指定可能

```adoc:example-caption.adoc
:example-caption: 例

.参考
====
asciidocの例です

====

.参考
====
asciidocの例です２
====
```

![image.png](https://qiita-image-store.s3.amazonaws.com/0/10862/6da8f2f5-ee5f-ded7-2bdb-dd752699c78d.png)


```adoc:table-caption.adoc
:table-caption: 表

.OS一覧
|======
|No|OS
|1|Windows
|2|Linux
|======

.OS一覧
|======
|No|OS
|1|Android
|2|iOS
|======
```

![image.png](https://qiita-image-store.s3.amazonaws.com/0/10862/04842ea1-b0cd-6da7-4c90-c4af82311848.png)


```adoc:image-caption.adoc

:figure-caption: 図

.脚注(NOTE)
image::icon_note.jpg[]
```

![image.png](https://qiita-image-store.s3.amazonaws.com/0/10862/33ccbfb2-45de-a342-0ad4-6821a0c1f3c5.png)

## ファイルを取り込む

`include::`を使用することで別ファイルを取り込むことができる
adocファイルが大きくなって分割したい時や、csvやソースなどadocとは別ファイルを管理したい時に便利

```adoc:include.adoc
// adocファイルの取込み
include::other.adoc

// csvをテーブルに取込み
[format="csv"]
|===
include::_includes/other.csv[]
|===

// ソースコードを取込み
[source,ruby]
----
include::_includes/other.rb[]
----

// PlantUMLを取込み
[plantuml]
----
include::_includes/sequence.puml[]
----

```

`lindes`でincludeする範囲を指定したり、`:includedir:`でincludeするフォルダをまとめて指定することも可能

```adoc:lines.adoc
:includedir: _includes

// _includes/other.csvの1～3行目を表示
[format="csv"]
|===
include::{includedir}/other.csv[lines=1..3]
|===

```

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

`:stylesdir:`でCSSのフォルダを`:stylesheet:`でCSSファイルを指定可能

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

何も指定していないとき、Windowsの場合は以下に入っているので、cssファイルをコピーして編集すると良い

```
# ruby2.4で、ascidoctorのバージョンが1.5.6.1の場合
C:\Ruby24\lib\ruby\gems\2.4.0\gems\asciidoctor-1.5.6.1\data\stylesheets\asciidoctor-default.css
```

## PDFのスタイルを設定する

PDFのスタイルは設定ファイル(yaml)として定義する
`:pdf-style:`で設定ファイルの指定が可能

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

何も指定していないとき、Windowsの場合は以下に入っているので、yamlファイルをコピーして編集すると良い

```
# ruby2.4で、ascidoctor-pdfのバージョンが1.5.0.alpha16の場合
C:\Ruby24\lib\ruby\gems\2.4.0\gems\asciidoctor-pdf-1.5.0.alpha.16\data\themes\default-theme.yml
```


## PDFのフッタに「Copyright」を入れる

企業のドキュメントなどは「Copyright」表記を入れることが多いので、
pdfのスタイル設定のフッタに記述することで対応可能

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

```yaml:default-theme.yml
footer:
  font_size: $base_font_size_small
  border_color: dddddd
  border_width: 0.25
  height: $base_line_height_length * 2.5
  line_height: 1
  padding: [$base_line_height_length / 2, 1, 0, 1]
  vertical_align: top
  recto:
    right:
      content: '{page-number} / {page-count}'
    center:
      content: Copyright (C) adoc company CO.,LTD. All right reserved.
  verso:
    right:
      content: '{page-number} / {page-count}'
    center:
      content: Copyright (C) adoc company CO.,LTD. All right reserved.
```

![image.png](https://qiita-image-store.s3.amazonaws.com/0/10862/943743da-f9f2-93eb-97a7-e3b6df5e42aa.png)

## 半角・全角が混じるとスペースがおかしくなる(asciidoctor-pdf)

半角・全角が混じるとスペースがおかしくなる。

* スペースがおかしい例

![image.png](https://qiita-image-store.s3.amazonaws.com/0/10862/d4f88d69-1bf5-fcb1-ea7c-862c364653af.png)

対策としては、「asciidoctor-pdf-cjk」を入れると大体解消

```
gem install asciidoctor-pdf-cjk
```

さらに、PDF変換のときに「-r asciidoctor-pdf-cjk」指定しないといけない

```
asciidoctor-pdf -r asciidoctor-pdf-cjk test.asc
```

* 適用後の例

![image.png](https://qiita-image-store.s3.amazonaws.com/0/10862/87c14b83-8bc0-d0a2-b63d-8ec81ff2b9e0.png)

## テキスト折り畳みをする

長いテキストで折り畳みをしたいときは`%collapsible`を使う
<font color="red">※asciidoctorのバージョンが2.0.0以上</font>

```adoc:collapsible.adoc
.テキスト折り畳みのタイトル
[%collapsible] 
====
* ここに内容を書く1
* ここに内容を書く2

.表も書ける
[options="autowidth"]
|====
|列1|列2|列3
|a|b|c
|====

.コードハイライトも書ける
[source, json]
{
  "hoge" : "fuga",
  "foo" : [1,2,3]
}
====
```

![collapse.gif](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/10862/274c2682-5e7a-3af6-3fcd-7992a383fe2e.gif)

# asciidoctor-pdfの課題

## 文字の色が変えられない

asiciidoctor-pdfのバグ？

## 「※」や「①」が表示されない

デフォルトフォントに「※」や「①」が入っていない。
fontsフォルダに「※」や「①」が入ったフォントファイルを入れればＯＫ

* HTML(※や①が出る）

![image.png](https://qiita-image-store.s3.amazonaws.com/0/10862/3309b11b-69c3-3d3a-3633-c02ed01bfe50.png)


* PDF(※や①が出ない）

![image.png](https://qiita-image-store.s3.amazonaws.com/0/10862/36c99004-57a4-8a35-dcbf-882b35a85b90.png)


対策としては、「※」や「①」が入ったフォントを使用する。

以下はIPAフォントを使用する場合の手順

* [IPAフォント](https://ipafont.ipa.go.jp/old/ipafont/download.html)をダウンロード(ここではPゴシックをダウンロード)
* ダウンロードしたzip内にある`ipagp.ttf`ファイルを`pdf-fontsdir`で指定されているフォルダに置く

```adoc:pdf-font.adoc
// PDF変換時のフォント指定
// 指定しない場合、デフォルトでは↓が適用される（ruby2.4 + 64bitWindowsOS)
// C:\Ruby24-x64\lib\ruby\gems\2.4.0\gems\asciidoctor-pdf-1.5.0.alpha.16\data\fonts
:pdf-fontsdir: ./_pdf_fonts

// PDF変換時のスタイル指定
// 指定しない場合、デフォルトでは↓が適用される（ruby2.4 + 64bitWindowsOS)
// C:\Ruby24-x64\lib\ruby\gems\2.4.0\gems\asciidoctor-pdf-1.5.0.alpha.16\data\themes\default-theme.yml
:pdf-style: ./_pdf_themes/default-theme.yml
```
* `:pdf-style:`で指定したymlを以下のように書き換える

```yaml:default-theme.yml
font:
  catalog:
    IPA PGothic:           # 追加箇所
      normal: ipagp.ttf    # 追加箇所
      bold: ipagp.ttf      # 追加箇所
      italic: ipagp.ttf    # 追加箇所
      bold_italic: ipagp.ttf # 追加箇所
base:
  font_family: IPA PGothic # 変更箇所
```

* IPAフォントで作成したPDF(※や①が出る）

![image.png](https://qiita-image-store.s3.amazonaws.com/0/10862/912b1df6-b26a-9d4a-8779-0ffc2b4d8688.png)

## インターレースのpngは表示されない


# 参考資料

- [Asciidoctor クリックリファレンス（日本語）](https://takumon.github.io/asciidoc-syntax-quick-reference-japanese-translation/)
- [Asciidoctor User Manual](http://asciidoctor.org/docs/user-manual/)
- [Asciidoctor pdf](https://github.com/asciidoctor/asciidoctor-pdf)