asciidoctor
asciidoctor-pdf

エクセルやパワーポイントのドキュメントを捨てて、超美麗なドキュメント作成をasciidoctorで実現しよう!

More than 3 years have passed since last update.


エクセルやパワーポイントのドキュメントを捨てて、超美麗なドキュメント作成をasciidoctorで実現しよう!

開発には付き物のドキュメント作成、現場ではワードやエクセル、パワーポイントを使うことが普通ですよね?

そんなドキュメント作成に革命を起こしそうなのがasciidoctorです。

Office製文書の悪い問題を簡単に解決してくれます。


Officeで技術文書を作成する時の問題点


  1. 成果物がバイナリなので Git などのバージョン管理ツールと相性が悪い

  2. 内容以外の修飾に掛かる時間が膨大すぎる、ワード以外では目次の作成、章番号の連番付け、印刷結果との違いの確認など 文章の内容を記述する時間より、体裁を整えるのに時間が掛かる

  3. Windows以外ではなかなか編集できない

  4. コードのハイライトなどできない

  5. コピーペーストがままならず同じパワポ同士でもテンプレート元が違うと体裁が崩れてしまう
    などなど、問題山盛り手間がかかりすぎです。
    ## もっと手軽にバージョン管理ができて、 体裁も綺麗な ドキュメントを 簡単に 作りたい!!


asciidoctorがめちゃめちゃお勧めです!

asciidoctorは、AsciiDocというMarkdownとかと同じようにテキストフォーマットで書いてHTMLやPDFに変換できるRuby製のツール群です。


メリット


  1. 変換元がテキストファイルであるため、バージョン管理ツール GIT との相性がよい

  2. include機構があるため、共通化しやすくメンテナンス性が良い

  3. 目次な章番号など自動で割り振りするためメンテナンス性が良い

  4. ソースコードをハイライトする機能や行番号の付与など自動で行ってくれる

  5. 図やテーブルもテキストで記述可能である


  6. マークアップで出力されるフォーマットが決まるため、書式の統一化を行いやすい


    デメリット



  7. 変換処理が必要であるため、変換機構を自動化する仕組みがないと不便


  8. 図が直感的にイメージしづらい場合がある


  9. フォーマットがある程度固定であり、自在に編集可能というわけではない



導入は超簡単!

続きはasciidocでGistに記述しています。

Github:asciidoctor-pdf-live-reload-seed

参考:自分のブログの記事です。