AsciiDocっていいよね

2023-02-25

VSCode

はじめに

AsciiDocというのがあるようなので試していきます。

Markdownで委託成果物に混ぜ込むドキュメントを書いてたのですが、 Wordだと面倒だし、Markdownだと見栄えが味気ないしで代替品を探してました。

そんな時に、パイセンからちょっと試しといてと言われ、かなり気にいったので手順を残しときます。ありがとうパイセン。

AsciiDoc

軽量型マークアップ言語の1つです。その他のマークアップ言語としては、MarkdownやSphinx、LaTexなどがあります。

特徴としては、表の記載が優れていること、テンプレートそのままで書籍向けPDFなどにも対応できること。注釈などの記載にも対応していることなど、ドキュメント製作においてはMarkdownに比べ機能が充実しています。

人によっては技術書の執筆にも使っているんじゃないでしょうか。しらんけど。

農林水産技術会議事務局筑波産学連携支援センター

導入には、この資料がわかりやすいのでこの資料をもとに導入していきます。

環境の導入

Ruby

Rubyをインストールして、Asciidocをインストールする。

gem install asciidoctor
gem install asciidoctor-diagram
gem install --pre asciidoctor-pdf
gem install asciidoctor-pdf-cjk
gem install coderay

VSCodeでの執筆

VSCodeにAsciiDocというEXTENSIONを追加します。

AsciiDoc

追加してVSCodeを再起動後、いくつか設定します。

日本語のPDF出力するためは設定が必要なのでやっていきましょう。

Asciidoc: Asciidoctorpdf_command

asciidoctor-pdf -a pdf-theme=default-with-font-fallbacks -a scripts=cjk

Javascript版がデフォルトで使用されるため、Ruby版に切り替えます。 PDF出力にはasciidoctorpdfを使用するため有効に。 PlantUML以外にも使える図表を増やすため、Krokiを使用します。

Asciidoc: Use_asciidoctor_js : false
Asciidoc: Use_asciidoctorpdf : true
Asciidoc: Use_kroki : true

【12/24にGitLab対応!】テキストで自在に「描く」- KrokiではじめるDiagram as Code

KrokiについてはQiitaの記事で概要がわかるものがあったのではリンクしておきます。

VSCode側の設定はひとまずこれで完了です。

試し書き

AsciiDoc公式

何事も、１次ソースを見ていくのが良いので、まずはハロワキメていきましょう。

= Hello, AsciiDoc!

This is an interactive editor.
Use it to try https://asciidoc.org[AsciiDoc].

== Section Title

* A list item
* Another list item

[,ruby]
--

上記の中身を、test.adocなどの名前でファイルを作っておきます。

VSCode上で、Ctrl+Shift+Pを押してコマンドパレットを開き「ASCIIDOC」を検索します。 Export PDFというような内容が書かれているので押してPDFを出力します。

出力されたPDFはこんな感じです。

その他の書き方はここにある情報などを参考に書けば良いです。

AsciiDoc cheatsheet

Asciidoctor 文法クイックリファレンス(日本語訳)

テンプレート

書籍形式にして、アイコンなどを盛々にして行くような設定例をここに残します。

= タイトル
:author: KENPOS
Update: {docdate}
:toc:
:sectnums: 
:toclevels: 5
:toc-title: Contents
:revdate: 2023/02/26
:revnumber: 0.1
:lang: ja
:doctype: book
:chapter-label:
:chapter-signifier:
:scripts: cjk
:pdf-theme: default-with-font-fallbacks
:sectnumlevels: 4
:toc: left
:experimental:
:figure-caption: Figure.
:table-caption: Table
:listing-caption: List
:example-caption: Example
:note-caption: Note
:tip-caption: Hint
:coution-caption: Coution
:warning-caption: Warning
:important-caption: Important
:version-label: Ver.
:last-update-label: Last Update
:icons: font
:source-highlighter: rouge
:preface-title: Foreword
:appendix-caption: Annex


== Youtubeの動画も貼れる

video::9K7YTzOCGSc[youtube]


== 様々なアイコン例 

NOTE: NOTE

TIP: TIP

IMPORTANT: IMPORTANT

WARNING: WARNING

CAUTION: CAUTION


icon:font[]

icon:fire[] 

icon:hand-stop-o[] 

icon:amazon[]

[aqua]#icon:twitter[]#


== こんな注釈も可能。

--
<1> C言語用の行末吹き出しコメント
<2> Ruby、Python、Perlなどの行末吹き出しコメント
<3> Clojure用の行末吹き出しコメント

このような記載でPDFに出力すると、こんな風に出力されます。