データサイエンス

Markdown使っていて、不満に思うこと

まだドキュメント作成にWord Excel 使ってるの

Markdown使っていて、不満に思うこと

文章を書く時、Markdownを使っている方は多いと思います。
私もあらゆるメモはMarkdown形式で記載することが多いのですが、さて、納品用ドキュメントを作成する際に困ることがあります。
* ヘッダー・フッターに共通の要素を入れたい
(ページ番号、copyright、ロゴ画像など)
* 改ページを任意の場所に入れたい
* 目次を自動生成したい

提出先によっては、書式を整えて提出したくなる場合があり、その際にMarkdownだといささか心もとないですね。

asciidocが良いみたい

プロジェクト内でドキュメントを作成する時は、複数の人間が同じ書類に変更を加えたり、レビューをしたりするので、当然テキストベースのマークアップ言語で記述して、Gitで管理するのが良いわけです。しかし、最後にWordにコピペする作業も、ドキュメント種が多くなると大変ですし、無駄な作業の感じがして辛いです。

でも、最初からWordで作ると、変更管理機能はあるものの、ファイル共有、レビュー、修正などにGitのメリットが活かせずスピード感が出ません。そんな時は、asciidocを使うことが多いです。記載もMarkdown同様に直感的ですし、ちょっとルールを覚える必要はありますが、前述の不満も解消できています。ドキュメント形式としては、HTMLまたはPDFにして収めることになります。(納品ファイル形式が定められている場合は、、素直に諦めます)

asciidocを使ってみよう

環境準備、記法などは、だいたい検索すれば出てくるので、ここでは割愛します。
個人的にいいなと思ったところを紹介しますね。
(わたしの環境は、macにasciidoctor/asciidoctor-pdf をインストールして使っています)

アイコンが簡単かわいい

文章の前に文字を記載するだけで、かわいいアイコンが出てきます

    NOTE: こんな情報アイコンが出てきます 。

f:id:gri-blog:20200110121201p:plain

    WARNING: 警告を書くこともできます

f:id:gri-blog:20200110121219p:plain

目次が作成できる

asciidocは、文章の構造から自動的に目次を生成してくれます。

以下のコードを、文章の頭に埋めるだけ。
* sectnums 番号を振る
* toclevels サブタイトルの2階層目までを目次に採用する
* toc-title 目次の名称を指定(デフォルトが英語のため)

    :toc:
:sectnums:
:toclevels: 2
:toc-title: 目次

この文章のここまでの見出しを例にすると、以下のように生成されます

f:id:gri-blog:20200110121246p:plain

改ページを入れられる

改ページを入れるのも簡単です。

以下のように記載するだけで、文章1と文章2の間に改ページがを入れることができます

    文章1
<<<
文章2

もっと使いたおそう

こちらの記事では紹介しませんでしたが、asciidoctorでは、テーマをカスタマイズすることで
出力するPDFのレイアウト、フォント、文字サイズなどが指定できます。

もっと色々試して、実用的なものを紹介できればと思います。