あまり手間をかけずに手順書や検証エビデンスを残したい

概要

あまり手間をかけずに手順書や検証エビデンスを残したい。
"いまは"これがいいかなと思ったことを書きました。

利用シーンの想定

フォーマットなど決まっていない内部向けの手順書や、簡単な検証結果の記録をするような場合。
手順やエビデンスは、コマンドと画面キャプチャが混在している。
※Windowsの想定。

用意するもの

• Visual Studio Code
  • Markdown All in One
  • Paste Image

出来るようになること

• Visual Studio Code
  • テキストが書ける
  • アドオンが追加できる
• Markdown All in One
  • HTML出力イメージがプレビューできる
  • HTML出力ができる
  • 目次が自動生成できる
• Paste Image
  • キャプチャを直感的に貼り付けることができる

出来るようになること（詳細）

Visual Studio Code

詳しい説明は割愛し、紹介ページを貼るだけにします。

• https://azure.microsoft.com/ja-jp/products/visual-studio-code/

Markdown All in One

HTML出力イメージがプレビューできる

Ctrl + Shift + v でプレビュー表示ができます。
もう一度押すとプレビューが閉じます。
出力イメージの確認に使用できます。

HTML出力ができる

以下の操作をすると、Markdownファイルと同じフォルダにHTMLファイルが出力されます。
1. Ctrl + Shift + P でコマンドパレットを表示
2. html と入力する
3. 候補から、Markdown All in One : Print Current document to HTMLを選択する

ただし、画像のファイルパスがデフォルトだと絶対パスになっているため、このままではほかの人に渡せません。

• HTMLをテキストエディタで確認。絶対パスになっている。

<p><img src="file:///d:\dev\****\****\images\201217-23-07-08.png" alt=""></p>

そのため、面倒ですが以下のように設定を変更します。
1. Ctrl + , で設定画面を開く
2. Absolute Img Path と入力する
3. Convert image path to absolute path のチェックボックスを外す

• HTMLをテキストエディタで確認。相対パスになった。

<p><img src="images/201217-23-07-08.png" alt=""></p>

目次が自動生成できる

画面キャプチャが多くてスクロールが多い手順は、重宝するとおもいます。
以下の操作をすると、カーソルを合わせた位置に目次が生成されます。
1. Ctrl + Shift + p でコマンドパレットを表示
2. toc と入力する
3. 候補から、Markdown All in One : Create Table of Contentsを選択する

Paste Image

キャプチャを直感的に貼り付けることができる

Ctrl + Alt + vでクリップボードのキャプチャを直感的に貼り付けることができます。
実際には、キャプチャを画像として保存して画像のパスをMarkdownに貼り付けています。

画像はMarkdownファイルと同じ階層に出力されます。

また、以下のように設定を変更することで、出力先の指定が可能です。
1. Ctrl + , で設定画面を開く
2. pasteimage.path と入力する
3. Paste Image: Path の値を変更する

※デフォルト:${currentFileDir} となっている。${currentFileDir}/images などとする。

アウトプットイメージ

こういった手順書が作成できます。

※中身はこちらのAsciidoctorインストール手順を使用しました。
https://qiita.com/aki-nasu/items/450fa0f9dc5cdd7f0acb

HTML

Markdown

# Asciidoctorのインストール検証

- [Asciidoctorのインストール検証](#asciidoctorのインストール検証)
  - [Rubyをインストールする](#rubyをインストールする)
    - [Rubyバージョンを確認する](#rubyバージョンを確認する)
    - [Asciidoctorをインストールする](#asciidoctorをインストールする)
    - [実行確認](#実行確認)
      - [sample.adocとして保存](#sampleadocとして保存)
      - [AsciidoctorでHTMLを出力する](#asciidoctorでhtmlを出力する)

## Rubyをインストールする

[Ruby-Install](https://rubyinstaller.org/downloads/)
### Rubyバージョンを確認する
Ruby 2.7.1-1であること。
```
ruby -v
```
![](images\201217-23-04-38.png)
### Asciidoctorをインストールする
gemでAsciidoctorをインストールし、インストールできたことを確認
```
gem install asciidoctor
gem list --local
```
![](images/201217-23-05-28.png)

### 実行確認
実際にHTMLを出力できることを確認
以下の内容をテキストに貼り付けてAsciidoctorのコマンドを実行
#### sample.adocとして保存
```
== レベル 1
Text.

=== レベル 2
Text.

==== レベル 3
Text.

===== レベル 4
Text.

.データ形式はCSV, 各カラム幅は表示域の15% (60 ÷ 4 = 15)
[format="csv",width="60%",cols="4"]
[frame="topbot",grid="none"]
|======
1,2,3,4
a,b,c,d
A,B,C,D
|======
```

#### AsciidoctorでHTMLを出力する
```
asciidoctor sample.adoc
```
![](images/201217-23-07-08.png)

おわりに

ちなみにこの記事は、HackMDで書きました。
公開していいものは、HackMDをオススメします。

あわせて読みたい・・
CodiMDによるドキュメント作成のすすめ