AsciiDoc + VSCodeでかっこいい文書作る
某方に布教されてAsciiDocにめっちゃハマった。
AsciiDocって
markdownより優れている点
- markdownより高機能。
- 困ったらHTMLタグ直書きとかしなくていい。
- 表セルを結合出来る。
- ソースコード、PlantUMLなどをincludeできる。
- 目次が自動で作られる。
- 使用可能なアイコンが大量にある。
- PDF書き出しした時の見た目が安定&綺麗。
(plantUMLについては過去記事参照)
markdownに劣る点
- 環境構築がダルい
- 普及してない
- はてなブログがasciidocに対応していない
環境構築
- ruby installerをDLし、実行環境を整える
- asciidoctorとエクステンションを追加する
- 以下をコマンドプロンプトで実行
- asciidoctor-diagramはplantUML等をasciidocで利用するためのエクステンション
- asciidoctor-pdfはPDF変換に必要。
gem install asciidoctor
gem install asciidoctor-diagram
gem install --pre asciidoctor-pdf
"AsciiDoc.use_asciidoctor_js": false, "AsciiDoc.asciidoctor_command": "asciidoctor -a outdir=tmp -a imagesdir=tmp -a imagesoutdir=tmp -r asciidoctor-diagram -o-",
これで環境構築完了。.adocフォルダを作って編集していく。
ctrl + K + V もしくは Ctrl + Shift + P → AsciiDoc: Open preview to the side でサイドパネルにリアルタイムプレビューが表示される。
HTML&PDF書き出し
- HTMLに書き出す時
asciidoctor [ファイル名].adoc
- PDFに書き出す時
asciidoctor-pdf [ファイル名].adoc
- asciidoctor-pdf等を使う時
asciidoctor -r asciidoctor-diagram [ファイル名].adoc asciidoctor-pdf -r asciidoctor-diagram [ファイル名].adoc
文法
ここで説明するより既にあるリファレンスを見てもらうほうが確実。
- 超基本的な機能に絞って紹介されている記事
- 公式リファレンス
iconについて
- 冒頭に
:icons: fontを追加すればアイコンが使用できる。
NOTE: NOTE TIP: TIP IMPORTANT: IMPORTANT WARNING: WARNING CAUTION: CAUTION
レンダリング結果
- 他にも色々なアイコンが使用できる。有名企業のアイコンもある。
icon:font[] icon:fire[] icon:hand-stop-o[] icon:amazon[] [aqua]#icon:twitter[]#
レンダリング結果
- 使えるフォントはFont-Awesomeに依存。以下のサイトで調べることが出来る。
Icons from Font Awesome, Bootstrap and Google
HTML/PDF書き出しのテーマの変更
- 書き出し時、ヘッダーフッターを設定したり、文字のフォーマットを指定したり、色々な事ができる。
- PDF書き出しのフォーマットを変更したければ、デフォルト設定なら以下のテーマを書き換えることで実現。
C:\Ruby25-x64\lib\ruby\gems\2.5.0\gems\asciidoctor-pdf-1.5.0.alpha.16\data\themes - 参考サイト
- PDF書き出しのフォーマットを変更したければ、デフォルト設定なら以下のテーマを書き換えることで実現。
