VSCode のAsciiDoc extensionには、クリップボード上の画像を保存し画像の参照記述を挿入する機能1があります。これを利用することで、画像が多い手順書などをスムーズに作成できます。
具体的には、
- スクリーンショットを取る
- 画像を保存する
- AsciiDoc上に画像の参照記述を記載する
という手順の2,3がショットカットキーひとつで済むようになります。
基本的な挙動
AsciiDocファイルを編集中にショートカットを実行すると、
- クリップボード上に保存されている画像がファイルとして保存され、
- カーソルの位置に
image::0-5-2020-13-13-28-PM.png[]のように保存された画像を表示するための記述が挿入される
ショートカットキー
- Macの場合、
Cmd + Alt + v - Winの場合、
Ctr + Alt + v
画像のファイル名
d-M-YYYY-HH-mm-ss-A.png で保存されますが、文字列を選択した状態でショートカットを実行すると、選択した文字列が画像のファイル名になります。
画像ファイルの保存場所
通常、編集中のファイルと同じフォルダに画像ファイルは保存されます。
しかし、imagesdir attributeを設定している場合、画像はそのフォルダに保存されます。
以下の場合、images フォルダに画像が保存されます。
:imagesdir: images
= Title
|
AsciiDocで画像を扱うときの悩ましい所
上記の機能で画像を含むドキュメントの作成はスムーズになりますが、そもそもAsciiDocを複数ファイルに分割管理した場合に、以下の悩ましい問題にぶち当たります。
次のような構造になっているとき、ABC.png はどこにおけばいいでしょうか？
= Top
include::./partial/A.adoc[]
== Aについて
image::ABC.png[]
答えは、top.adoc と同じフォルダです。そうしないと、top.adoc を変換した場合画像が表示されなくなります（include した側のファイルを基準に画像を探しに行きます）。
しかし、この場合 A.adoc 単体で参照すると、画像が表示されなくなってしまいます。編集中に画像を含めた確認をしようとした場合、いちいち top.adoc からする必要がありかなり不便です。
また、せっかく説明した機能で画像挿入をしようとしても、A.adoc のフォルダに画像が保存されてしまいます。
解決方法
いろいろ調べましたが、少しトリッキーな気もしますが以下の方法がベターなのかなと思いました。
- 画像保存用のフォルダ(images)を用意
- 各ファイルに imagesdir を設定する。画像フォルダは各ファイルからの相対パスを記述
- 全体の変換時に imagesdir attributeを設定して変換。画像フォルダはtop.adoc からの相対パスを記述
asciidoctor -a imagesdir=images -D build top.adoc
cp -r images build/images
例
|--top.adoc
|--partial
| |--A.adoc
|--images
|--ABC.png
= Top
include::./partial/A.adoc[]
:imagesdir: ../images
== Aについて
image::ABC.png[]
この方法だと、説明したExtensionの機能も使いつつ個別のファイルごとで画像込みの確認もできるようになります
(top.adoc をVSCodeのプレビューでみると画像は見えなくなりますが、全体の確認は変換したもので確認するのがいいのかなと。。。)
-
Paste Imageという同じ機能を持ったextensionもありますが、画像貼り付けのショートカットキーが同じで競合します。自分の環境では、AsciiDoc extensionが優先されました。 ↩