Markdown使っていて、不満に思うこと
まだドキュメント作成にWord Excel 使ってるの
Markdown使っていて、不満に思うこと
文章を書く時、Markdownを使っている方は多いと思います。
私もあらゆるメモはMarkdown形式で記載することが多いのですが、さて、納品用ドキュメントを作成する際に困ることがあります。
* ヘッダー・フッターに共通の要素を入れたい
（ページ番号、copyright、ロゴ画像など）
* 改ページを任意の場所に入れたい
* 目次を自動生成したい
提出先によっては、書式を整えて提出したくなる場合があり、その際にMarkdownだといささか心もとないですね。
asciidocが良いみたい
プロジェクト内でドキュメントを作成する時は、複数の人間が同じ書類に変更を加えたり、レビューをしたりするので、当然テキストベースのマークアップ言語で記述して、Gitで管理するのが良いわけです。しかし、最後にWordにコピペする作業も、ドキュメント種が多くなると大変ですし、無駄な作業の感じがして辛いです。
でも、最初からWordで作ると、変更管理機能はあるものの、ファイル共有、レビュー、修正などにGitのメリットが活かせずスピード感が出ません。そんな時は、asciidocを使うことが多いです。記載もMarkdown同様に直感的ですし、ちょっとルールを覚える必要はありますが、前述の不満も解消できています。ドキュメント形式としては、HTMLまたはPDFにして収めることになります。（納品ファイル形式が定められている場合は、、素直に諦めます）
asciidocを使ってみよう
環境準備、記法などは、だいたい検索すれば出てくるので、ここでは割愛します。 個人的にいいなと思ったところを紹介しますね。 （わたしの環境は、macにasciidoctor/asciidoctor-pdf をインストールして使っています）
アイコンが簡単かわいい
文章の前に文字を記載するだけで、かわいいアイコンが出てきます
NOTE: こんな情報アイコンが出てきます 。
WARNING: 警告を書くこともできます
目次が作成できる
asciidocは、文章の構造から自動的に目次を生成してくれます。
以下のコードを、文章の頭に埋めるだけ。 * sectnums 番号を振る * toclevels サブタイトルの2階層目までを目次に採用する * toc-title 目次の名称を指定（デフォルトが英語のため）
:toc:
:sectnums:
:toclevels: 2
:toc-title: 目次
この文章のここまでの見出しを例にすると、以下のように生成されます
改ページを入れられる
改ページを入れるのも簡単です。
以下のように記載するだけで、文章1と文章2の間に改ページがを入れることができます
文章1
<<<
文章2
もっと使いたおそう
こちらの記事では紹介しませんでしたが、asciidoctorでは、テーマをカスタマイズすることで 出力するPDFのレイアウト、フォント、文字サイズなどが指定できます。
もっと色々試して、実用的なものを紹介できればと思います。
