AsciiDocを使った設計書の作成

はじめに

設計書を作成するときにWordやExcelなどのOffice系ソフトが使われることが多いです。 ただ、上記のようなソフトでは、以下のデメリットがあります。

• 差分の管理が難しい
• マージがしにくい
• 見た目の設定と中身の設定ができるため、文章の作成に集中できない
• スタイルを統一が難しい

そこで、上記の課題を解決するAsciiDocを使った設計書の作成方法について記載します。

AsciiDocとは

AsciiDocとは、主に技術文書の作成のために設計された軽量なマークアップ言語です。 AsciiDocでよく使う記法を紹介します。

タイトルとセクションタイトル

タイトルとセクションタイトルは、以下のように記載します。 Markdownは、「#」ですが、AsciiDocでは、「=」を使用します。 セクションタイトルは、レベル1から5まであります。

= ドキュメントタイトル

== レベル1 セクションタイトル

=== レベル2 セクションタイトル

==== レベル3 セクションタイトル

===== レベル4 セクションタイトル

====== レベル5 セクションタイトル

リンク

リンクは以下のように書きます。

https://google.com[Google]

箇条書き

箇条書きは、Markdownと同じで、「-」や「*」で表現することができます。

- 箇条書き1
- 箇条書き2
- 箇条書き3

表

表は、以下のように書きます。 1行目をヘッダーにする場合は、optionsにheaderを指定します。 また、表のタイトルは、

.table-title
[options="header", cols="1,1"]
|===

|header1 | header2

| item(1, 1)
| item(1, 2)

| item(2, 1)
| item(2, 2)

|===

AsciiDocからPDFの作成

AsciiDocをPDFに変換するには、Asciidoctor-PDFを使用します。

以下のコマンドでインストールできます。

gem install asciidoctor-pdf

PDFへ変換する場合は、以下のコマンドを実行します。

asciidoctor-pdf filename.adoc

実行結果として、filename.pdfが作成されます。

まとめ

マークアップ言語のAsciiDocとAsciiDocをPDFに変換するAsciidoctor-PDFを紹介しました。 ぜひ、使ってみてはいかがでしょうか！