Help us understand the problem. What is going on with this article?

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

More than 1 year has passed since last update.

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例

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事業部 開発1グループ
: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

環境構築(Windows)

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

  1. ruby(2.2以上)をインストール
  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でもプラグインを入れることでレンダリング可能

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

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

  apm install language-asciidoc
  apm install asciidoc-preview

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

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

  1. pandocインストール
  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

TIPS

文字の色を変える(変わらない)

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

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

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

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

目次を使う・設定する

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

= asciidocの使い方

== asciidocとは?

=== asciidoctorとは?

==== asciidoctorのメリット

==== asciidoctorのデメリット

=== asciidoctor-pdfとは?

== asciidoc記法

toc_left.jpg

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

= asciidocの使い方

== asciidocとは?

=== asciidoctorとは?

==== asciidoctorのメリット

==== asciidoctorのデメリット

=== asciidoctor-pdfとは?

== asciidoc記法

toc_sectnum.jpg

  • :toclevels:で表示する階層を指定可能(デフォルト2,最大5)
  • :toclevels: 3にした結果
toclevels.adoc
:toc: left
:sectnums:
:toc-title: 目次
:toclevels: 3

= asciidocの使い方

== asciidocとは?

=== asciidoctorとは?

==== asciidoctorのメリット

==== asciidoctorのデメリット

=== asciidoctor-pdfとは?

== asciidoc記法

image.png

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

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

  • coderayのインストール
gem install coderay
  • adocファイルに定義&記述
source-highlighter.adoc
:source-highlighter: coderay

[source, json]
{
  "hoge" : "fuga",
  "foo" : [1,2,3]
}
  • 対策後
{
  "hoge" : "fuga",
  "foo" : [1,2,3]
}

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

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

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

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

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

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

[[what_is_asciidoctor]]
== asciidoctorとは?

image.png

表のセルを結合する

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

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

表のセル内で箇条書きにする

colsaを付けると、asciidoc形式になるので、箇条書きとかができる。

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

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

. Windows
. Linux
. Mac
|====

image.png

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

表の列幅を自動調整する

optionsautowidthを付けると列幅が自動調整される

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

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

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

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

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

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

  • 表示させない場合(属性env-externalが無い)
    • env-externalは例で、値は何でもよい
invisible.adoc
ifdef::env-external[]
  この文章はお客様用です
endif::[]
  • 表示させる場合(属性env-externalがある)
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だと出ない

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

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

image.png

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

icon-font.adoc
:icons: font

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

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

image.png

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

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

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

= asciidocの使い方
  • HTMLの場合(一番上に表示)

image.png

  • PDFの場合(表紙に表示)

image.png

PlantUMLなどを記述する

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

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

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

class Cat extends Animal {
}

class Dog extends Animal {
}
----

image.png

  • asciidoc-diagramを使っているので、PDF/HTML変換時は指定しないと表示されない
asciidoctor -r asciidoctor-diagram sample.asoc
  • PlantUML以外にもditaagraphvizなどにも対応

例・表・画像に説明文(キャプション)を付ける

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

example-caption.adoc
:example-caption: 例

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

====

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

image.png

table-caption.adoc
:table-caption: 表

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

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

image.png

image-caption.adoc
:figure-caption: 図

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

image.png

ファイルを取り込む

include::を使用することで別ファイルを取り込むことができる
adocファイルが大きくなって分割したい時や、csvやソースなど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するフォルダをまとめて指定することも可能

lines.adoc
:includedir: _includes

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

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

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

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:で設定ファイルの指定が可能

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のスタイル設定のフッタに記述することで対応可能

test.adoc
:pdf-style: themes/default-theme.yml
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

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

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

  • スペースがおかしい例

image.png

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

gem install asciidoctor-pdf-cjk

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

asciidoctor-pdf -r asciidoctor-pdf-cjk test.asc
  • 適用後の例

image.png

テキスト折り畳みをする

長いテキストで折り畳みをしたいときは%collapsibleを使う
※asciidoctorのバージョンが2.0.0以上

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

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

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

collapse.gif

asciidoctor-pdfの課題

文字の色が変えられない

asiciidoctor-pdfのバグ?

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

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

  • HTML(※や①が出る)

image.png

  • PDF(※や①が出ない)

image.png

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

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

  • IPAフォントをダウンロード(ここではPゴシックをダウンロード)
  • ダウンロードしたzip内にあるipagp.ttfファイルをpdf-fontsdirで指定されているフォルダに置く
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を以下のように書き換える
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

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

参考資料

jrits
信頼と魅力のある先進のITをもとに、お客様のワークスタイル・イノベーションの実現を目指します。
http://www.jrits.co.jp/
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Comments
No comments
Sign up for free and join this conversation.
If you already have a Qiita account
Why do not you register as a user and use Qiita more conveniently?
You need to log in to use this function. Qiita can be used more conveniently after logging in.
You seem to be reading articles frequently this month. Qiita can be used more conveniently after logging in.
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
ユーザーは見つかりませんでした